momlevel.trend module¶
trend.py - utilities for working with trends
- momlevel.trend.broadcast_trend(slope, dim_arr)¶
Function to broadcast a trend along a dimension
This function broadcasts a trend against a dimension to obtain a fitted line, e.g. (m * x).
- Parameters:
slope (xarray.core.dataarray.DataArray) – Array containing a slope. If this is a time trend, the units of the trend will be inferred from the array’s units atttribute according to CF-convention. If the units attribute is missing, Xarray’s default time units of [ns] wil be assumed
dim_arr (xarray.core.dataarray.DataArray) – Dimension array, e.g. time axis
- Returns:
Broadcasted array, or fitted line
- Return type:
xarray.core.dataarray.DataArray
- momlevel.trend.calc_linear_trend(arr, dim='time', time_units=None)¶
Function to calculate the linear trend of a DataArray
This function calculates the linear trend of an xarray DataArray object. The trend can be done along any array dimension, but this is most commonly time. The function calls the Xarray’s polyfit function which uses NumPy’s polyfit routine. The linear trend is defined as order=1 within these functions.
Xarray’s internal clock is based on nanoseconds. The trend is returned in units of “ns-1” by default. Alternative time units can be specified and a conversion is performed. Recognized units are: “ns”, “s”, “min”, “hr”, “day”, “mon” and “yr”
- Parameters:
arr (xarray.core.dataarray.DataArray) – Input array
dim (str, optional) – Dimension for detrending operation, by default “time”
time_units (str, optional) – Result time units, see above, by default None
- Returns:
Xarray Dataset with variable _slope and _intercept arrays
- Return type:
xarray.core.dataset.Dataset
- momlevel.trend.deseason(arr, tdim='time', output_format='residuals')¶
Removes seasonal and linear trends from a time-series dataset.
This function applies detrending and deseasonalizing operations on an xarray.DataArray object. It can return residuals, the fitted model, or the model coefficients based on the specified output_format. The input array is processed along a specified time dimension, and the output array maintains the same shape as the input in all configurations except for coefficient mode.
The model equation is:
\[y(t) = a_0 + a_1t + b_1\sin(2\pi t) + b_2\cos(2\pi t) + c_1\sin(4\pi t) + c_2\cos(4\pi t) + \epsilon(t)\]where: - \(t\) is time in decimal years - \(a_0\) is the constant term (mean) - \(a_1\) is the linear trend coefficient - \(b_1, b_2\) are the annual cycle coefficients - \(c_1, c_2\) are the semi-annual cycle coefficients - \(\epsilon(t)\) represents the residuals
The annual cycle amplitude and phase can be computed from the coefficients as: .. math:
A_{annual} = \sqrt{b_1^2 + b_2^2} \phi_{annual} = rctan2(b_2, b_1)- Parameters:
arr (xr.DataArray) – Input data as an xarray.DataArray object. The data should have a time dimension specified by tdim. If no chunking is applied to the array along the time dimension, it will be rechunked.
tdim (str, default="time") – The name of the time dimension in arr along which the computation will be performed. The default value is “time”.
output_format ({"residuals", "model", "coeff"}, default="residuals") –
Specifies the type of output to return: - “residuals”: Returns the daily residuals after detrending and
removing seasonal signals.
”model”: Returns the linear trend and seasonal cycle model.
”coeff”: Returns the polynomial coefficients of the fitted seasonal model.
- Returns:
The processed xarray.DataArray after removing trends and seasonal components. The exact contents will depend on the selected output_format.
- Return type:
xr.DataArray
- momlevel.trend.linear_detrend(xobj, dim='time', order=1, mode='remove')¶
Function to linearly detrend an xarray object
This function performs a linear de-trending of either an xarray DataArray or Dataset. The function can either remove the linear mean and return anomalies relative to the trend, or it can correct for a linear trend while preserving the original magnitude of the input data.
This function can operate on a single timeseries as well as a multi-dimensional array that contains a time dimension. In the case of a multi-dimensional array, the trends are calculated independently for each point.
- Parameters:
xobj (xarray.core.dataarray.DataArray or xarray.core.dataset.Dataset) – Input xarray object
dim (str, optional) – Name of coordinate for linear detrending, by default “time”
order (int, optional) – Order of polynomial fit. Linear detrending defaults to “1”
mode (str, optional) – Either “remove” the linear trend and return anomalies, or “correct” for a drift and retain the original magnitude of the input data, by default “remove”
- Return type:
xarray.core.dataarray.DataArray or xarray.core.dataset.Dataset
- momlevel.trend.seasonal_model(da_timeseries, tcoord='time', return_model=False)¶
Function to calculate a seasonal cycle in a time series This function creates a modelled time series that includes a linear trend and annual and semi-annual harmonics
- f(time) = b + m * time + c1 * sin(2*pi*time/year) + …
c2 * cos(2*pi*time/year) + c3 * sin(4*pi*time/year) + … c4 * cos(4*pi*time/year) + residual
- Parameters:
da_timeseries (xarray.core.dataarray.DataArray) – A time series in a DataArray format, which can be of arbitrary dimensionality
tcoord (str, optional) – Name of the time coordinate, if present, by default “time”
- Returns:
residuals (xarray.core.dataarray.DataArray) – Residuals from modelled fit
seasonal_model (xarray.core.dataarray.DataArray) – Modelled seasonal cycle of time series (returned only if return_model=True)
- momlevel.trend.time_conversion_factor(src, dst, days_per_month=30.417, days_per_year=365.0)¶
Function that returns conversion factors for common time units.
This function returns a conversion factor for a source time unit to a destination time unit. Time units are specified as string inputs.
Recognized units are “ns”, “s”, “min”, “hr”, “day”, “mon” and “yr”
For conversions involving months, an average value of 30.417 days per month is assumed but this value can be overridden with the days_per_month optional argument. For conversions involving years, a value of 365 days per year is the default but can be overridden at runtime with the optional days_per_year argument.
- Parameters:
src (str) – Source time unit string
dst (str) – Destination time unit string
days_per_month (float, optional) – Days per month, by default 30.417
days_per_year (float, optional) – Days per year, by default 365.0
- Returns:
Time conversion factor
- Return type:
float