python package for generating calendars for machine learning timeseries analysis.
Project description
lilio: Calendar generator for machine learning with timeseries data
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
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.
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
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
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 75e0a4cc46ed998cf072295c1188e11b61e194290f201dfc0ebeb95b1a1daadd |
|
MD5 | 436a910fa30feae97f747fb4ce8fa2de |
|
BLAKE2b-256 | b464f3a1622e02425b3b4a6752249c1dcd194950e349a3691f384b861c88f164 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | ecd20ee3285c52dc0e8bd7dde8a103fc76ae32c63696ee68d81e0fabf5001637 |
|
MD5 | 5b115eb1e4098a9a6891f9fa56bb8e48 |
|
BLAKE2b-256 | 388050482dafd6ba4fafec32177325ac5532e0180bb76300229d50a2c70c23e2 |