energy_analysis_toolbox.timeseries.resample._facade module#

energy_analysis_toolbox.timeseries.resample._facade.to_freq(timeseries: pd.Series[float], freq: str, origin: Literal['floor', 'ceil'] | Timestamp | None = None, last_step_duration: float | None = None, method: Literal['piecewise_affine', 'piecewise_constant', 'volume_conservative', 'flow_rate_conservative'] | Callable[[Series, DatetimeIndex], Series] = 'piecewise_affine', **kwargs) → pd.Series[float][source]#

Return a timeseries resampled at a given frequency.

Parameters:

  • timeseries (pd.Series) – Series of values of a function of time, indexed using DateTimeIndex.

  • freq (str) – Frequency of the resampled series. See pandas.Series.resample for a list of possible values.

  • origin ({None, 'floor', 'ceil', pd.Timestamp}, optional) – Origin of the resampling period. see index_to_freq for details.

  • last_step_duration ({None, float}, optional) – Duration of the last time-step in timeseries in (s). See index_to_freq for details.

  • method (str or callable, optional) –

    Method used to interpolate the values of the resampled series. The accepted values are:

    • ’piecewise_affine’: uses piecewise_affine, assume the values a straight line between two points. The default method.

    • ’piecewise_constant’: uses piecewise_constant, assume the values constant until the next point.

    • ’volume_conservative’: uses volume_to_freq, conserve the quantity of the values. Best to use it for energy timeseries.

    • ’flow_rate_conservative’: uses flow_rate_to_freq, conserve the values time the duration between two points. Best to use it for power timeseries.

    If a callable is passed, it must take a pandas.Series as first argument and a pandas.DatetimeIndex as second argument. See the interface of piecewise_affine function. The default is ‘piecewise_affine’.

Important

The various methods may manage extrapolation differently, so this situation should be avoided or managed with special care.

Returns:

new_series (pd.Series) – Values of the series resampled at the given frequency.

Examples

This function can be used to resample timeseries of different physical nature with the right method depending on the physical quantity. For example, a timeseries of pointwise temperature can be resampled using piecewise affine interpolation:

>>> new_temp = eat.timeseries.resample.to_freq(temperature, '1min',
... method='piecewise_affine')

The same is true for an energy index :

>>> new_index = eat.timeseries.resample.to_freq(temperature, '1min',
... method='piecewise_affine')

Regarding a quantity that is conserved over time, such as a volume or a flow rate, the resampling should be done using a conservative method. For power and energy, dedicated functions exists, but this function can also be used:

>>> new_volume = eat.timeseries.resample.to_freq(volume, '1min',
... method='volume_conservative')
>>> new_flow_rate = eat.timeseries.resample.to_freq(flow_rate, '1min',
... method='flow_rate_conservative')

See more examples of use in Resampling timeseries using eat.

energy_analysis_toolbox.timeseries.resample._facade.trim_out_of_bounds(data: DataFrame | Series, resampled_data: DataFrame | Series, fill_value: dict[str, any] | None = None) → DataFrame | Series[source]#

Fill resampled data with NA outside the boundaries of initial index.

Parameters:

  • data (pd.DataFrame or pd.Series) – The table of original data which has been resampled.

  • resampled_data (pd.DataFrame or pd.Series) – The result of the resampling.

  • fill_value (dict, optional) – A dictionary where keys are column names, and values are the placeholders used for samples outside the boundaries of the original index. If None, defaults to {'value': pd.NA}.

Returns:

resampled_data (pd.DataFrame or Series) – The passed resample data with placeholders set inplace.