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). 按显式标签窗聚合（非 resample）。语义与示例见 docs/tutorials/3.time_averaging.ipynb。

Parameters:

  • df (pandas.DataFrame) – Must use a DatetimeIndex. 须为 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]. 定义见教程 docs/tutorials/3.time_averaging.ipynb。

  • aggfunc (str or callable, default 'mean') – Passed to _aggregate(). / 传入 _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(). / center 窗的原生步长；None 时由 _archive_timestep_1_or_3() 推断为 1 或 3 分钟。

  • match_ceiling_labels (bool, default True) – When alignment='center', trim monthly edge labels like ceiling (default) or floor. alignment='center' 时，月界裁剪与 ceiling**（默认）或 **floor 一致。

Returns:

One row per output label; insufficient coverage yields NaN rows (labels retained). 每个输出标签一行；覆盖不足时保留标签但行为 NaN。

Return type:

pandas.DataFrame

Raises:

TypeError – If df.index is not a DatetimeIndex. / 索引非 DatetimeIndex。