gradients

gradients#

Heating and cooling gradients (rate of change per hour) of a time series, classified by direction and season.

See Gradients for usage examples.

API Reference#

Heating and cooling gradients (rate of change per hour) of a time series.

Sign-based method: the series is resampled to a fixed frequency (hourly by default), then the step-to-step difference (the gradient) is taken. Differencing does not bridge data gaps — missing steps become NaN and are dropped. A fixed threshold separates relevant heating/cooling phases from the noise of small fluctuations.

Seasons are classified via pyedautils.data_prep.season.get_season().

pyedautils.data_prep.gradients.compute_gradients(data: Series | DataFrame, *, threshold: float = 0.0, freq: str = '1h', tracking_type: str = 'astronomical', direction_labels: Tuple[str, str] = ('heating', 'cooling'), season_labels: List[str] | None = None) → DataFrame[source]#

Step-to-step gradients of a time series, classified by direction and season.

Parameters:

  • data – A pandas Series with a DatetimeIndex, or a two-column [timestamp, value] DataFrame.

  • threshold – Absolute magnitude threshold (per freq step); only |gradient| > threshold is kept. Default 0 (keep all non-zero steps).

  • freq – Resampling frequency for the mean before differencing. Default "1h" (gradient is then per hour).

  • tracking_type – Season definition passed to get_season() ("astronomical" or "meteorological").

  • direction_labels – (rising, falling) labels. Default ("heating", "cooling").

  • season_labels – Optional custom season labels (order: spring, summer, fall, winter) passed to get_season().

Returns:

One row per kept step with columns [timestamp, gradient, direction, season]. direction is the first label for gradient > 0 and the second for gradient < 0.

Return type:

pd.DataFrame

pyedautils.data_prep.gradients.summarize_gradients(gradients: DataFrame, direction_labels: Tuple[str, str] = ('heating', 'cooling'), decimals: int = 2) → DataFrame[source]#

Aggregate gradients by direction (mean / min / max / count).

Parameters:

  • gradients – Output of compute_gradients().

  • direction_labels – (rising, falling) labels, used to order rows and to guarantee both rows exist even if one direction is empty.

  • decimals – Rounding for the statistics. Default 2.

Returns:

One row per direction with columns [direction, mean, min, max, n]. Statistics are NaN when a direction has no steps.

Return type:

pd.DataFrame

pyedautils.data_prep.gradients.mean_gradients_by_season(gradients: DataFrame, season_order: List[str] | None = None, direction_order: Tuple[str, str] | None = ('heating', 'cooling')) → DataFrame[source]#

Mean gradient and count per season and direction.

Parameters:

  • gradients – Output of compute_gradients().

  • season_order – Optional ordered list of season labels for sorting.

  • direction_order – Optional ordered direction labels for sorting.

Returns:

Columns [season, direction, mean, n].

Return type:

pd.DataFrame