{"id":18709139,"url":"https://github.com/jojoee/cyclical","last_synced_at":"2025-04-12T10:35:08.636Z","repository":{"id":62566150,"uuid":"309023068","full_name":"jojoee/cyclical","owner":"jojoee","description":"Encode item list into \"cyclical\"","archived":false,"fork":false,"pushed_at":"2023-08-27T13:44:48.000Z","size":45,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-09T16:37:25.503Z","etag":null,"topics":["cyclic","cyclical","normalization","normalize"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/cyclical/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jojoee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-01T04:30:28.000Z","updated_at":"2023-08-27T13:45:57.000Z","dependencies_parsed_at":"2022-11-03T16:00:19.391Z","dependency_job_id":null,"html_url":"https://github.com/jojoee/cyclical","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jojoee%2Fcyclical","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jojoee%2Fcyclical/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jojoee%2Fcyclical/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jojoee%2Fcyclical/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jojoee","download_url":"https://codeload.github.com/jojoee/cyclical/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223512344,"owners_count":17157744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cyclic","cyclical","normalization","normalize"],"created_at":"2024-11-07T12:26:28.509Z","updated_at":"2024-11-07T12:26:29.117Z","avatar_url":"https://github.com/jojoee.png","language":"Python","readme":"# Cyclical\n\n[![continuous integration](https://github.com/jojoee/cyclical/workflows/continuous%20integration/badge.svg?branch=master)](https://github.com/jojoee/cyclical/actions/workflows/continuous-integration.yml)\n[![continuous delivery](https://github.com/jojoee/cyclical/workflows/continuous%20delivery/badge.svg?branch=master)](https://github.com/jojoee/cyclical/actions/workflows/continuous-delivery.yml)\n\n[![PyPI version fury.io](https://badge.fury.io/py/cyclical.svg)](https://pypi.python.org/pypi/cyclical/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![codecov](https://codecov.io/gh/jojoee/cyclical/branch/master/graph/badge.svg)](https://codecov.io/gh/jojoee/cyclical)\n\nEncode item list into \"cyclical\"\n\n## Installation\n\n```\npip install cyclical\n\n# or\ngit clone https://github.com/jojoee/cyclical\ncd cyclical\npython setup.py install\n```\n\n## Usage\n\n```python\nfrom cyclical import cyclical\n\nn_rows = 1000\nn_hrs = 24\nhrs = [item % n_hrs for item in list(range(0, n_rows, 1))]\nencoded_hrs = cyclical.encode(hrs, n_hrs)\nprint(encoded_hrs)\n\n\"\"\"\n([0.0, 0.25881904510252074, 0.49999999999999994, 0.7071067811865476, 0.8660254037844386,\n0.9659258262890682, 1.0, 0.9659258262890683, 0.8660254037844387, 0.7071067811865476,\n0.5000000000000003, 0.258819045102521, 1.2246467991473532e-16, -0.25881904510252035,\n-0.4999999999999997, ...\n\"\"\"\n```\n\n## Real use case\n\nTLTR: normalize cyclical data (e.g. month number [0-11], hour number [0, 23]) by mapping them into sin and cos of 1-radius-circle\n\n2 years ago while I was doing the “ocean current prediction model”. From the background knowledge of its nature which the ocean current has a strong relation with wind speed and wind speed also based on the season. So, I try to give the model “month number” which starts with 0 and ends with 11.\n\nWith the deep learning model, I have to normalize data into [0, 1] which 1 refers to the maximum magnitude. There have many ways to normalize data such as min/max, mean/std, and other normalization but it can’t apply to this “month number” data.\n\n“Month number” has a cyclical characteristic, so month-number-11 can’t be compared with month-number-0 as it showed, Thus I have to represent “month number” with other normalization method instead which is “cyclical” in this module.\n\n```python\nimport pandas as pd\nfrom cyclical import cyclical\nimport math\nimport matplotlib.pyplot as plt\n%matplotlib inline\n\nn_rows = 1000\nn_hrs = 24\nhrs = [item % n_hrs for item in list(range(0, n_rows, 1))]\nencoded_hrs = cyclical.encode(hrs, n_hrs)\n# print(encoded_hrs)\n\nn_months = 12\nmonths = [item % n_months for item in list(range(0, n_rows, 1))]\nencoded_months = cyclical.encode(months, n_months)\n\n# datframe\ndf = pd.DataFrame({\n    # hr\n    'hr_sin': encoded_hrs[0],\n    'hr_cos': encoded_hrs[1],\n\n    # month\n    'month_sin': encoded_months[0],\n    'month_cos': encoded_months[1],\n})\ndisplay(df)\n\n# plot\nn_samples = math.floor(n_rows * 0.1)\ndf.sample(n_samples).plot.scatter('hr_sin', 'hr_cos').set_aspect('equal')\nplt.show()\n\n# plot\ndf.sample(n_samples).plot.scatter('month_sin', 'month_cos').set_aspect('equal')\nplt.show()\n```\n\n![example-df](https://raw.githack.com/jojoee/cyclical/master/example/example-df.png)\n\n![hour-number](https://raw.githack.com/jojoee/cyclical/master/example/hour-number.png)\n![month-number](https://raw.githack.com/jojoee/cyclical/master/example/month-number.png)\n\n## Reference\n- [Encoding cyclical continuous features - 24-hour time](https://ianlondon.github.io/blog/encoding-cyclical-features-24hour-time/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjojoee%2Fcyclical","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjojoee%2Fcyclical","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjojoee%2Fcyclical/lists"}