core_lens.utils.season#

Season-to-date-range resolution for time filtering and temporal column derivation.

Functions#

resolve_time_filter(→ polars.Expr)

Convert a View.time_filter dict to a Polars filter expression.

add_temporal_columns(→ polars.DataFrame | polars.LazyFrame)

Return df with temporal grouping columns appended.

Module Contents#

core_lens.utils.season.resolve_time_filter(time_filter: dict[str, str | int | tuple[int, int] | None], time_col: str, season_config: core_lens.aoi.SeasonConfig) → polars.Expr#

Convert a View.time_filter dict to a Polars filter expression.

Two modes are supported, matching the dict shapes produced by between():

Date range mode — {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"}. Translated directly to a between predicate on time_col.

Season mode — {"season": name, "year": int | (int, int)}. The season name is resolved to a (MM-DD, MM-DD) range from season_config. Year-crossing seasons (e.g. rabi: Nov–Mar) produce an OR expression. When year is absent, all years are matched. When year is a single integer, only that year (or the transition year for year-crossing seasons) is matched.

Parameters:

  • time_filter (dict[str, str | int | tuple[int, int] | None]) – The dictionary stored on time_filter.

  • time_col (str) – Name of the time column in the Parquet file.

  • season_config (SeasonConfig) – The SeasonConfig in effect.

Returns:

A Polars expression that can be passed to .filter().

Return type:

pl.Expr

Raises:

ValueError – If time_filter has an unrecognised structure.

core_lens.utils.season.add_temporal_columns(df: polars.DataFrame | polars.LazyFrame, time_col: str, season_config: core_lens.aoi.SeasonConfig) → polars.DataFrame | polars.LazyFrame#

Return df with temporal grouping columns appended.

Adds the five columns that aggregate() accepts as by values. Called by the materialisation layer (_materialise()) immediately after collect for every sub_annual Result.

Columns added (if not already present):

  • year — integer calendar year of the date.

  • month — integer month (1–12).

  • year_month — string "YYYY-MM" (zero-padded).

  • season — season name string ("kharif" | "rabi" | "zaid").

  • season_year — string "{season}_{year}" (e.g. "kharif_2022").

If a column with one of those names already exists on df it is left untouched — this prevents overwriting data the entity itself may supply.

Parameters:

  • df (pl.DataFrame | pl.LazyFrame) – The collected sub_annual DataFrame.

  • time_col (str) – Name of the date/datetime column to derive from.

  • season_config (SeasonConfig) – The SeasonConfig in effect, used to map each date to its season name.

Returns:

A new DataFrame with the temporal grouping columns appended.

Return type:

pl.DataFrame | pl.LazyFrame