time_weighted

time_weighted ¤

Time-weighted resampling for irregular and change-encoded signals.

series.resample(window).mean() averages samples, which is only right when samples are evenly spaced. On a change-encoded signal (one row per change) or irregular data the result is driven by how many rows land in a window, not by how long each value was held: On@09:00, Off@09:59 reads as 50 % on instead of ~98 %, and a window that holds a value without any new sample has no mean at all.

:func:time_weighted_resample holds each value until the next sample (zero-order hold) and averages by time inside each window.

time_weighted_resample ¤

time_weighted_resample(
    series: Series,
    window: str,
    *,
    data_end: Timestamp | None = None,
    max_gap: str | Timedelta | None = None
) -> pd.Series

Time-weighted mean of a held signal per window.

Parameters:

Name	Type	Description	Default
`series`	`Series`	Values with a `DatetimeIndex` (naive or tz-aware). NaN values are ignored (non-numeric values are treated as NaN, with a :class:`~ts_shape.errors.DataQualityWarning`); for duplicate timestamps the last value wins.	required
`window`	`str`	Resample frequency (e.g. `'1h'`).	required
`data_end`	`Timestamp \| None`	Hold the last value until this time (e.g. the end of a companion signal). Default: the series ends at its last sample.	`None`
`max_gap`	`str \| Timedelta \| None`	If set, a value is not held across a gap to the next sample longer than this; that span counts as "no data" instead. `None` (default) holds every value until the next sample, however long the gap.	`None`

Returns:

Type	Description
`Series`	A float Series indexed by window start. Windows without any held
`Series`	value are NaN.