bsrn.utils.averaging.pretty_average#

bsrn.utils.averaging.pretty_average(df, freq, alignment='ceiling', aggfunc='mean', resolution=None, match_ceiling_labels=True)[source]#

Average df over explicit labeled windows (not pandas resample semantics). Semantics and examples: docs/tutorials/4.time_averaging.ipynb.

Parameters:

  • df (pandas.DataFrame) – Must use a DatetimeIndex.

  • freq (str) – Fixed bin frequency (e.g. '1h', '30min').

  • alignment ({‘floor’, ‘ceiling’, ‘center’}, default 'ceiling') – floor [L, L+Δ) · ceiling (L-Δ, L] · center [L-Δ/2+res, L+Δ/2]. Definitions: tutorial docs/tutorials/4.time_averaging.ipynb.

  • aggfunc (str or callable, default 'mean') – Passed to _aggregate().

  • resolution (pandas.Timedelta or None, default None) – Native timestep for center windows; if None, inferred as 1 or 3 min via _archive_timestep_1_or_3().

  • match_ceiling_labels (bool, default True) – When alignment='center', trim monthly edge labels like ceiling (default) or floor.

Returns:

One row per output label; insufficient coverage yields NaN rows (labels retained).

Return type:

pandas.DataFrame

Raises:

TypeError – If df.index is not a DatetimeIndex.