Contents

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.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

momlevel.tidegauge module momlevel.util module