lilio.calendarο
Lilioβs main Calendar module.
Module Contentsο
- class lilio.calendar.Interval(role: Literal['target', 'precursor'], length: str | dict, gap: str | dict = '0d')[source]ο
Basic construction element of calendar for defining precursors and targets.
Construct the basic element of the calendar.
The Interval is characterised by its type (either target or precursor), its length and the gap between it and the previous interval of its type (or the anchor date, if the interval is the first target/first precursor).
- Parameters:
role β The type of interval. Either βtargetβ or βprecursorβ.
length β The length of the interval. This can either be a pandas-like frequency string (e.g. β10dβ, β2Wβ, or β3Mβ), or a pandas.DateOffset compatible dictionary such as {days=10}, {weeks=2}, or {months=1, weeks=2}.
gap β The gap between the previous interval and this interval. Valid inputs are the same as the length keyword argument. Defaults to β0dβ.
Example
>>> from lilio import Interval >>> iv = Interval("target", length="7d") >>> iv Interval(role='target', length='7d', gap='0d')
You can modify the intervalβs properties in-place:
>>> iv.gap = "1W" >>> iv Interval(role='target', length='7d', gap='1W')
- class lilio.calendar.Calendar(anchor: str, allow_overlap: bool = False, mapping: None | _MappingYears | _MappingData | _MappingDataGreedy = None, intervals: None | list[Interval] = None)[source]ο
Build a calendar from scratch with basic construction elements.
Instantiate a basic container for building calendar using basic blocks.
This is a highly flexible calendar which allows the user to build their own calendar with the basic building blocks of target and precursor periods.
Users have the freedom to create calendar with customized intervals, gap between intervals, and even overlapped intervals. They need to manage the calendar themselves.
Some shorthand calendars, such as a daily_calendar, weekly_calendar and monthly_calendar are available in lilio.calendar_shorthands. These can be used to easily construct basic calendars with only a few parameters, but do not have the flexibility that this calendar builder module provides.
- Parameters:
anchor β
String denoting the anchor date. The following inputs are valid: - βMM-DDβ for a month and day. E.g. β12-31β. - βMMβ for only a month, e.g. β4β for March. - English names and abbreviations of months. E.g. βDecemberβ or
βjanβ.
- βWwwβ for a week number, e.g. βW05β for the fifth week of the
year.
- βWww-Dβ for a week number plus day of week. E.g. βW01-4β for the
first thursday of the year.
allow_overlap β If overlapping intervals between years is allowed or not. Default behaviour is False, which means that anchor years will be skipped to avoid data being shared between anchor years.
mapping β Calendar mapping. Input in the form: (βyearsβ, 2000, 2020) or (βdataβ, pd.Timestamp(β2000-01-01β), pd.Timestamp(β2020-01-01β)). The calendar mapping is usually set with the map_years or map_to_data methods.
intervals β A list of Interval objects that should be appended to the calendar when it is initialized.
Example
Instantiate a custom calendar and appending target/precursor periods.
>>> import lilio >>> calendar = lilio.Calendar(anchor="12-31") >>> calendar Calendar( anchor='12-31', allow_overlap=False, mapping=None, intervals=None )
- property allow_overlap[source]ο
- if overlapping intervals are allowed or not.
- Type:
Returns the allow_overlap
- property mapping: None | Literal['years', 'data', 'data-greedy'][source]ο
Return the mapping of the calendar. Either None, βyearsβ, or βdataβ.
- add_intervals(role: Literal['target', 'precursor'], length: str, gap: str = '0d', n: int = 1) None [source]ο
Add one or more intervals to the calendar.
The interval can be a target or a precursor, and can be defined by its length, a possible gap between this interval and the preceding interval.
- Parameters:
role β Either a βtargetβ or βprecursorβ interval(s).
length β The length of the interval(s), in a format of β5dβ for five days, β2Wβ for two weeks, or β1Mβ for one month.
gap β The gap between this interval and the preceding target/precursor interval. Same format as the length argument.
n β The number of intervals which should be added to the calendar. Defaults to 1.
- map_years(start: int, end: int)[source]ο
Add a start and end year mapping to the calendar.
If the start and end years are the same, the intervals for only that single year are returned by calendar.get_intervals().
- Parameters:
start β The first year for which the calendar will be realized
end β The last year for which the calendar will be realized
- Returns:
The calendar mapped to the input start and end year.
- map_to_data(input_data: pandas.Series | pandas.DataFrame | xarray.Dataset | xarray.DataArray, safe: bool = True)[source]ο
Map the calendar to input data period.
Stores the first and last intervals of the input data to the calendar, so that the intervals can cover the data to the greatest extent.
- Parameters:
input_data β Input data for datetime mapping. Its index must be either pandas.DatetimeIndex, or an xarray time coordinate with datetime data.
safe β bool describing if data should be mapped in safe (makes sure intervals are data-filled) or greedy mode (interval created if there is any data), safe is default.
- Returns:
The calendar mapped to the input data period.
- get_intervals() pandas.DataFrame [source]ο
Retrieve updated intervals from the Calendar object.
- show() pandas.DataFrame [source]ο
Display the intervals the Calendar will generate for the current setup.
- Returns:
Dataframe containing the calendar intervals.
- Return type:
pd.Dataframe
- visualize(n_years: int = 3, interactive: bool = False, relative_dates: bool = False, show_length: bool = False, add_legend: bool = True, ax=None, **bokeh_kwargs) None [source]ο
Plot a visualization of the current calendar setup, to aid in user setup.
Note: The interactive visualization requires the bokeh package to be installed in the active Python environment.
- Parameters:
n_years β Sets the maximum number of anchor years that should be shown. By default only the most recent 3 are visualized, to ensure that they fit within the plot.
interactive β If False, matplotlib will be used for the visualization. If True, bokeh will be used.
relative_dates β Toggles if the intervals should be displayed relative to the anchor date, or as absolute dates.
show_length β Toggles if the frequency of the intervals should be displayed. Defaults to False (Matplotlib plotter only).
add_legend β Toggles if a legend should be added to the plot (Matplotlib only)
ax β Matplotlib axis object to plot the visualization into.
**bokeh_kwargs β Keyword arguments to pass to Bokehβs plotting.figure. See https://docs.bokeh.org/en/latest/docs/reference/plotting/figure.html for a list of possible keyword arguments.
- property flat: pandas.DataFrame[source]ο
Returns the flattened intervals.