lilio.calendar_shifter

Calendar shifter to create staggered calendars.

Module Contents

lilio.calendar_shifter.calendar_shifter(calendar: calendar_shifter.calendar, shift: str | dict) → calendar_shifter.calendar

Shift a Calendar instance by a given time offset.

Instead of shifting the anchor date, this function shifts two things in reference to the anchor date:

target period(s): as a gap between the anchor date and the start of the first

target period

precursor period(s): as a gap between the anchor date and the start of the

first precursor period

This way, the anchor year from the input calendar is maintained on the returned calendar. This is important for train-test splitting at later stages.

Parameters:

• calendar – a lilio.Calendar instance

• shift – 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}

Example

Shift a calendar by a given dateoffset.

>>> import lilio
>>> cal = lilio.Calendar(anchor="07-01")
>>> cal.add_intervals("target", "7d")
>>> cal.add_intervals("precursor", "7d", gap="14d")
>>> cal.add_intervals("precursor", "7d", n=3)
>>> cal_shifted = lilio.calendar_shifter.calendar_shifter(cal, "7d")
>>> cal_shifted  
Calendar(
    anchor='07-01',
    allow_overlap=False,
    mapping=None,
    intervals=[
        Interval(role='target', length='7d', gap={'days': 7}),
        Interval(role='precursor', length='7d', gap={'days': 7}),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d')
    ]
)

lilio.calendar_shifter.staggered_calendar(calendar: staggered_calendar.calendar, shift: str | dict, n_shifts: int) → list[staggered_calendar.calendar]

Create a staggered calendar list by shifting a calendar by an offset n-times.

Parameters:

• calendar – an lilio.Calendar instance

• shift – 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}

• n_shifts – strictly positive integer for the number of shifts

Example

Shift an input calendar n times by a given dateoffset and return a list of these shifted calendars.

>>> import lilio
>>> cal = lilio.Calendar(anchor="07-01")
>>> cal.add_intervals("target", "7d")
>>> cal.add_intervals("precursor", "7d", gap="14d")
>>> cal.add_intervals("precursor", "7d", n=3)
>>> cal_shifted = lilio.calendar_shifter.staggered_calendar(cal, "7d", 1)
>>> cal_shifted  
[Calendar(
    anchor='07-01',
    allow_overlap=False,
    mapping=None,
    intervals=[
        Interval(role='target', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='14d'),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d')
    ]
),
Calendar(
    anchor='07-01',
    allow_overlap=False,
    mapping=None,
    intervals=[
        Interval(role='target', length='7d', gap={'days': 7}),
        Interval(role='precursor', length='7d', gap={'days': 7}),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d'),
        Interval(role='precursor', length='7d', gap='0d')
    ]
)]

lilio.calendar_shifter.calendar_list_resampler(cal_list: list, ds: xarray.Dataset, dim_name: str = 'step') → xarray.Dataset

Return a dataset, resampled to every calendar in a list of calendars.

The resampled calendars will be concatenated along a new dimension (with the default name ‘step’) into a single xarray Dataset.

Parameters:

• cal_list – List of calendars.

• ds – Dataset to resample.

• dim_name – The name of the new dimension that will be added to the output dataset.

Returns:

Resampled xr.Dataset