transforms.climatology ====================== .. py:module:: transforms.climatology .. autoapi-nested-parse:: Climatological transformations for earthkit data objects. Typically this is done with an xarray representation of data. Functions --------- .. autoapisummary:: transforms.climatology.anomaly transforms.climatology.auto_anomaly transforms.climatology.daily_max transforms.climatology.daily_mean transforms.climatology.daily_median transforms.climatology.daily_min transforms.climatology.daily_reduce transforms.climatology.daily_std transforms.climatology.max transforms.climatology.mean transforms.climatology.median transforms.climatology.min transforms.climatology.monthly_max transforms.climatology.monthly_mean transforms.climatology.monthly_median transforms.climatology.monthly_min transforms.climatology.monthly_reduce transforms.climatology.monthly_std transforms.climatology.percentiles transforms.climatology.quantiles transforms.climatology.reduce transforms.climatology.relative_anomaly transforms.climatology.std Package Contents ---------------- .. py:function:: anomaly(dataarray, climatology, **_kwargs) Calculate the anomaly from a reference climatology. :param dataarray: The DataArray over which to calculate the anomaly from the reference climatology. Must contain a time dimension indicated by time_dim. :type dataarray: :py:class:`xr.DataArray` :param climatology: Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray. :type climatology: :py:class:`(xr.DataArray`, :py:class:`optional)` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param relative: Return the relative anomaly, i.e. the percentage change w.r.t the climatological period :type relative: :py:class:`bool (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :py:class:`xr.DataArray` .. py:function:: auto_anomaly(dataarray, *_args, climatology_range = None, climatology_how = 'mean', relative = False, **_kwargs) Calculate the anomaly from a reference climatology. :param dataarray: The DataArray over which to calculate the anomaly from the reference climatology. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param climatology: Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray. :type climatology: :py:class:`(xr.DataArray`, :py:class:`optional)` :param climatology_range: Start and end year of the period to be used for the reference climatology. Default is to use the entire time-series. :type climatology_range: :py:class:`(list` or :py:class:`tuple`, :py:class:`optional)` :param climatology_how: Method used to calculate climatology, default is "mean". Accepted values are "median", "min", "max" :type climatology_how: :py:class:`string` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param relative: Return the relative anomaly, i.e. the percentage change w.r.t the climatological period :type relative: :py:class:`bool (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :py:class:`xr.DataArray` .. py:function:: daily_max(*_args, **_kwargs) Calculate the daily climatological max. :param dataarray: The DataArray over which to calculate the climatological max. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: daily_mean(*_args, **_kwargs) Calculate the daily climatological mean. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: daily_median(*_args, **_kwargs) Calculate the daily climatological median. :param dataarray: The DataArray over which to calculate the climatological median. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: daily_min(*_args, **_kwargs) Calculate the daily climatological min. :param dataarray: The DataArray over which to calculate the climatological min. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: daily_reduce(*_args, **_kwargs) Reduce the data to the daily climatology of the provided "how" method. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param how: 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 :type how: :py:class:`str` or :py:class:`callable` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: daily_std(*_args, **_kwargs) Calculate the daily climatological standard deviation. :param dataarray: The DataArray over which to calculate the climatological standard deviation. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: max(*_args, **_kwargs) Calculate the climatological maximum. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: mean(*_args, **_kwargs) Calculate the climatological mean. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: median(*_args, **_kwargs) Calculate the climatological median. :param dataarray: The DataArray over which to calculate the climatological median. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: min(*_args, **_kwargs) Calculate the climatological minimum. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_max(*_args, **_kwargs) Calculate the monthly climatological max. :param dataarray: The DataArray over which to calculate the climatological max. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_mean(*_args, **_kwargs) Calculate the monthly climatological mean. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_median(*_args, **_kwargs) Calculate the monthly climatological median. :param dataarray: The DataArray over which to calculate the climatological median. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_min(*_args, **_kwargs) Calculate the monthly climatological min. :param dataarray: The DataArray over which to calculate the climatological min. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_reduce(*_args, **_kwargs) Reduce the data to the monthly climatology of the provided "how" method. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param how: 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 :type how: :py:class:`str` or :py:class:`callable` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: monthly_std(*_args, **_kwargs) Calculate the monthly climatological standard deviation. :param dataarray: The DataArray over which to calculate the climatological standard deviation. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: percentiles(dataarray, p, **_kwargs) Calculate a set of climatological percentiles. :param dataarray: The DataArray over which to calculate the climatological percentiles. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param p: The pecentile, or list of percentiles, to calculate the climatology. :type p: :py:class:`float | list` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: quantiles(dataarray, q, time_dim = None, groupby_kwargs = {}, **reduce_kwargs) Calculate a set of climatological quantiles. :param dataarray: The DataArray over which to calculate the climatological quantiles. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param q: The quantile, or list of quantiles, to calculate the climatology. :type q: :py:class:`float | list` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param groupby_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.groupby_time` :type groupby_kwargs: :py:class:`dict` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: 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. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param how: 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 :type how: :py:class:`str` or :py:class:`callable` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param groupby_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.groupby_time` :type groupby_kwargs: :py:class:`dict` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray` .. py:function:: relative_anomaly(*_args, **_kwargs) Calculate the relative anomaly from a reference climatology, i.e. percentage change. :param dataarray: The DataArray over which to calculate the anomaly from the reference climatology. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param climatology: Reference climatology data against which the anomaly is to be calculated. If not provided then the climatological mean is calculated from dataarray. :type climatology: :py:class:`(xr.DataArray`, :py:class:`optional)` :param climatology_range: Start and end year of the period to be used for the reference climatology. Default is to use the entire time-series. :type climatology_range: :py:class:`(list` or :py:class:`tuple`, :py:class:`optional)` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :py:class:`xr.DataArray` .. py:function:: std(*_args, **_kwargs) Calculate the climatological standard deviation. :param dataarray: The DataArray over which to calculate the climatological standard deviation. Must contain a `time` dimension. :type dataarray: :py:class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :py:class:`str (optional)` :param bin_widths: 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. :type bin_widths: :py:class:`int` or :py:class:`list (optional)` :param time_dim: Name of the time dimension in the data object, default behaviour is to detect the time dimension from the input object :type time_dim: :py:class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :py:class:`xr.DataArray`