Skip to main content

python package for generating calendars for machine learning timeseries analysis.

Project description

lilio: Calendar generator for machine learning with timeseries data

Logo

github license badge rsd badge DOI SQAaaS badge shields.io fair-software.eu Documentation Status build workflow scc badge

A python package for generating calendars to resample timeseries into training and target data for machine learning. Named after the inventor of the Gregorian Calendar.

Lilio was originally designed for use in s2spy, a high-level python package integrating expert knowledge and artificial intelligence to boost (sub) seasonal forecasting.

Installation

workflow pypi badge supported python versions conda-forge

To install the latest release of lilio, do:

python3 -m pip install lilio

Lilio is also available on conda-forge. If you use conda, do:

conda install -c conda-forge lilio

To install the in-development version from the GitHub repository, do:

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.

The testing framework used here is pytest. Before running the test, we get a local copy of the source code and install lilio via the command:

git clone https://github.com/AI4S2S/lilio.git
cd lilio
python3 -m pip install -e .[dev]

Then, run tests:

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.

Conceptual illustration of Lilio Calendar

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:

>>> 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:

>>> 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 and weekly_calendar. However, you can also create custom calendars by calling Calendar directly. For a nice walkthrough, see this example notebook.

Documentation

Documentation Status

For detailed information on using lilio package, visit the documentation page hosted at Readthedocs.

Contributing

If you want to contribute to the development of lilio, have a look at the contribution guidelines.

How to cite us

rsd badge DOI

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 and the NLeSC/python-template.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lilio-0.5.0.tar.gz (1.8 MB view details)

Uploaded Source

Built Distribution

lilio-0.5.0-py3-none-any.whl (34.8 kB view details)

Uploaded Python 3

File details

Details for the file lilio-0.5.0.tar.gz.

File metadata

  • Download URL: lilio-0.5.0.tar.gz
  • Upload date:
  • Size: 1.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.9.19

File hashes

Hashes for lilio-0.5.0.tar.gz
Algorithm Hash digest
SHA256 75e0a4cc46ed998cf072295c1188e11b61e194290f201dfc0ebeb95b1a1daadd
MD5 436a910fa30feae97f747fb4ce8fa2de
BLAKE2b-256 b464f3a1622e02425b3b4a6752249c1dcd194950e349a3691f384b861c88f164

See more details on using hashes here.

File details

Details for the file lilio-0.5.0-py3-none-any.whl.

File metadata

  • Download URL: lilio-0.5.0-py3-none-any.whl
  • Upload date:
  • Size: 34.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.9.19

File hashes

Hashes for lilio-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ecd20ee3285c52dc0e8bd7dde8a103fc76ae32c63696ee68d81e0fabf5001637
MD5 5b115eb1e4098a9a6891f9fa56bb8e48
BLAKE2b-256 388050482dafd6ba4fafec32177325ac5532e0180bb76300229d50a2c70c23e2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page