Conversions

Move data between datetimes and calendars, and between calendars.

datetime_to_timeslice

datetime_to_timeslice(
    dtm: Any,
    calendar: Calendar,
    alignment: str | Mapping[str, str] | None = None,
) -> list

The leaf timeslice each datetime falls in (None where none does).

The calendar's utc_offset_minutes shifts the instants first; year_start anchors YDAY and YEAR. alignment overrides how instants beyond a vocabulary map (one rule, or a mapping per timeframe).

tsl2dtm

tsl2dtm(
    tsl: Any,
    calendar: Any,
    year: Any,
    tz: str = "UTC",
    alignment: Any = None,
) -> pa.Array

The instant each timeslice starts at, in year (one, or one per timeslice). A sampled calendar is dated against its parent.

dtm2tsl

dtm2tsl(
    dtm: Any, calendar: Any, alignment: Any = None
) -> list

The timeslice each datetime falls in.

tsl2hour

tsl2hour(tsl: Any, calendar: Any) -> list

Hour of day (0-23) of each timeslice.

tsl2yday

tsl2yday(tsl: Any, calendar: Any) -> list

Day of year of each timeslice.

tsl2month

tsl2month(
    tsl: Any, calendar: Any, year: Any = None
) -> list

Month (1-12) of each timeslice.

hour2HOUR

hour2HOUR(x: Any, calendar: Any = None) -> list

Hours (0-23) as HOUR labels.

yday2YDAY

yday2YDAY(x: Any, calendar: Any = None) -> list

Days of year as YDAY labels.

expand_calendar

expand_calendar(
    x: Calendar,
    year: Any,
    by: object = None,
    tz: str = "UTC",
    alignment: str | Mapping[str, str] | None = None,
) -> pa.Table

The model year(s) as a datetime grid labelled with timeslices: columns datetime, year, timeslice.

recast_calendar

recast_calendar(
    x: Any,
    source: Calendar,
    target: Calendar | str,
    year: int,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    na_action: NaAction = "drop",
    parent: Calendar | str | None = None,
    collect: bool | None = None,
) -> Any

Recast timeslice data from one calendar to another (or to a timeframe of the same calendar) through the datetime grid of year.

Columns other than the key and the values are identifiers. rule is one of CALENDAR_RULES, or None to use register_calendar_rule(). Rule "share" keeps the source key and returns shares within parent.

recast

recast_calendar() and the timebase halves (port of R/recast.R).

Every conversion routes source -> datetime grid -> target. The route is collapsed into a crosswalk by calendar_map_between(), and the aggregation is nestedscales' recast_crosswalk(), so NA semantics (including the partial-source law) are the core's.

recast_calendar

recast_calendar(
    x: Any,
    source: Calendar,
    target: Calendar | str,
    year: int,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    na_action: NaAction = "drop",
    parent: Calendar | str | None = None,
    collect: bool | None = None,
) -> Any

Recast timeslice data from one calendar to another (or to a timeframe of the same calendar) through the datetime grid of year.

Columns other than the key and the values are identifiers. rule is one of CALENDAR_RULES, or None to use register_calendar_rule(). Rule "share" keeps the source key and returns shares within parent.

recast_from_timebase

recast_from_timebase(
    x: Any,
    calendar: Calendar,
    year: Any = None,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    na_action: NaAction = "drop",
    collect: bool | None = None,
) -> Any

Aggregate datetime-keyed rows UP into the calendar's timeslices, per model year. weighted_mean uses a weight column when present.

recast_to_timebase

recast_to_timebase(
    x: Any,
    calendar: Calendar,
    year: Any = None,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    attach_weight: bool = True,
    collect: bool | None = None,
) -> Any

Project timeslice data DOWN to the datetime grid: one row per grid point. sum columns are split equally over a timeslice's grid points; a weight column (share / points) is attached for the return trip.

recast_to_timebase

recast_to_timebase(
    x: Any,
    calendar: Calendar,
    year: Any = None,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    attach_weight: bool = True,
    collect: bool | None = None,
) -> Any

Project timeslice data DOWN to the datetime grid: one row per grid point. sum columns are split equally over a timeslice's grid points; a weight column (share / points) is attached for the return trip.

recast_from_timebase

recast_from_timebase(
    x: Any,
    calendar: Calendar,
    year: Any = None,
    key: str | None = None,
    values: Any = None,
    rule: str | None = None,
    by: object = None,
    tz: str = "UTC",
    na_action: NaAction = "drop",
    collect: bool | None = None,
) -> Any

Aggregate datetime-keyed rows UP into the calendar's timeslices, per model year. weighted_mean uses a weight column when present.

calendar_map

calendar_map(
    x: Calendar,
    source: str,
    target: str,
    weight: str | None = None,
    **kwargs: Any,
) -> pa.Table

Crosswalk between two timeframes of one calendar.

calendar_map_between

calendar_map_between(
    source: Calendar,
    target: Calendar,
    year: Any,
    by: object = None,
    tz: str = "UTC",
) -> pa.Table

Crosswalk between two calendars over the datetime grid of year(s).

Columns year, <source name>, <target name>, n_from (grid points of the source timeslice), n_overlap, w (the source share falling in the pair). A null target marks grid points the target does not cover.

register_calendar_map

register_calendar_map(
    x: Calendar | str, source: str, target: str, map: Any
) -> str

Register a direct crosswalk between two timeframes of one calendar.

register_calendar_map_between

register_calendar_map_between(
    source: Calendar | str, target: Calendar | str, map: Any
) -> str

Register a direct crosswalk between two calendars; map=None removes it. Needs columns year, the two calendar names, n_from, n_overlap, w.

get_calendar_map

get_calendar_map(
    x: Calendar | str, source: str, target: str
) -> pa.Table | None

get_calendar_map_between

get_calendar_map_between(
    source: Calendar | str, target: Calendar | str
) -> pa.Table | None

list_calendar_maps

list_calendar_maps() -> pa.Table

clear_calendar_maps

clear_calendar_maps(
    registry: bool = False,
    name: str | Sequence[str] | None = None,
) -> None

Drop the memo cache; with registry=True also the registered maps (the named keys only, when name is given).

join_calendar

join_calendar(
    x: Any,
    calendar: Calendar,
    key: str | None = None,
    timeframes: bool | str | Sequence[str] | None = None,
    meta: bool = False,
    as_factor: bool = True,
    year: Any = None,
    by: object = None,
    tz: str = "UTC",
    collect: bool | None = None,
) -> Any

Attach calendar's timeslice labels (and optionally timeframes, share, weight) to x, keyed by a timeslice or datetime column.

base_calendar

base_calendar(
    years: object, by: object = "hour", tz: str = "UTC"
) -> pa.Table

The datetime grid of whole Gregorian years: columns datetime, year.

Each year runs [Jan 1 00:00, next Jan 1) local time in tz, in absolute steps of by ("hour", "15 min", "day", ...). Cached.