Advanced tools¶

Core tools¶

Methods to build indicators and compute functions and to help handle climate data in general.

The top-level of this module contains exceptions and type descriptors used internally.

class xclim.core.InputKind(*values)[source]¶

Constants for defining types or kinds of indicator parameters.

For use by external parsers to determine what kind of data the indicator expects. On the creation of an indicator, the appropriate constant is stored in xclim.core.indicator.Indicator.parameters. The integer value is what gets stored in the output of xclim.core.indicator.Indicator.json().

For developers: For each constant, the docstring specifies the annotation a parameter of a compute function should use in order to be picked up by the indicator constructor. Notice that we are using the annotation format as described in PEP 604, i.e. with ‘|’ indicating a union and without import objects from typing.

BOOL = 9¶

A boolean flag.

Annotation : bool, may be optional.

DATASET = 70¶

An xarray dataset.

Developers : as compute functions only accept DataArrays, this should only be added by the indicator.

DATE = 7¶

A date in the YYYY-MM-DD format, may include a time.

Annotation : xclim.core.utils.DateStr (may be optional).

DAY_OF_YEAR = 6¶

A date, but without a year, in the MM-DD format.

Annotation : xclim.core.utils.DayOfYearStr (may be optional).

DICT = 10¶

A dictionary.

Annotation : dict or dict | None, may be optional.

FREQ_STR = 3¶

A string representing an “offset alias”, as defined by pandas.

See the Pandas documentation on Offset aliases for a list of valid aliases.

Annotation : str + freq as the parameter name.

KWARGS = 50¶

A mapping from argument name to value.

Developers : maps the **kwargs. Please use as little as possible.

MASK = 11¶: A mask or flag or scalar. Any value without units that might be passed as a non-temporal DataArray. Can be a DataArray, a single bool or a single float.

Annotation : xr.DataArray | bool or xr.DataArray | float, may be optional.

NUMBER = 4¶

A number.

Annotation : int, float and unions thereof, potentially optional.

NUMBER_SEQUENCE = 8¶

A sequence of numbers

Annotation : Sequence[int], Sequence[float] and unions thereof, may include single int and float, may be optional.

OPTIONAL_VARIABLE = 1¶

An optional data variable (DataArray or variable name).

Annotation : xr.DataArray | None. The default should be None.

OTHER_PARAMETER = 99¶

An object that fits None of the previous kinds.

Developers : This is the fallback kind, it will raise an error in xclim’s unit tests if used.

QUANTIFIED = 2¶

A quantity with units, either as a string (scalar), a pint.Quantity (scalar) or a DataArray (with units set).

Annotation : xclim.core.utils.Quantified and an entry in the xclim.core.units.declare_units() decorator. “Quantified” translates to str | xr.DataArray | pint.util.Quantity.

STRING = 5¶

A simple string.

Annotation : str or str | None. In most cases, this kind of parameter makes sense with choices indicated in the docstring’s version of the annotation with curly braces. See Defining new index-like compute functions.

VARIABLE = 0¶

A data variable (DataArray or variable name).

Annotation : xr.DataArray. May not include anything else, may not be optional.

exception xclim.core.MissingVariableError[source]¶: Error raised when a dataset is passed to an indicator but one of the needed variable is missing.

exception xclim.core.ValidationError[source]¶: Error raised when input data to an indicator fails the validation tests.

xclim.core.infer_kind_from_parameter(param)[source]¶

Return the appropriate InputKind constant from an inspect.Parameter object.

Parameters:: param (Parameter) – An inspect.Parameter instance.
Return type:: InputKind
Returns:: InputKind – The appropriate InputKind constant.

Notes

The correspondence between parameters and kinds is documented in xclim.core.utils.InputKind.

xclim.core.is_percentile_dataarray(source)[source]¶

Evaluate whether a DataArray is a Percentile.

A percentile DataArray must have ‘climatology_bounds’ attributes and either a quantile or percentiles coordinate, the window is not mandatory.

Parameters:: source (xr.DataArray) – The DataArray to evaluate.
Return type:: bool
Returns:: bool – True if the DataArray is a percentile.

xclim.core.raise_warn_or_log(err, mode, msg=None, err_type=<class 'ValueError'>, stacklevel=1)[source]¶

Raise, warn or log an error according.

Parameters:

err (Exception) – An error.
mode ({‘ignore’, ‘log’, ‘warn’, ‘raise’}) – What to do with the error.
msg (str, optional) – The string used when logging or warning. Defaults to the msg attr of the error (if present) or to “Failed with <err>”.
err_type (type) – The type of error/exception to raise.
stacklevel (int) – Stacklevel when warning. Relative to the call of this function (1 is added).

Module comprising the bootstrapping algorithm for indicators.

xclim.core.bootstrapping.bootstrap_func(compute_index_func, **kwargs)[source]¶

Bootstrap the computation of percentile-based indicators.

Indicators measuring exceedance over percentile-based thresholds (such as tx90p) may contain artificial discontinuities at the beginning and end of the reference period used to calculate percentiles. The bootstrap procedure can reduce those discontinuities by iteratively computing the percentile estimate and the index on altered reference periods.

These altered reference periods are themselves built iteratively: When computing the index for year x, the bootstrapping creates as many altered reference periods as the number of years in the reference period. To build one altered reference period, the values of year x are replaced by the values of another year in the reference period, then the index is computed on this altered period. This is repeated for each year of the reference period, excluding year x. The final result of the index for year x is then the average of all the index results on altered years.

Parameters:

compute_index_func (Callable) – Index function.
**kwargs (dict) – Arguments to func.

Return type:

DataArray

Returns:

xr.DataArray – The result of func with bootstrapping.

Notes

This function is meant to be used by the percentile_bootstrap decorator. The parameters of the percentile calculation (percentile, window, reference_period) are stored in the attributes of the percentile DataArray. The bootstrap algorithm implemented here does the following:

For each temporal grouping in the calculation of the index
    If the group `g_t` is in the reference period
        For every other group `g_s` in the reference period
            Replace group `g_t` by `g_s`
            Compute percentile on resampled time series
            Compute index function using percentile
        Average output from index function over all resampled time series
    Else compute index function using original percentile

References

Zhang, Hegerl, Zwiers, and Kenyon [2005]

xclim.core.bootstrapping.build_bootstrap_year_da(da, groups, label, dim='time')[source]¶

Return an array where every other group replaces a group in the original along a new dimension.

Parameters:

da (DataArray) – Original input array over the reference period.
groups (dict) – Output of grouping functions, such as DataArrayResample.groups.
label (Any) – Key identifying the group item to replace.
dim (str) – Dimension recognised as time. Default: time.

Return type:

DataArray

Returns:

DataArray – Array where one group is replaced by values from every other group along the bootstrap dimension.

xclim.core.bootstrapping.percentile_bootstrap(func)[source]¶

Decorator applying a bootstrap step to the calculation of exceedance over a percentile threshold.

This feature is experimental.

Parameters:: func (Callable) – The function to decorate.
Return type:: Callable
Returns:: Callable – The decorated function.

Notes

Bootstrapping avoids discontinuities in the exceedance between the reference period over which percentiles are computed, and “out of reference” periods. See bootstrap_func for details.

Declaration example:

@declare_units(tas="[temperature]", t90="[temperature]")
@percentile_bootstrap
def tg90p(
    tas: xarray.DataArray,
    t90: xarray.DataArray,
    freq: Freq = "YS",
    bootstrap: bool = False,
) -> xarray.DataArray:
    pass

Examples

>>> from xclim.core.calendar import percentile_doy
>>> from xclim.compute import tg90p
>>> tas = xr.open_dataset(path_to_tas_file).tas
>>> # To start bootstrap reference period must not fully overlap the studied period.
>>> tas_ref = tas.sel(time=slice("1990-01-01", "1992-12-31"))
>>> t90 = percentile_doy(tas_ref, window=5, per=90)
>>> tas_90th_percentile = tg90p(tas=tas, tas_per=t90.sel(percentiles=90), freq="YS", bootstrap=True)

Formatting Utilities for Indicators¶

class xclim.core.formatting.AttrFormatter(mapping, modifiers)[source]¶

Bases: string.Formatter

A formatter for frequently used attribute values.

Parameters:

mapping (dict of str, sequence of str) – A mapping from values to their possible variations.
modifiers (sequence of str) – The list of modifiers. Must at least match the length of the longest value of mapping. Cannot include reserved modifier ‘r’.

Notes

See the doc of format_field() for more details.

format(format_string, /, *args, **kwargs)[source]¶

Format a string.

Parameters:

format_string (str) – The string to format.
*args (Any) – Arguments to format.
**kwargs (Any) – Keyword arguments to format.

Return type:

str

Returns:

str – The formatted string.

format_field(value, format_spec)[source]¶

Format a value given a formatting spec.

If format_spec is in this Formatter’s modifiers, the corresponding variation of value is given. If format_spec is ‘r’ (raw), the value is returned unmodified. If format_spec is not specified but value is in the mapping, the first variation is returned.

Parameters:

value (Any) – The value to format.
format_spec (str) – The formatting spec.

Return type:

str

Returns:

str – The formatted value.

Examples

Let’s say the string “The dog is {adj1}, the goose is {adj2}” is to be translated to French and that we know that possible values of adj are nice and evil. In French, the genre of the noun changes the adjective (cat = chat is masculine, and goose = oie is feminine) so we initialize the formatter as:

>>> fmt = AttrFormatter(
...     {
...         "nice": ["beau", "belle"],
...         "evil": ["méchant", "méchante"],
...         "smart": ["intelligent", "intelligente"],
...     },
...     ["m", "f"],
... )
>>> fmt.format(
...     "Le chien est {adj1:m}, l'oie est {adj2:f}, le gecko est {adj3:r}",
...     adj1="nice",
...     adj2="evil",
...     adj3="smart",
... )
"Le chien est beau, l'oie est méchante, le gecko est smart"

The base values may be given using unix shell-like patterns:

>>> fmt = AttrFormatter(
...     {"YS-*": ["annuel", "annuelle"], "MS": ["mensuel", "mensuelle"]},
...     ["m", "f"],
... )
>>> fmt.format(
...     "La moyenne {freq:f} est faite sur un échantillon {src_timestep:m}",
...     freq="YS-JUL",
...     src_timestep="MS",
... )
'La moyenne annuelle est faite sur un échantillon mensuel'

xclim.core.formatting.capitalize_free_text(text, sep='. ')[source]¶

Ensure each sentence of the text begins with an uppercase letter.

Parameters:

text (str) – A string.
sep (str) – The separator indicating the end and the beginning of sentences, in addition to the first letter of the text.

Returns:

str – The capitalized text. In opposition to str.capitalize(), case of letters not at the beginning of a sentence is preserved.

xclim.core.formatting.gen_call_string(funcname, *args, **kwargs)[source]¶

Generate a signature string for use in the history attribute.

DataArrays and Dataset are replaced with their name, while Nones, floats, ints and strings are printed directly. All other objects have their type printed between < >.

Arguments given through positional arguments are printed positionnally and those given through keywords are printed prefixed by their name.

Parameters:

funcname (str) – Name of the function.
*args (Any) – Arguments given to the function.
**kwargs (Any) – Keyword arguments given to the function.

Return type:

str

Returns:

str – The formatted string.

Examples

>>> A = xr.DataArray([1], dims=("x",), name="A")
>>> gen_call_string("func", A, b=2.0, c="3", d=[10] * 100)
"func(<A array>, b=2.0, c='3', d=<list>)"

xclim.core.formatting.get_percentile_metadata(data, prefix)[source]¶

Get the metadata related to percentiles from the given DataArray as a dictionary.

Parameters:

data (xr.DataArray) – Must be a percentile DataArray, this means the necessary metadata must be available in its attributes and coordinates.
prefix (str) – The prefix to be used in the metadata key. Usually this takes the form of “tasmin_per” or equivalent.

Return type:

dict[str, str]

Returns:

dict – A mapping of the configuration used to compute these percentiles.

xclim.core.formatting.merge_attributes(attribute, *inputs_list, new_line='\\n', missing_str=None, **inputs_kws)[source]¶

Merge attributes from several DataArrays or Datasets.

If more than one input is given, its name (if available) is prepended as: “<input name> : <input attribute>”.

Parameters:

attribute (str) – The attribute to merge.
*inputs_list (xr.DataArray or xr.Dataset) – The datasets or variables that were used to produce the new object. Inputs given that way will be prefixed by their name attribute if available.
new_line (str) – The character to put between each instance of the attributes. Usually, in CF-conventions, the history attributes uses ‘\n’ while cell_methods uses ‘ ‘.
missing_str (str) – A string that is printed if an input doesn’t have the attribute. Defaults to None, in which case the input is simply skipped.
**inputs_kws (xr.DataArray or xr.Dataset) – Mapping from names to the datasets or variables that were used to produce the new object. Inputs given that way will be prefixes by the passed name.

Return type:

str

Returns:

str – The new attribute made from the combination of the ones from all the inputs.

xclim.core.formatting.prefix_attrs(source, keys, prefix)[source]¶

Rename some keys of a dictionary by adding a prefix.

Parameters:

source (dict) – Source dictionary, for example data attributes.
keys (sequence) – Names of keys to prefix.
prefix (str) – Prefix to prepend to keys.

Return type:

dict

Returns:

dict – Dictionary of attributes with some keys prefixed.

xclim.core.formatting.unprefix_attrs(source, keys, prefix)[source]¶

Remove prefix from keys in a dictionary.

Parameters:

source (dict) – Source dictionary, for example data attributes.
keys (sequence) – Names of original keys for which prefix should be removed.
prefix (str) – Prefix to remove from keys.

Return type:

dict

Returns:

dict – Dictionary of attributes whose keys were prefixed, with prefix removed.

xclim.core.formatting.update_history(hist_str, *inputs_list, new_name=None, **inputs_kws)[source]¶

Return a history string with the timestamped message and the combination of the history of all inputs.

The new history entry is formatted as “[<timestamp>] <new_name>: <hist_str> - xclim version: <xclim.__version__>.”

Parameters:

hist_str (str) – The string describing what has been done on the data.
*inputs_list (xr.DataArray or xr.Dataset) – The datasets or variables that were used to produce the new object. Inputs given that way will be prefixed by their “name” attribute if available.
new_name (str, optional) – The name of the newly created variable or dataset to prefix hist_msg.
**inputs_kws (xr.DataArray or xr.Dataset) – Mapping from names to the datasets or variables that were used to produce the new object. Inputs given that way will be prefixes by the passed name.

Return type:

str

Returns:

str – The combine history of all inputs starting with hist_str.

Internationalization module¶

This module defines methods and object to help the internationalization of metadata for climate indicators computed by xclim. Go to Adding translated metadata to see how to use this feature.

All the methods and objects in this module use localization data given in JSON files. These files are expected to be defined as in this example for French:

{
    "attrs_mapping": {
        "modifiers": ["", "f", "mpl", "fpl"],
        "YS": ["annuel", "annuelle", "annuels", "annuelles"],
        "YS-*": ["annuel", "annuelle", "annuels", "annuelles"],
        # ... and so on for other frequent parameters translation...
    },
    "dtrvar": {
        "long_name": "Variabilité de l'amplitude de la température diurne",
        "description": "Variabilité {freq:f} de l'amplitude de la température diurne (définie comme la moyenne de la variation journalière de l'amplitude de température sur une période donnée)",
        "title": "Variation quotidienne absolue moyenne de l'amplitude de la température diurne",
        "comment": "",
        "abstract": "La valeur absolue de la moyenne de l'amplitude de la température diurne.",
    },
    # ... and so on for other indicators...
}

Indicators are named by their identifier, the same as in the indicator registry (xclim.core.indicators.registry), but which can differ from the callable name. In the example above, the indicator is usually called in python code using atmos.daily_temperature_range_variability, but its identifier is dtrvar. Use the ind.identifier accessor to get its registry name, they are case-insensitive.

Accordingly, when writing a translation file for an IndicatorCollection, the keys to use are the same as the ones in the indicators section of the collection’s YAML file.

Here, the usual parameter passed to the formatting of “description” is “freq” and is usually translated from “YS” to “annual”. However, in French and in this sentence, the feminine form should be used, so the “f” modifier is added by the translator so that the formatting function knows which translation to use. Acceptable entries for the mappings are limited to what is already defined in xclim.core.indicators.utils.default_formatter.

For user-provided internationalization dictionaries, only the “attrs_mapping” and its “modifiers” key are mandatory, all other entries (translations of frequent parameters and all indicator entries) are optional. For xclim-provided translations (for now only French), all indicators must have en entry and the “attrs_mapping” entries must match exactly the default formatter. Those default translations are found in the xclim/locales folder.

xclim.core.locales.TRANSLATABLE_ATTRS = ['long_name', 'description', 'comment', 'title', 'abstract']¶: List of attributes to consider translatable when generating locale dictionaries.

exception xclim.core.locales.UnavailableLocaleError(locale)[source]¶

Error raised when a locale is requested but doesn’t exist.

Parameters:: locale (str) – The locale code.

xclim.core.locales.generate_local_dict(locale, init_english=False)[source]¶

Generate a dictionary with keys for each indicator and translatable attributes.

Parameters:

locale (str) – Locale in the IETF format.
init_english (bool) – If True, fills the initial dictionary with the english versions of the attributes. Defaults to False.

Return type:

CaseInsensitiveDict

Returns:

dict – Indicator translation dictionary.

xclim.core.locales.get_local_attrs(indicator, locale, var_name=None, names=None, append_locale_name=True)[source]¶

Get all attributes of an indicator in the requested locale.

Parameters:

indicator (str or sequence of strings) – Indicator’s identifier, usually the same as in xc.core.indicator.registry. If multiple names are passed, the attrs from each indicator are merged, with the highest priority set to the first name.
locale (str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.
var_name (str, optional) – For multi-output indicator, this is the name of the variable for which we request attributes.
names (sequence of str, optional) – If given, only returns translations of attributes in this list.
append_locale_name (bool) – If True (default), append the language tag (as “{attr_name}_{locale}”) to the returned attributes.

Return type:

dict

Returns:

dict – All attributes available for given indicator and locales. Warns and returns an empty dict if none were available.

Raises:

ValueError – If append_locale_name is False and multiple locales are requested.

xclim.core.locales.get_local_dict(locale)[source]¶

Return all translated metadata for a given locale.

Parameters:

locale (str or sequence of str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.

Return type:

tuple[str, dict]

Returns:

str – The best fitting locale string.
dict – The available translations in this locale.

Raises:

UnavailableLocaleError – If the given locale is not available.

xclim.core.locales.get_local_formatter(locale)[source]¶

Return an AttrFormatter instance for the given locale.

Parameters:: locale (str or tuple of str) – IETF language tag or a tuple of the language tag and a translation dict, or a tuple of the language tag and a path to a json file defining translation of attributes.
Return type:: AttrFormatter
Returns:: AttrFormatter – A locale-based formatter object instance.

xclim.core.locales.list_locales()[source]¶

List of loaded locales.

Includes all loaded locales, no matter how complete the translations are.

Return type:: list
Returns:: list – A list of available locales.

xclim.core.locales.load_locale(locdata, locale)[source]¶

Load translations from a json file into xclim.

Parameters:

locdata (str or Path or dictionary) – Either a loaded locale dictionary or a path to a json file.
locale (str) – The locale name (IETF tag).

Return type:

None

xclim.core.locales.read_locale_file(filename, module=None, encoding='UTF8')[source]¶

Read a locale file (.json) and return its dictionary.

Parameters:

filename (PathLike) – The file to read.
module (str, optional) – If the module is a string, this module name is added to all identifiers translated in this file. Defaults to None, and no module name is added (as if the indicator was an official xclim indicator).
encoding (str) – The encoding to use when reading the file. Defaults to UTF-8, overriding Python’s default mechanism which is machine-dependent.

Return type:

dict[str, dict]

Returns:

dict – The locale dictionary. All entries are lowercase.

Options Submodule¶

Global or contextual options for xclim, similar to xarray.set_options.

xclim.core.options.cfcheck(func)[source]¶

Decorate functions checking CF-compliance of DataArray attributes.

Functions should raise ValidationError exceptions whenever attributes are non-conformant.

Parameters:: func (Callable) – Function to decorate.
Return type:: Callable
Returns:: Callable – Decorated function.

xclim.core.options.datacheck(func)[source]¶

Decorate functions checking data inputs validity.

Parameters:: func (Callable) – Function to decorate.
Return type:: Callable
Returns:: Callable – Decorated function.

xclim.core.options.register_missing_method(name)[source]¶

Parameters:: name (str) – Name of missing method.
Return type:: Callable
Returns:: Callable – Decorator function.

xclim.core.options.run_check(func, option, *args, **kwargs)[source]¶

Run function and customize exception handling based on option.

Parameters:

func (Callable) – Function to run.
option (str) – Option to use.
*args (tuple) – Positional arguments to pass to the function.
**kwargs (dict) – Keyword arguments to pass to the function.

Raises:

ValidationError – If the function raises a ValidationError and the option is set to “raise”.

Miscellaneous Utilities¶

Helper functions for the computations, indicator construction and other things.

class xclim.core.utils.CaseInsensitiveDict(data=None)[source]¶

Bases: collections.abc.MutableMapping[str, Any]

A basic dictionary but keys are strings and case-insensitive, stored all lowercase.

get(key, default=None)[source]¶

Return type:: Any

setdefault(key, default=None)[source]¶

Return type:: Any

update(other, **kwargs)[source]¶

If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

items()[source]¶

Return type:: Iterator[tuple[str, Any]]

keys()[source]¶

Return type:: Iterator[str]

pop(key)[source]¶

If key is not found, d is returned if given, otherwise KeyError is raised.

Return type:: Any

popitem()[source]¶

as a 2-tuple; but raise KeyError if D is empty.

Return type:: tuple[str, Any]

copy()[source]¶

Return type:: CaseInsensitiveDict

xclim.core.utils.deprecated(from_version, suggested=None)[source]¶

Mark an index as deprecated and optionally suggest a replacement.

Parameters:

from_version (str, optional) – The version of xclim from which the function is deprecated.
suggested (str, optional) – The name of the function to use instead.

Return type:

Callable

Returns:

Callable – The decorated function.

xclim.core.utils.load_module(path, name=None)[source]¶

Load a python module from a python file, optionally changing its name.

Parameters:

path (os.PathLike) – The path to the python file.
name (str, optional) – The name to give to the module. If None, the module name will be the stem of the path.

Return type:

ModuleType

Returns:

ModuleType – The loaded module.

Examples

Given a path to a module file (.py):

from pathlib import Path
import os

path = Path("path/to/example.py")

The two following imports are equivalent, the second uses this method.

os.chdir(path.parent)
import example as mod1

os.chdir(previous_working_dir)
mod2 = load_module(path)
mod1 == mod2

xclim.core.utils.ensure_chunk_size(da, **minchunks)[source]¶

Ensure that the input DataArray has chunks of at least the given size.

If only one chunk is too small, it is merged with an adjacent chunk. If many chunks are too small, they are grouped together by merging adjacent chunks.

Parameters:

da (xr.DataArray) – The input DataArray, with or without the dask backend. Does nothing when passed a non-dask array.
**minchunks (dict[str, int]) – A kwarg mapping from dimension name to minimum chunk size. Pass -1 to force a single chunk along that dimension.

Return type:

DataArray

Returns:

xr.DataArray – The input DataArray, possibly rechunked.

xclim.core.utils.uses_dask(*das)[source]¶

Evaluate whether dask is installed and array is loaded as a dask array.

Parameters:: *das (xr.DataArray or xr.Dataset) – DataArrays or Datasets to check.
Return type:: bool
Returns:: bool – True if any of the passed objects is using dask.

xclim.core.utils.lazy_indexing(da, index, dim=None)[source]¶

Get values of da at indices index in a NaN-aware and lazy manner.

Parameters:

da (xr.DataArray) – Input array. If not 1D, dim must be given and must not appear in index.
index (xr.DataArray) – N-d integer indices, if DataArray is not 1D, all dimensions of index must be in DataArray.
dim (str, optional) – Dimension along which to index, unused if da is 1D, should not be present in index.

Return type:

DataArray

Returns:

xr.DataArray – Values of da at indices index.

xclim.core.utils.calc_perc(arr, percentiles=None, alpha=1.0, beta=1.0, copy=True)[source]¶

Compute percentiles using nan_calc_percentiles and move the percentiles’ axis to the end.

Parameters:

arr (array_like) – The input array.
percentiles (sequence of float, optional) – The percentiles to compute. If None, only the median is computed.
alpha (float) – A constant used to correct the index computed.
beta (float) – A constant used to correct the index computed.
copy (bool) – If True, the input array is copied before computation. Default is True.

Return type:

ndarray

Returns:

np.ndarray – The percentiles along the last axis.

xclim.core.utils.nan_calc_percentiles(arr, percentiles=None, axis=-1, alpha=1.0, beta=1.0, copy=True)[source]¶

Convert the percentiles to quantiles and compute them using _nan_quantile.

Parameters:

arr (array_like) – The input array.
percentiles (sequence of float, optional) – The percentiles to compute. If None, only the median is computed.
axis (int) – The axis along which to compute the percentiles.
alpha (float) – A constant used to correct the index computed.
beta (float) – A constant used to correct the index computed.
copy (bool) – If True, the input array is copied before computation. Default is True.

Return type:

ndarray

Returns:

np.ndarray – The percentiles along the specified axis.

xclim.core.utils.make_clix_meta_yaml(raw, adapted)[source]¶

Read in the clix-meta “index_definitions.yml” file and adapt it to a xclim virtual module yaml.

Parameters:

raw (os.PathLike or StringIO or str) – The path to the clix-meta “index_definitions.yml” file or the string representation of the yaml.
adapted (os.PathLike) – The path where to write the adapted yaml.

Return type:

None

xclim.core.utils.split_auxiliary_coordinates(obj)[source]¶

Split auxiliary coords from the dataset.

An auxiliary coordinate is a coordinate variable that does not define a dimension and thus is not necessarily needed for dataset alignment. Any coordinate that has a name different from its dimension(s) is flagged as auxiliary. All scalar coordinates are flagged as auxiliary.

Parameters:

obj (xr.DataArray or xr.Dataset) – An xarray object.

Return type:

tuple[DataArray | Dataset, DataArray]

Returns:

clean_obj (xr.DataArray or xr.Dataset) – Same as obj but without any auxiliary coordinate.
aux_crd_ds (xr.Dataset) – The auxiliary coordinates as a dataset. Might be empty.

Notes

This is useful to circumvent xarray’s alignment checks that will sometimes look the auxiliary coordinate’s data, which can trigger unwanted dask computations.

The auxiliary coordinates can be merged back with the dataset with xarray.Dataset.assign_coords() or xarray.DataArray.assign_coords().

clean, aux = split_auxiliary_coordinates(ds)
merged = clean.assign_coords(da.coords)
merged.identical(ds)  # -> True

xclim.core.utils.get_temp_dimname(dims, new_dim)[source]¶

Get an new dimension name based on new_dim, that is not used in dims.

Parameters:

dims (sequence of str) – The dimension names that already exist.
new_dim (str) – The new name we want.

Return type:

str

Returns:

str – The new dimension name with as many underscores prepended as necessary to make it unique.

Command line interface¶

Command Line Interface module¶

class xclim.cli.XclimCli(name=None, commands=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **kwargs)[source]¶

Bases: click.core.Group

Main cli class.

get_command(ctx, cmd_name)[source]¶

Return the requested command.

Return type:: Command

list_commands(ctx)[source]¶

Return the available commands (other than the indicators).

Return type:: tuple[str, str, str, str, str, str]

xclim.cli.write_file(ctx, *_, **kwargs)[source]¶: Write the output dataset to file.

Testing¶

Testing and Tutorial Utilities’ Module¶

xclim.testing.utils.TESTDATA_BRANCH = 'v2025.4.29'¶

Sets the branch of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_BRANCH="my_testing_branch"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_BRANCH="my_testing_branch" pytest

xclim.testing.utils.TESTDATA_CACHE_DIR = PosixPath('/home/docs/.cache/xclim-testdata')¶

Sets the directory to store the testing datasets.

If not set, the default location will be used (based on platformdirs, see pooch.os_cache()).

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_CACHE_DIR="/path/to/my/data"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_CACHE_DIR="/path/to/my/data" pytest

xclim.testing.utils.TESTDATA_REPO_URL = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/'¶

Sets the URL of the testing data repository to use when fetching datasets.

Notes

When running tests locally, this can be set for both pytest and tox by exporting the variable:

$ export XCLIM_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata"

or setting the variable at runtime:

$ env XCLIM_TESTDATA_REPO_URL="https://github.com/my_username/xclim-testdata" pytest

xclim.testing.utils.audit_url(url, context=None)[source]¶

Check if the URL is well-formed.

Parameters:

url (str) – The URL to check.
context (str, optional) – Additional context to include in the error message. Default is None.

Return type:

str

Returns:

str – The URL if it is well-formed.

Raises:

URLError – If the URL is not well-formed.

xclim.testing.utils.default_testdata_cache = PosixPath('/home/docs/.cache/xclim-testdata')¶: Default location for the testing data cache.

xclim.testing.utils.default_testdata_repo_url = 'https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/'¶: Default URL of the testing data repository to use when fetching datasets.

xclim.testing.utils.default_testdata_version = 'v2025.4.29'¶: Default version of the testing data to use when fetching datasets.

xclim.testing.utils.gather_testing_data(worker_cache_dir, worker_id, _cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'))[source]¶

Gather testing data across workers.

Parameters:

worker_cache_dir (str or Path) – The directory to store the testing data.
worker_id (str) – The worker ID.
_cache_dir (str or Path, optional) – The directory to store the testing data. Default is None.

Raises:

ValueError – If the cache directory is not set.
FileNotFoundError – If the testing data is not found.

Return type:

None

xclim.testing.utils.list_input_variables(submodules=None, realms=None)[source]¶

List all possible variables names used in xclim’s indicators.

Made for development purposes. Parses all indicator parameters with the xclim.core.utils.InputKind.VARIABLE or OPTIONAL_VARIABLE kinds.

Parameters:

submodules (str, optional) – Restrict the output to indicators of a list of submodules only. Default None, which parses all indicators.
realms (Sequence of str, optional) – Restrict the output to indicators of a list of realms only. Default None, which parses all indicators.

Return type:

dict

Returns:

dict – A mapping from variable name to indicator class.

xclim.testing.utils.nimbus(repo='https://raw.githubusercontent.com/Ouranosinc/xclim-testdata/', branch='v2025.4.29', cache_dir=PosixPath('/home/docs/.cache/xclim-testdata'), allow_updates=True)[source]¶

Pooch registry instance for xclim test data.

Parameters:

repo (str) – URL of the repository to use when fetching testing datasets.
branch (str) – Branch of repository to use when fetching testing datasets.
cache_dir (str or Path, optional) – The path to the directory where the data files are stored.
allow_updates (bool) – If True, allow updates to the data files. Default is True.

Returns:

pooch.Pooch – The Pooch instance for accessing the xclim testing data.

Notes

There are three environment variables that can be used to control the behaviour of this registry:

XCLIM_TESTDATA_CACHE_DIR: If this environment variable is set, it will be used as the base directory to store the data files. The directory should be an absolute path (i.e., it should start with /). Otherwise, the default location will be used (based on platformdirs, see pooch.os_cache()).
XCLIM_TESTDATA_REPO_URL: If this environment variable is set, it will be used as the URL of the repository to use when fetching datasets. Otherwise, the default repository will be used.
XCLIM_TESTDATA_BRANCH: If this environment variable is set, it will be used as the branch of the repository to use when fetching datasets. Otherwise, the default branch will be used.

Examples

Using the registry to download a file:

import xarray as xr
from xclim.testing.helpers import nimbus

example_file = nimbus().fetch("example.nc")
data = xr.open_dataset(example_file)

xclim.testing.utils.open_dataset(name, nimbus_kwargs=None, **xr_kwargs)[source]¶

Convenience function to open a dataset from the xclim testing data using the nimbus class.

This is a thin wrapper around the nimbus class to make it easier to open xclim testing datasets.

Parameters:

name (str) – Name of the file containing the dataset.
nimbus_kwargs (dict) – Keyword arguments passed to the nimbus function.
**xr_kwargs (Any) – Keyword arguments passed to xarray.open_dataset.

Return type:

Dataset

Returns:

xarray.Dataset – The dataset.