transforms.aggregate.climatology ================================ .. py:module:: transforms.aggregate.climatology Attributes ---------- .. autoapisummary:: transforms.aggregate.climatology.anomalazy Functions --------- .. autoapisummary:: transforms.aggregate.climatology.reduce transforms.aggregate.climatology.mean transforms.aggregate.climatology.median transforms.aggregate.climatology.min transforms.aggregate.climatology.max transforms.aggregate.climatology.std transforms.aggregate.climatology.daily_reduce transforms.aggregate.climatology.daily_mean transforms.aggregate.climatology.daily_median transforms.aggregate.climatology.daily_min transforms.aggregate.climatology.daily_max transforms.aggregate.climatology.daily_std transforms.aggregate.climatology.monthly_reduce transforms.aggregate.climatology.monthly_mean transforms.aggregate.climatology.monthly_median transforms.aggregate.climatology.monthly_min transforms.aggregate.climatology.monthly_max transforms.aggregate.climatology.monthly_std transforms.aggregate.climatology.quantiles transforms.aggregate.climatology.percentiles transforms.aggregate.climatology.anomaly transforms.aggregate.climatology.update_anomaly_array transforms.aggregate.climatology.relative_anomaly transforms.aggregate.climatology.auto_anomaly Module Contents --------------- .. 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: :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 numpy method. In the case of duplicate names, method selection is first in the order: xarray, earthkit, numpy. 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 np.ndarray over an integer valued axis :type how: :class:`str` or :class:`callable` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: mean(dataarray, *args, **kwargs) Calculate the climatological mean. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: median(dataarray, **kwargs) Calculate the climatological median. :param dataarray: The DataArray over which to calculate the climatological median. Must contain a `time` dimension. :type dataarray: :class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: min(dataarray, *args, **kwargs) Calculate the climatological minimum. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: max(dataarray, *args, **kwargs) Calculate the climatological maximum. :param dataarray: The DataArray over which to calculate the climatological mean. Must contain a `time` dimension. :type dataarray: :class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: std(dataarray, *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: :class:`xr.DataArray` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_reduce(dataarray, *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: :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 numpy method. In the case of duplicate names, method selection is first in the order: xarray, earthkit, numpy. 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 np.ndarray over an integer valued axis :type how: :class:`str` or :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_mean(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_median(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_min(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_max(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: daily_std(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_reduce(dataarray, *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: :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 numpy method. In the case of duplicate names, method selection is first in the order: xarray, earthkit, numpy. 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 np.ndarray over an integer valued axis :type how: :class:`str` or :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_mean(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_median(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_min(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_max(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. py:function:: monthly_std(dataarray, *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: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :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: :class:`xr.DataArray` :param q: The quantile, or list of quantiles, to calculate the climatology. :type q: :class:`float | list` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :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: :class:`xr.DataArray` :param percentiles: The pecentile, or list of percentiles, to calculate the climatology. :type percentiles: :class:`float | list` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.reduce` (except how) :rtype: :class:`xr.DataArray` .. 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: :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: :class:`(xr.DataArray`, :class:`optional)` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param relative: Return the relative anomaly, i.e. the percentage change w.r.t the climatological period :type relative: :class:`bool (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :class:`xr.DataArray` .. py:function:: update_anomaly_array(anomaly_array, original_array, var_name, name_tag, update_attrs) .. py:function:: relative_anomaly(dataarray, *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: :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: :class:`(xr.DataArray`, :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: :class:`(list` or :class:`tuple`, :class:`optional)` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :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: :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: :class:`(xr.DataArray`, :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: :class:`(list` or :class:`tuple`, :class:`optional)` :param climatology_how: Method used to calculate climatology, default is "mean". Accepted values are "median", "min", "max" :type climatology_how: :class:`string` :param frequency: Valid options are `day`, `week` and `month`. :type frequency: :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: :class:`int` or :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: :class:`str (optional)` :param relative: Return the relative anomaly, i.e. the percentage change w.r.t the climatological period :type relative: :class:`bool (optional)` :param \*\*reduce_kwargs: Any other kwargs that are accepted by `earthkit.transforms.aggregate.climatology.mean` :rtype: :class:`xr.DataArray` .. py:data:: anomalazy