my_code_base.stats.timeseries¶

Functions¶

`extend_annual_series`(ds)	Fill a time series with only annual values (one such timeseries could be generated
`pd_seasonal_decompose`(x[, freq])	Decompose a time series into its trend, the seasonality, and the residuals.
`weighted_annual_mean`(ds)	Compute the weighted annual mean of an `xarray.Dataset` or `xarray.DataArray`.
`xr_deseasonalize`(da[, freq, dim])	Remove the seasonal cycle of an `xr.Dataset` object.
`xr_seasonal_decompose`(da[, dim])	Perform seasonal decomposition of a time series using the given dataset.

Module Contents¶

my_code_base.stats.timeseries.extend_annual_series(ds)[source]¶

Fill a time series with only annual values (one such timeseries could be generated via weighted_annual_mean(), for example) such that all months are represented again but the value for all 12 months within a year is equal to the annual value.

Parameters:¶

ds : xarray.Dataset¶: The input dataset containing the time series data.

Returns:¶

The extended time series dataset with monthly values.

Return type:¶

xarray.Dataset

Raises:¶

AssertionError – If the dataset does not have ‘year’ as a dimension.

Example

>>> ds = xr.Dataset({'time': pd.date_range('2000-01-01', '2001-12-31', freq='ME'),
...                  'value': np.random.rand(24)})
>>> extended_ds = extend_annual_series(ds)

my_code_base.stats.timeseries.pd_seasonal_decompose(x, freq=12)[source]¶

Decompose a time series into its trend, the seasonality, and the residuals.

Parameters:¶

x : pandas.Series¶: A pandas.Series containing a time series of data
freq : int¶: The frequency of the data, e.g. 12 for monthly data

Returns:¶

A pandas.DataFrame containing time series of the raw data, trend,
seasonality, the detrended time series, and the residuals.

my_code_base.stats.timeseries.weighted_annual_mean(ds: xarray.Dataset | xarray.DataArray)[source]¶

Compute the weighted annual mean of an xarray.Dataset or xarray.DataArray.

Parameters:¶

ds : xarray.Dataset | xarray.DataArray¶: The input dataset or data array.

Returns:¶

The weighted annual mean of the input dataset or data array.

Return type:¶

xarray.DataArray

Raises:¶

AssertionError – If the sum of the weights in each year is not equal to 1.0.

Notes

The function computes the annual mean of the input dataset or data array, taking into account the different lengths of the months. Each month is weighted by the number of days it comprises. If the frequency of the time dimension is ‘1M’, the function applies the weights. If the frequency is ‘1D’ or higher, no weights are applied.

The function follows the approach described in the following source: https://ncar.github.io/esds/posts/2021/yearly-averages-xarray/

The function assumes that the input dataset or data array has a ‘time’ dimension.

my_code_base.stats.timeseries.xr_deseasonalize(da, freq=12, dim='time')[source]¶

Remove the seasonal cycle of an xr.Dataset object. Data get first detrended, then the long-term average of every season is subtracted for each season. Finally, the trend is added again.

Parameters:¶

freq : int¶: The frequency of the data. Default is 12 for monthly resolution.
dim : str¶: The name of the time dimension.

my_code_base.stats.timeseries.xr_seasonal_decompose(da, dim='time')[source]¶

Perform seasonal decomposition of a time series using the given dataset.

Parameters:¶

da : xarray.DataArray¶: The input data array containing the time series.
dim : str¶: The dimension along which the decomposition is performed. Default is ‘time’.

Returns:¶

A new dataset containing the decomposed components: trend, detrended, seasonality, residuals, and deseasonalized.

Return type:¶

xarray.Dataset