transforms.climatology

Climatological transformations for earthkit data objects.

Typically this is done with an xarray representation of data.

Functions

anomaly(dataarray, climatology, **_kwargs)	Calculate the anomaly from a reference climatology.
auto_anomaly(dataarray, *_args[, climatology_range, ...])	Calculate the anomaly from a reference climatology.
daily_max(*_args, **_kwargs)	Calculate the daily climatological max.
daily_mean(*_args, **_kwargs)	Calculate the daily climatological mean.
daily_median(*_args, **_kwargs)	Calculate the daily climatological median.
daily_min(*_args, **_kwargs)	Calculate the daily climatological min.
daily_reduce(*_args, **_kwargs)	Reduce the data to the daily climatology of the provided "how" method.
daily_std(*_args, **_kwargs)	Calculate the daily climatological standard deviation.
max(*_args, **_kwargs)	Calculate the climatological maximum.
mean(*_args, **_kwargs)	Calculate the climatological mean.
median(*_args, **_kwargs)	Calculate the climatological median.
min(*_args, **_kwargs)	Calculate the climatological minimum.
monthly_max(*_args, **_kwargs)	Calculate the monthly climatological max.
monthly_mean(*_args, **_kwargs)	Calculate the monthly climatological mean.
monthly_median(*_args, **_kwargs)	Calculate the monthly climatological median.
monthly_min(*_args, **_kwargs)	Calculate the monthly climatological min.
monthly_reduce(*_args, **_kwargs)	Reduce the data to the monthly climatology of the provided "how" method.
monthly_std(*_args, **_kwargs)	Calculate the monthly climatological standard deviation.
percentiles(dataarray, p, **_kwargs)	Calculate a set of climatological percentiles.
quantiles(dataarray, q[, time_dim, groupby_kwargs])	Calculate a set of climatological quantiles.
reduce(dataarray[, time_dim, how, groupby_kwargs])	Group data annually over a given frequency and reduce using the specified how method.
relative_anomaly(*_args, **_kwargs)	Calculate the relative anomaly from a reference climatology, i.e. percentage change.
std(*_args, **_kwargs)	Calculate the climatological standard deviation.

Package Contents

transforms.climatology.anomaly(dataarray, climatology, **_kwargs)

Calculate the anomaly from a reference climatology.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the anomaly from the reference climatology. Must contain a time dimension indicated by time_dim.

• climatology ((xr.DataArray, optional)) – Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• relative (bool (optional)) – Return the relative anomaly, i.e. the percentage change w.r.t the climatological period

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.climatology.mean

Return type:

xr.DataArray

transforms.climatology.auto_anomaly(dataarray, *_args, climatology_range=None, climatology_how='mean', relative=False, **_kwargs)

Calculate the anomaly from a reference climatology.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the anomaly from the reference climatology. Must contain a time dimension.

• climatology ((xr.DataArray, optional)) – Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray.

• climatology_range ((list or tuple, optional)) – Start and end year of the period to be used for the reference climatology. Default is to use the entire time-series.

• climatology_how (string) – Method used to calculate climatology, default is “mean”. Accepted values are “median”, “min”, “max”

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• relative (bool (optional)) – Return the relative anomaly, i.e. the percentage change w.r.t the climatological period

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.climatology.mean

Return type:

xr.DataArray

transforms.climatology.daily_max(*_args, **_kwargs)

Calculate the daily climatological max.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological max. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.daily_mean(*_args, **_kwargs)

Calculate the daily climatological mean.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.daily_median(*_args, **_kwargs)

Calculate the daily climatological median.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological median. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.daily_min(*_args, **_kwargs)

Calculate the daily climatological min.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological min. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.daily_reduce(*_args, **_kwargs)

Reduce the data to the daily climatology of the provided “how” method.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• how (str or callable) – Method used to reduce data. Default=’mean’, which will implement the xarray in-built mean. If string, it must be an in-built xarray reduce method, an earthkit how method or any method compatible with the array namespace of the data. In the case of duplicate names, method selection is first in the order: xarray, earthkit, array_namespace. Otherwise it can be any function which can be called in the form f(x, axis=axis, **kwargs) to return the result of reducing an array over an integer valued axis

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.daily_std(*_args, **_kwargs)

Calculate the daily climatological standard deviation.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological standard deviation. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.max(*_args, **_kwargs)

Calculate the climatological maximum.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.mean(*_args, **_kwargs)

Calculate the climatological mean.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.median(*_args, **_kwargs)

Calculate the climatological median.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological median. Must contain a time dimension.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.min(*_args, **_kwargs)

Calculate the climatological minimum.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_max(*_args, **_kwargs)

Calculate the monthly climatological max.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological max. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_mean(*_args, **_kwargs)

Calculate the monthly climatological mean.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_median(*_args, **_kwargs)

Calculate the monthly climatological median.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological median. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_min(*_args, **_kwargs)

Calculate the monthly climatological min.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological min. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_reduce(*_args, **_kwargs)

Reduce the data to the monthly climatology of the provided “how” method.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• how (str or callable) – Method used to reduce data. Default=’mean’, which will implement the xarray in-built mean. If string, it must be an in-built xarray reduce method, an earthkit how method or any method compatible with the array namespace of the data. In the case of duplicate names, method selection is first in the order: xarray, earthkit, array_namespace. Otherwise it can be any function which can be called in the form f(x, axis=axis, **kwargs) to return the result of reducing an array over an integer valued axis

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.monthly_std(*_args, **_kwargs)

Calculate the monthly climatological standard deviation.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological standard deviation. Must contain a time dimension.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.percentiles(dataarray, p, **_kwargs)

Calculate a set of climatological percentiles.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological percentiles. Must contain a time dimension.

• p (float | list) – The pecentile, or list of percentiles, to calculate the climatology.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.quantiles(dataarray, q, time_dim=None, groupby_kwargs={}, **reduce_kwargs)

Calculate a set of climatological quantiles.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological quantiles. Must contain a time dimension.

• q (float | list) – The quantile, or list of quantiles, to calculate the climatology.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• groupby_kwargs (dict) – Any other kwargs that are accepted by earthkit.transforms.aggregate.groupby_time

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.reduce(dataarray, time_dim=None, how='mean', groupby_kwargs={}, **reduce_kwargs)

Group data annually over a given frequency and reduce using the specified how method.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological mean. Must contain a time dimension.

• how (str or callable) – Method used to reduce data. Default=’mean’, which will implement the xarray in-built mean. If string, it must be an in-built xarray reduce method, an earthkit how method or any method compatible with the array namespace of the data. In the case of duplicate names, method selection is first in the order: xarray, earthkit, array_namespace. Otherwise it can be any function which can be called in the form f(x, axis=axis, **kwargs) to return the result of reducing an array over an integer valued axis

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• groupby_kwargs (dict) – Any other kwargs that are accepted by earthkit.transforms.aggregate.groupby_time

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray

transforms.climatology.relative_anomaly(*_args, **_kwargs)

Calculate the relative anomaly from a reference climatology, i.e. percentage change.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the anomaly from the reference climatology. Must contain a time dimension.

• climatology ((xr.DataArray, optional)) – Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray.

• climatology_range ((list or tuple, optional)) – Start and end year of the period to be used for the reference climatology. Default is to use the entire time-series.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.climatology.mean

Return type:

xr.DataArray

transforms.climatology.std(*_args, **_kwargs)

Calculate the climatological standard deviation.

Parameters:

• dataarray (xr.DataArray) – The DataArray over which to calculate the climatological standard deviation. Must contain a time dimension.

• frequency (str (optional)) – Valid options are day, week and month.

• bin_widths (int or list (optional)) – If bin_widths is an int, it defines the width of each group bin on the frequency provided by frequency. If bin_widths is a sequence it defines the edges of each bin, allowing for non-uniform bin widths.

• time_dim (str (optional)) – Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object

• **reduce_kwargs – Any other kwargs that are accepted by earthkit.transforms.aggregate.reduce (except how)

Return type:

xr.DataArray