# lilio: Calendar generator for machine learning with timeseries data
<img align="right" width="160" alt="Logo" src="https://raw.githubusercontent.com/AI4S2S/lilio/main/docs/assets/images/lilio_logo.png">
<!--[](https://github.com/AI4S2S/lilio) -->
[](https://github.com/AI4S2S/lilio)
[](https://research-software-directory.org/software/lilio)
[](https://zenodo.org/badge/latestdoi/588084019)
[](https://api.eu.badgr.io/public/assertions/P3scOSLyQVWzzsjq0Ueycw "SQAaaS gold badge achieved")
[](https://fair-software.eu)
[](https://lilio.readthedocs.io/en/stable/?badge=stable)
[](https://github.com/AI4S2S/lilio/actions/workflows/build.yml)
[](https://sonarcloud.io/dashboard?id=AI4S2S_lilio)
<!--[](https://github.com/AI4S2S/lilio/actions/workflows/sonarcloud.yml) -->
A python package for generating calendars to resample timeseries into training and target data for machine learning. Named after [the inventor](https://en.wikipedia.org/wiki/Aloysius_Lilius) of the [Gregorian Calendar](https://en.wikipedia.org/wiki/Gregorian_calendar).
Lilio was originally designed for use in [`s2spy`](https://github.com/AI4S2S/s2spy), a high-level python package integrating expert knowledge and artificial intelligence to boost (sub) seasonal forecasting.
## Installation
[](https://pypi.python.org/project/lilio/)
[](https://pypi.python.org/project/lilio/)
[](https://anaconda.org/conda-forge/lilio)
To install the latest release of lilio, do:
```console
python3 -m pip install lilio
```
Lilio is also available on conda-forge. If you use conda, do:
```console
conda install -c conda-forge lilio
```
To install the in-development version from the GitHub repository, do:
```console
python3 -m pip install git+https://github.com/AI4S2S/lilio.git
```
### Configure the package for development and testing
A more extensive developer guide can be found [here](./docs/README.dev.md).
The testing framework used here is [pytest](https://pytest.org). Before running the test, we get a local copy of the source code and install `lilio` via the command:
```py
git clone https://github.com/AI4S2S/lilio.git
cd lilio
python3 -m pip install -e .[dev]
```
Then, run tests:
```py
hatch run test
```
## How the lilio calendars work
In Lilio, calendars are 2-dimensional. Each row (year) represents a unique
observation, whereas each column corresponds to a precursor period with a
certain lag. This is how we like to structure our data for ML applications.
We define the "anchor date" to be between the target and precursor periods
(strictly speaking, it is the start of the first target interval). All other
intervals are expressed as offsets to this anchor date. Conveniently, this
eliminates any ambiguity related to leap years.
Here's a calendar generated with Lilio:
```py
>>> calendar = lilio.daily_calendar(anchor="11-30", length='180d')
>>> calendar = calendar.map_years(2020, 2021)
>>> calendar.show()
i_interval -1 1
anchor_year
2021 [2021-06-03, 2021-11-30) [2021-11-30, 2022-05-29)
2020 [2020-06-03, 2020-11-30) [2020-11-30, 2021-05-29)
```
Now, the user can load the data `input_data` (e.g. `pandas` `DataFrame`) and resample it to the desired timescales configured in the calendar:
```py
>>> calendar = calendar.map_to_data(input_data)
>>> bins = lilio.resample(calendar, input_data)
>>> bins
anchor_year i_interval interval mean_data target
0 2020 -1 [2020-06-03, 2020-11-30) 275.5 True
1 2020 1 [2020-11-30, 2021-05-29) 95.5 False
2 2021 -1 [2021-06-03, 2021-11-30) 640.5 True
3 2021 1 [2021-11-30, 2022-05-29) 460.5 False
```
For convenience, Lilio offers a few shorthands for standard of calendars e.g.
[`monthly_calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar_shorthands/index.html#lilio.calendar_shorthands.monthly_calendar)
and
[`weekly_calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar_shorthands/index.html#lilio.calendar_shorthands.weekly_calendar).
However, you can also create custom calendars by calling
[`Calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar/index.html#lilio.calendar.Calendar)
directly. For a nice walkthrough, see [this example
notebook](https://lilio.readthedocs.io/en/latest/notebooks/all_about_the_calendar.html).
<!---
## Tutorials
`lilio` supports operations that are common in a machine learning pipeline of sub-seasonal to seasonal forecasting research. Tutorials covering supported methods and functionalities are listed in [notebooks](https://github.com/AI4S2S/lilio/tree/main/notebooks). To check these notebooks, users need to install [`Jupyter lab`](https://jupyter.org/). More details about each method can be found in this [API reference documentation](https://ai4s2s.readthedocs.io/en/latest/autoapi/index.html).
-->
## Documentation
[](https://lilio.readthedocs.io/en/latest/?badge=latest)
For detailed information on using `lilio` package, visit the [documentation page](https://lilio.readthedocs.io/en/latest/) hosted at Readthedocs.
## Contributing
If you want to contribute to the development of lilio,
have a look at the [contribution guidelines](docs/CONTRIBUTING.md).
## How to cite us
[](https://research-software-directory.org/software/lilio)
[](https://zenodo.org/badge/latestdoi/588084019)
Please use the Zenodo DOI to cite this package if you used it in your research.
## Acknowledgements
This package was developed by the Netherlands eScience Center and Vrije Universiteit Amsterdam under Netherlands eScience Center grant NLESC.OEC.2021.005.
The package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [NLeSC/python-template](https://github.com/NLeSC/python-template).
Raw data
{
"_id": null,
"home_page": null,
"name": "lilio",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": "Claire Donnelly <c.donnelly@esciencecenter.nl>, Yang Liu <y.liu@esciencecenter.nl>, Bart Schilperoort <b.schilperoort@esciencecenter.nl>, Peter Kalverla <p.kalvera@esciencecenter.nl>, Jannes van Ingen <jannes.van.ingen@s2s-ai.com>, Sem Vijverberg <sem.vijverberg@vu.nl>",
"keywords": "calendar, calendar generation, calendar maker, machine learning, timeseries analysis",
"author": "Claire Donnelly, Yang Liu, Bart Schilperoort, Peter Kalverla, Jannes van Ingen, Sem Vijverberg",
"author_email": "c.donnelly@esciencecenter.nl",
"download_url": "https://files.pythonhosted.org/packages/b4/64/f3a1622e02425b3b4a6752249c1dcd194950e349a3691f384b861c88f164/lilio-0.5.0.tar.gz",
"platform": null,
"description": "# lilio: Calendar generator for machine learning with timeseries data\n\n<img align=\"right\" width=\"160\" alt=\"Logo\" src=\"https://raw.githubusercontent.com/AI4S2S/lilio/main/docs/assets/images/lilio_logo.png\">\n\n\n<!--[](https://github.com/AI4S2S/lilio) -->\n[](https://github.com/AI4S2S/lilio)\n[](https://research-software-directory.org/software/lilio)\n[](https://zenodo.org/badge/latestdoi/588084019)\n[](https://api.eu.badgr.io/public/assertions/P3scOSLyQVWzzsjq0Ueycw \"SQAaaS gold badge achieved\")\n[](https://fair-software.eu)\n[](https://lilio.readthedocs.io/en/stable/?badge=stable)\n[](https://github.com/AI4S2S/lilio/actions/workflows/build.yml)\n[](https://sonarcloud.io/dashboard?id=AI4S2S_lilio)\n<!--[](https://github.com/AI4S2S/lilio/actions/workflows/sonarcloud.yml) -->\n\nA python package for generating calendars to resample timeseries into training and target data for machine learning. Named after [the inventor](https://en.wikipedia.org/wiki/Aloysius_Lilius) of the [Gregorian Calendar](https://en.wikipedia.org/wiki/Gregorian_calendar).\n\nLilio was originally designed for use in [`s2spy`](https://github.com/AI4S2S/s2spy), a high-level python package integrating expert knowledge and artificial intelligence to boost (sub) seasonal forecasting.\n\n## Installation\n[](https://pypi.python.org/project/lilio/)\n[](https://pypi.python.org/project/lilio/)\n[](https://anaconda.org/conda-forge/lilio)\n\nTo install the latest release of lilio, do:\n```console\npython3 -m pip install lilio\n```\n\nLilio is also available on conda-forge. If you use conda, do:\n```console\nconda install -c conda-forge lilio\n```\n\nTo install the in-development version from the GitHub repository, do:\n\n```console\npython3 -m pip install git+https://github.com/AI4S2S/lilio.git\n```\n\n### Configure the package for development and testing\nA more extensive developer guide can be found [here](./docs/README.dev.md).\n\nThe testing framework used here is [pytest](https://pytest.org). Before running the test, we get a local copy of the source code and install `lilio` via the command:\n\n```py\ngit clone https://github.com/AI4S2S/lilio.git\ncd lilio\npython3 -m pip install -e .[dev]\n```\n\nThen, run tests:\n```py\nhatch run test\n```\n\n## How the lilio calendars work\n\nIn Lilio, calendars are 2-dimensional. Each row (year) represents a unique\nobservation, whereas each column corresponds to a precursor period with a\ncertain lag. This is how we like to structure our data for ML applications.\n\n\n\nWe define the \"anchor date\" to be between the target and precursor periods\n(strictly speaking, it is the start of the first target interval). All other\nintervals are expressed as offsets to this anchor date. Conveniently, this\neliminates any ambiguity related to leap years.\n\nHere's a calendar generated with Lilio:\n\n```py\n>>> calendar = lilio.daily_calendar(anchor=\"11-30\", length='180d')\n>>> calendar = calendar.map_years(2020, 2021)\n>>> calendar.show()\ni_interval -1 1\nanchor_year\n2021 [2021-06-03, 2021-11-30) [2021-11-30, 2022-05-29)\n2020 [2020-06-03, 2020-11-30) [2020-11-30, 2021-05-29)\n```\n\nNow, the user can load the data `input_data` (e.g. `pandas` `DataFrame`) and resample it to the desired timescales configured in the calendar:\n\n```py\n>>> calendar = calendar.map_to_data(input_data)\n>>> bins = lilio.resample(calendar, input_data)\n>>> bins\n anchor_year i_interval interval mean_data target\n0 2020 -1 [2020-06-03, 2020-11-30) 275.5 True\n1 2020 1 [2020-11-30, 2021-05-29) 95.5 False\n2 2021 -1 [2021-06-03, 2021-11-30) 640.5 True\n3 2021 1 [2021-11-30, 2022-05-29) 460.5 False\n```\n\nFor convenience, Lilio offers a few shorthands for standard of calendars e.g.\n[`monthly_calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar_shorthands/index.html#lilio.calendar_shorthands.monthly_calendar)\nand\n[`weekly_calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar_shorthands/index.html#lilio.calendar_shorthands.weekly_calendar).\nHowever, you can also create custom calendars by calling\n[`Calendar`](https://lilio.readthedocs.io/en/latest/autoapi/lilio/calendar/index.html#lilio.calendar.Calendar)\ndirectly. For a nice walkthrough, see [this example\nnotebook](https://lilio.readthedocs.io/en/latest/notebooks/all_about_the_calendar.html).\n\n<!---\n## Tutorials\n`lilio` supports operations that are common in a machine learning pipeline of sub-seasonal to seasonal forecasting research. Tutorials covering supported methods and functionalities are listed in [notebooks](https://github.com/AI4S2S/lilio/tree/main/notebooks). To check these notebooks, users need to install [`Jupyter lab`](https://jupyter.org/). More details about each method can be found in this [API reference documentation](https://ai4s2s.readthedocs.io/en/latest/autoapi/index.html).\n\n-->\n## Documentation\n[](https://lilio.readthedocs.io/en/latest/?badge=latest)\n\nFor detailed information on using `lilio` package, visit the [documentation page](https://lilio.readthedocs.io/en/latest/) hosted at Readthedocs.\n\n## Contributing\n\nIf you want to contribute to the development of lilio,\nhave a look at the [contribution guidelines](docs/CONTRIBUTING.md).\n\n## How to cite us\n[](https://research-software-directory.org/software/lilio)\n[](https://zenodo.org/badge/latestdoi/588084019)\n\nPlease use the Zenodo DOI to cite this package if you used it in your research.\n\n## Acknowledgements\nThis package was developed by the Netherlands eScience Center and Vrije Universiteit Amsterdam under Netherlands eScience Center grant NLESC.OEC.2021.005.\n\nThe package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [NLeSC/python-template](https://github.com/NLeSC/python-template).\n",
"bugtrack_url": null,
"license": null,
"summary": "python package for generating calendars for machine learning timeseries analysis.",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [
"calendar",
" calendar generation",
" calendar maker",
" machine learning",
" timeseries analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "388050482dafd6ba4fafec32177325ac5532e0180bb76300229d50a2c70c23e2",
"md5": "5b115eb1e4098a9a6891f9fa56bb8e48",
"sha256": "ecd20ee3285c52dc0e8bd7dde8a103fc76ae32c63696ee68d81e0fabf5001637"
},
"downloads": -1,
"filename": "lilio-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b115eb1e4098a9a6891f9fa56bb8e48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 34767,
"upload_time": "2024-06-11T09:20:00",
"upload_time_iso_8601": "2024-06-11T09:20:00.481082Z",
"url": "https://files.pythonhosted.org/packages/38/80/50482dafd6ba4fafec32177325ac5532e0180bb76300229d50a2c70c23e2/lilio-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b464f3a1622e02425b3b4a6752249c1dcd194950e349a3691f384b861c88f164",
"md5": "436a910fa30feae97f747fb4ce8fa2de",
"sha256": "75e0a4cc46ed998cf072295c1188e11b61e194290f201dfc0ebeb95b1a1daadd"
},
"downloads": -1,
"filename": "lilio-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "436a910fa30feae97f747fb4ce8fa2de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 1819070,
"upload_time": "2024-06-11T09:20:03",
"upload_time_iso_8601": "2024-06-11T09:20:03.719707Z",
"url": "https://files.pythonhosted.org/packages/b4/64/f3a1622e02425b3b4a6752249c1dcd194950e349a3691f384b861c88f164/lilio-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-11 09:20:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lilio"
}
JSON