API

Indicators

Indicators are the main tool xclim provides to compute climate indices. In contrast to the function defined in xclim.indices, Indicators add a layer of health checks and metadata handling. Indicator objects are split into realms : atmos, land and seaIce.

Virtual modules are also inserted here. A normal installation of xclim comes with three virtual modules:

• xclim.indicators.cf, Indicators defined in cf-index-meta.

• xclim.indicators.icclim, Indicators defined by ECAD, as found in python package Icclim.

• xclim.indicators.anuclim, Indicators of the Australian National University’s Fenner School of Environment and Society.

Climate Indicators API

Atmospheric Indicators

While the indices module stores the computing functions, this module defines Indicator classes and instances that include a number of functionalities, such as input validation, unit conversion, output meta-data handling, and missing value masking.

The concept followed here is to define Indicator subclasses for each input variable, then create instances for each indicator.

xclim.indicators.atmos.biologically_effective_degree_days(tasmin='tasmin', tasmax='tasmax', lat='lat', *, thresh_tasmin='10 degC', method='gladstones', low_dtr='10 degC', high_dtr='13 degC', max_daily_degree_days='9 degC', start_date='04-01', end_date='11-01', freq='YS', ds=None)

Biologically effective degree days (realm: atmos)

Considers daily minimum and maximum temperature with a given base threshold between 1 April and 31 October, with a maximum daily value for cumulative degree days (typically 9°C), and integrates modification coefficients for latitudes between 40°N and 50°N as well as for swings in daily temperature range. Metric originally published in Gladstones (1992).

This indicator will check for missing values according to the method “from_context”. Based on indice biologically_effective_degree_days().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• lat (str or DataArray) – Latitude coordinate. If None and method in [“gladstones”, “icclim”], a CF-conformant “latitude” field must be available within the passed DataArray. Default : ds.lat. [Required units : []]

• thresh_tasmin (quantity (string or DataArray, with units)) – The minimum temperature threshold. Default : 10 degC. [Required units : [temperature]]

• method ({‘icclim’, ‘jones’, ‘gladstones’}) – The formula to use for the calculation. The “gladstones” integrates a daily temperature range and latitude coefficient. End_date should be “11-01”. The “icclim” method ignores daily temperature range and latitude coefficient. End date should be “10-01”. The “jones” method integrates axial tilt, latitude, and day-of-year on coefficient. End_date should be “11-01”. Default : gladstones.

• low_dtr (quantity (string or DataArray, with units)) – The lower bound for daily temperature range adjustment (default: 10°C). Default : 10 degC. [Required units : [temperature]]

• high_dtr (quantity (string or DataArray, with units)) – The higher bound for daily temperature range adjustment (default: 13°C). Default : 13 degC. [Required units : [temperature]]

• max_daily_degree_days (quantity (string or DataArray, with units)) – The maximum amount of biologically effective degrees days that can be summed daily. Default : 9 degC. [Required units : [temperature]]

• start_date (date (string, MM-DD)) – The hemisphere-based start date to consider (north = April, south = October). Default : 04-01.

• end_date (date (string, MM-DD)) – The hemisphere-based start date to consider (north = October, south = April). This date is non-inclusive. Default : 11-01.

• freq (offset alias (string)) – Resampling frequency (default: “YS”; For Southern Hemisphere, should be “AS-JUL”). Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

bedd (DataArray) – Integral of mean daily temperature above {thresh_tasmin}, with maximum value of {max_daily_degree_days}, multiplied by day-length coefficient and temperature range modifier based on {method} method for days between {start_date} and {end_date} [K days], with additional attributes: description: Heat-summation index for agroclimatic suitability estimation, developed specifically for viticulture. Computed with {method} formula (Summation of min((max((Tn + Tx)/2 - {thresh_tasmin}, 0) * k) + TR_adj, Dmax), where coefficient k is a latitude-based day-length for days between {start_date} and {end_date}), coefficient TR_adj is a modifier accounting for large temperature swings, and Dmax is the maximum possibleamount of degree days that can be gained within a day ({max_daily_degree_days}).

Notes

The tasmax ceiling of 19°C is assumed to be the max temperature beyond which no further gains from daily temperature occur. Indice originally published in Gladstones [1992].

Let \(TX_{i}\) and \(TN_{i}\) be the daily maximum and minimum temperature at day \(i\), \(lat\) the latitude of the point of interest, \(degdays_{max}\) the maximum amount of degrees that can be summed per day (typically, 9). Then the sum of daily biologically effective growing degree day (BEDD) units between 1 April and 31 October is:

\[BEDD_i = \sum_{i=\text{April 1}}^{\text{October 31}} min\left( \left( max\left( \frac{TX_i + TN_i)}{2} - 10, 0 \right) * k \right) + TR_{adj}, degdays_{max}\right)\]

\[\begin{split}TR_{adj} = f(TX_{i}, TN_{i}) = \begin{cases} 0.25(TX_{i} - TN_{i} - 13), & \text{if } (TX_{i} - TN_{i}) > 13 \\ 0, & \text{if } 10 < (TX_{i} - TN_{i}) < 13\\ 0.25(TX_{i} - TN_{i} - 10), & \text{if } (TX_{i} - TN_{i}) < 10 \\ \end{cases}\end{split}\]

\[k = f(lat) = 1 + \left(\frac{\left| lat \right|}{50} * 0.06, \text{if }40 < |lat| <50, \text{else } 0\right)\]

A second version of the BEDD (method=”icclim”) does not consider \(TR_{adj}\) and \(k\) and employs a different end date (30 September) [Project team ECA&D and KNMI, 2013]. The simplified formula is as follows:

\[BEDD_i = \sum_{i=\text{April 1}}^{\text{September 30}} min\left( max\left(\frac{TX_i + TN_i)}{2} - 10, 0\right), degdays_{max}\right)\]

References

Gladstones [1992], Project team ECA&D and KNMI [2013]

xclim.indicators.atmos.calm_days(sfcWind='sfcWind', *, thresh='2 m s-1', freq='MS', ds=None, **indexer)

Calm days (realm: atmos)

Number of days with surface wind speed below threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice calm_days().

Parameters:

• sfcWind (str or DataArray) – Daily windspeed. Default : ds.sfcWind. [Required units : [speed]]

• thresh (quantity (string or DataArray, with units)) – Threshold average near-surface wind speed on which to base evaluation. Default : 2 m s-1. [Required units : [speed]]

• freq (offset alias (string)) – Resampling frequency. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

calm_days (DataArray) – Number of days with surface wind speed below {thresh} (number_of_days_with_sfcWind_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with surface wind speed below {thresh}.

Notes

Let \(WS_{ij}\) be the windspeed at day \(i\) of period \(j\). Then counted is the number of days where:

\[WS_{ij} < Threshold [m s-1]\]

xclim.indicators.atmos.cffwis_indices(tas='tas', pr='pr', sfcWind='sfcWind', hurs='hurs', lat='lat', snd=None, ffmc0=None, dmc0=None, dc0=None, season_mask=None, *, season_method=None, overwintering=False, dry_start=None, initial_start_up=True, ds=None, **params)

Canadian Fire Weather Index System indices. (realm: atmos)

Computes the 6 fire weather indexes as defined by the Canadian Forest Service: the Drought Code, the Duff-Moisture Code, the Fine Fuel Moisture Code, the Initial Spread Index, the Build Up Index and the Fire Weather Index.

This indicator will check for missing values according to the method “skip”. Based on indice cffwis_indices().

Parameters:

• tas (str or DataArray) – Noon temperature. Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Rain fall in open over previous 24 hours, at noon. Default : ds.pr. [Required units : [precipitation]]

• sfcWind (str or DataArray) – Noon wind speed. Default : ds.sfcWind. [Required units : [speed]]

• hurs (str or DataArray) – Noon relative humidity. Default : ds.hurs. [Required units : []]

• lat (str or DataArray) – Latitude coordinate Default : ds.lat. [Required units : []]

• snd (str or DataArray, optional) – Noon snow depth, only used if season_method=’LA08’ is passed. [Required units : [length]]

• ffmc0 (str or DataArray, optional) – Initial values of the fine fuel moisture code. [Required units : []]

• dmc0 (str or DataArray, optional) – Initial values of the Duff moisture code. [Required units : []]

• dc0 (str or DataArray, optional) – Initial values of the drought code. [Required units : []]

• season_mask (str or DataArray, optional) – Boolean mask, True where/when the fire season is active. [Required units : []]

• season_method ({‘GFWED’, None, ‘WF93’, ‘LA08’}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given. Default : None.

• overwintering (boolean) – Whether to activate DC overwintering or not. If True, either season_method or season_mask must be given. Default : False.

• dry_start ({‘GFWED’, None, ‘CFS’}) – Whether to activate the DC and DMC “dry start” mechanism or not, see fire_weather_ufunc(). Default : None.

• initial_start_up (boolean) – If True (default), gridpoints where the fire season is active on the first timestep go through a start_up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points. Any other keyword parameters as defined in fire_weather_ufunc() and in default_params. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• params – Default : None.

Returns:

• dc (DataArray) – Drought Code (drought_code), with additional attributes: description: Numeric rating of the average moisture content of deep, compact organic layers.

• dmc (DataArray) – Duff Moisture Code (duff_moisture_code), with additional attributes: description: Numeric rating of the average moisture content of loosely compacted organic layers of moderate depth.

• ffmc (DataArray) – Fine Fuel Moisture Code (fine_fuel_moisture_code), with additional attributes: description: Numeric rating of the average moisture content of litter and other cured fine fuels.

• isi (DataArray) – Initial Spread Index (initial_spread_index), with additional attributes: description: Numeric rating of the expected rate of fire spread.

• bui (DataArray) – Buildup Index (buildup_index), with additional attributes: description: Numeric rating of the total amount of fuel available for combustion.

• fwi (DataArray) – Fire Weather Index (fire_weather_index), with additional attributes: description: Numeric rating of fire intensity.

Notes

See Natural Resources Canada [n.d.], the xclim.indices.fire module documentation, and the docstring of fire_weather_ufunc() for more information. This algorithm follows the official R code released by the CFS, which contains revisions from the original 1982 Fortran code.

References

Wang, Anderson, and Suddaby [2015]

xclim.indicators.atmos.cold_and_dry_days(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Cold and dry days (realm: atmos)

Number of days with temperature below a given percentile and precipitation below a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_and_dry_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – First quartile of daily mean temperature computed by month. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – First quartile of daily total precipitation computed by month. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

cold_and_dry_days (DataArray) – Number of days where temperature is below {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is below {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

Beniston [2009]

xclim.indicators.atmos.cold_and_wet_days(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Cold and wet days (realm: atmos)

Number of days with temperature below a given percentile and precipitation above a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_and_wet_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – First quartile of daily mean temperature computed by month. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Third quartile of daily total precipitation computed by month. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

cold_and_wet_days (DataArray) – Number of days where temperature is below {tas_per_thresh}th percentile and precipitation is above {pr_per_thresh}th percentile [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is below {tas_per_thresh}th percentile and precipitation is above {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

Beniston [2009]

xclim.indicators.atmos.cold_spell_days(tas='tas', *, thresh='-10 degC', window=5, freq='AS-JUL', op='<', resample_before_rl=True, ds=None)

Cold spell days (realm: atmos)

The number of days that are part of a cold spell. A cold spell is defined as a minimum number of consecutive days with mean daily temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_spell_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature below which a cold spell begins. Default : -10 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature below threshold to qualify as a cold spell. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cold_spell_days (DataArray) – Total number of days constituting events of at least {window} consecutive days where the mean daily temperature is below {thresh} (cold_spell_days) [days], with additional attributes: description: {freq} number of days that are part of a cold spell. A cold spell is defined as {window} or more consecutive days with mean daily temperature below {thresh}.

Notes

Let \(T_i\) be the mean daily temperature on day \(i\), the number of cold spell days during period \(\phi\) is given by:

\[\sum_{i \in \phi} \prod_{j=i}^{i+5} [T_j < thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.cold_spell_duration_index(tasmin='tasmin', tasmin_per='tasmin_per', *, window=6, freq='YS', resample_before_rl=True, bootstrap=False, op='<', ds=None)

Cold Spell Duration Index (CSDI) (realm: atmos)

Number of days part of a percentile-defined cold spell. A cold spell occurs when the daily minimum temperature is below a given percentile for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_spell_duration_index().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – nth percentile of daily minimum temperature with dayofyear coordinate. Default : ds.tasmin_per. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature below threshold to qualify as a cold spell. Default : 6.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

csdi_{window} (DataArray) – Total number of days constituting events of at least {window} consecutive days where the daily minimum temperature is below the {tasmin_per_thresh}th percentile (cold_spell_duration_index) [days], with additional attributes: description: {freq} number of days with at least {window} consecutive days where the daily minimum temperature is below the {tasmin_per_thresh}th percentile. A {tasmin_per_window} day(s) window, centred on each calendar day in the {tasmin_per_period} period, is used to compute the {tasmin_per_thresh}th percentile(s).

Notes

Let \(TN_i\) be the minimum daily temperature for the day of the year \(i\) and \(TN10_i\) the 10th percentile of the minimum daily temperature over the 1961-1990 period for day of the year \(i\), the cold spell duration index over period \(\phi\) is defined as:

\[\sum_{i \in \phi} \prod_{j=i}^{i+6} \left[ TN_j < TN10_j \right]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

References

From the Expert Team on Climate Change Detection, Monitoring and Indices (ETCCDMI; [Zhang et al., 2011]).

xclim.indicators.atmos.cold_spell_frequency(tas='tas', *, thresh='-10 degC', window=5, freq='AS-JUL', op='<', resample_before_rl=True, ds=None)

Cold spell frequency (realm: atmos)

The number of cold spell events. A cold spell is defined as a minimum number of consecutive days with mean daily temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_spell_frequency().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature below which a cold spell begins. Default : -10 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature below threshold to qualify as a cold spell. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cold_spell_frequency (DataArray) – Total number of series of at least {window} consecutive days where the mean daily temperature is below {thresh} (cold_spell_frequency), with additional attributes: description: {freq} number cold spell events. A cold spell is defined as a minimum number of consecutive days with mean daily temperature below {thresh}.

xclim.indicators.atmos.consecutive_frost_days(tasmin='tasmin', *, thresh='0 degC', freq='AS-JUL', resample_before_rl=True, ds=None)

Consecutive frost days (realm: atmos)

Maximum number of consecutive days where the daily minimum temperature is below 0°C

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_frost_days().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

consecutive_frost_days (DataArray) – Maximum number of consecutive days where minimum daily temperature is below {thresh} (spell_length_of_days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum number of consecutive days where minimum daily temperature is below {thresh}.

Notes

Let \(\mathbf{t}=t_0, t_1, \ldots, t_n\) be a minimum daily temperature series and \(thresh\) the threshold below which a day is considered a frost day. Let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([t_i < thresh] \neq [t_{i+1} < thresh]\), that is, the days where the temperature crosses the threshold. Then the maximum number of consecutive frost days is given by

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [t_{s_j} < thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

xclim.indicators.atmos.cool_night_index(tasmin='tasmin', *, lat=None, freq='YS', ds=None)

Cool night index (realm: atmos)

A night coolness variable which takes into account the mean minimum night temperatures during the month when ripening usually occurs beyond the ripening period.

This indicator will check for missing values according to the method “from_context”. Based on indice cool_night_index().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• lat ({‘south’, ‘north’}) – Latitude coordinate as an array, float or string. If None, a CF-conformant “latitude” field must be available within the passed DataArray. Default : None.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cool_night_index (DataArray) – Mean minimum temperature in late summer [degC], with additional attributes: cell_methods: time: mean over days; description: Mean minimum temperature for September (Northern hemisphere) or March (Southern hemisphere).

Notes

Given that this indice only examines September and March months, it is possible to send in DataArrays containing only these timesteps. Users should be aware that due to the missing values checks in wrapped Indicators, datasets that are missing several months will be flagged as invalid. This check can be ignored by setting the following context:

with xclim.set_options(check_missing="skip"):
    cni = cool_night_index(tasmin)

References

Tonietto and Carbonneau [2004]

xclim.indicators.atmos.cooling_degree_days(tas='tas', *, thresh='18.0 degC', freq='YS', ds=None, **indexer)

Cooling degree days (realm: atmos)

The cumulative degree days for days when the mean daily temperature is above a given threshold and buildings must be air conditioned.

This indicator will check for missing values according to the method “from_context”. Based on indice cooling_degree_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Temperature threshold above which air is cooled. Default : 18.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

cooling_degree_days (DataArray) – Cumulative sum of temperature degrees for mean daily temperature above {thresh} (integral_of_air_temperature_excess_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} cumulative cooling degree days (mean temperature above {thresh}).

Notes

Let \(x_i\) be the daily mean temperature at day \(i\). Then the cooling degree days above temperature threshold \(thresh\) over period \(\phi\) is given by:

\[\sum_{i \in \phi} (x_{i}-{thresh} [x_i > thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.corn_heat_units(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='4.44 degC', thresh_tasmax='10 degC', ds=None)

Corn heat units (realm: atmos)

A temperature-based index used to estimate the development of corn crops. Corn growth occurs when the daily minimum and maximum temperatures exceed given thresholds.

This indicator will check for missing values according to the method “skip”. Based on indice corn_heat_units().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The minimum temperature threshold needed for corn growth. Default : 4.44 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed for corn growth. Default : 10 degC. [Required units : [temperature]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

chu (DataArray) – Corn heat units (Tmin > {thresh_tasmin} and Tmax > {thresh_tasmax}), with additional attributes: description: Temperature-based index used to estimate the development of corn crops. Corn growth occurs when the minimum and maximum daily temperatures both exceed {thresh_tasmin} and {thresh_tasmax}, respectively.

Notes

Formula used in calculating the Corn Heat Units for the Agroclimatic Atlas of Quebec [Audet et al., 2012].

The thresholds of 4.44°C for minimum temperatures and 10°C for maximum temperatures were selected following the assumption that no growth occurs below these values.

Let \(TX_{i}\) and \(TN_{i}\) be the daily maximum and minimum temperature at day \(i\). Then the daily corn heat unit is:

\[CHU_i = \frac{YX_{i} + YN_{i}}{2}\]

with

\[ \begin{align}\begin{aligned}YX_i & = 3.33(TX_i -10) - 0.084(TX_i -10)^2, &\text{if } TX_i > 10°C\\YN_i & = 1.8(TN_i -4.44), &\text{if } TN_i > 4.44°C\end{aligned}\end{align} \]

Where \(YX_{i}\) and \(YN_{i}\) is 0 when \(TX_i \leq 10°C\) and \(TN_i \leq 4.44°C\), respectively.

References

Audet, Côté, Bachand, and Mailhot [2012], Bootsma, Tremblay, and Filion [1999]

xclim.indicators.atmos.daily_freezethaw_cycles(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='0 degC', thresh_tasmax='0 degC', op_tasmin='<=', op_tasmax='>', freq='YS', resample_before_rl=True, ds=None, **indexer)

Daily freeze-thaw cycles (realm: atmos)

The number of days with a freeze-thaw cycle. A freeze-thaw cycle is defined as a day where maximum daily temperature is above a given threshold and minimum daily temperature is at or below a given threshold, usually 0°C for both.

This indicator will check for missing values according to the method “from_context”. Based on indice multiday_temperature_swing(). With injected parameters: window=1, op=sum.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a freeze event. Default : 0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a thaw event. Default : 0 degC. [Required units : [temperature]]

• op_tasmin ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation for tasmin. Default: “<=”. Default : <=.

• op_tasmax ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation for tasmax. Default: “>”. Default : >.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

dlyfrzthw (DataArray) – Number of days where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} [days], with additional attributes: description: {freq} number of days with a diurnal freeze-thaw cycle, where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin}.

Notes

Let \(TX_{i}\) be the maximum temperature at day \(i\) and \(TN_{i}\) be the daily minimum temperature at day \(i\). Then freeze thaw spells during a given period are consecutive days where:

\[TX_{i} > 0℃ \land TN_{i} < 0℃\]

This indice returns a given statistic of the found lengths, optionally dropping those shorter than the window argument. For example, window=1 and op=’sum’ returns the same value as daily_freezethaw_cycles().

xclim.indicators.atmos.daily_pr_intensity(pr='pr', *, thresh='1 mm/day', freq='YS', op='>=', ds=None, **indexer)

Simple Daily Intensity Index (realm: atmos)

Average precipitation for days with daily precipitation above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_pr_intensity().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

sdii (DataArray) – Average precipitation during days with daily precipitation over {thresh} (Simple Daily Intensity Index: SDII) (lwe_thickness_of_precipitation_amount) [mm d-1], with additional attributes: description: {freq} Simple Daily Intensity Index (SDII) or {freq} average precipitation for days with daily precipitation over {thresh}.

Notes

Let \(\mathbf{p} = p_0, p_1, \ldots, p_n\) be the daily precipitation and \(thresh\) be the precipitation threshold defining wet days. Then the daily precipitation intensity is defined as:

\[\frac{\sum_{i=0}^n p_i [p_i \leq thresh]}{\sum_{i=0}^n [p_i \leq thresh]}\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.daily_temperature_range(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Mean of daily temperature range (realm: atmos)

The average difference between the daily maximum and minimum temperatures.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range(). With injected parameters: op=mean.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

dtr (DataArray) – Mean diurnal temperature range (air_temperature) [K], with additional attributes: cell_methods: time range within days time: mean over days; description: {freq} mean diurnal temperature range.

Notes

For a default calculation using op=’mean’ :

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the mean diurnal temperature range in period \(j\) is:

\[DTR_j = \frac{ \sum_{i=1}^I (TX_{ij} - TN_{ij}) }{I}\]

xclim.indicators.atmos.daily_temperature_range_variability(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Variability of daily temperature range (realm: atmos)

The average day-to-day variation in daily temperature range.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range_variability().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

dtrvar (DataArray) – Mean diurnal temperature range variability (air_temperature) [K], with additional attributes: cell_methods: time range within days time: difference over days time: mean over days; description: {freq} mean diurnal temperature range variability, defined as the average day-to-day variation in daily temperature range for the given time period.

Notes

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then calculated is the absolute day-to-day differences in period \(j\) is:

\[vDTR_j = \frac{ \sum_{i=2}^{I} |(TX_{ij}-TN_{ij})-(TX_{i-1,j}-TN_{i-1,j})| }{I}\]

xclim.indicators.atmos.days_over_precip_doy_thresh(pr='pr', pr_per='pr_per', *, thresh='1 mm/day', freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Number of days with precipitation above a given daily percentile (realm: atmos)

Number of days in a period where precipitation is above a given daily percentile and a fixed threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice days_over_precip_thresh().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – Percentile of wet day precipitation flux. Either computed daily (one value per day of year) or computed over a period (one value per spatial point). Default : ds.pr_per. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

days_over_precip_doy_thresh (DataArray) – Number of days with daily precipitation flux above the {pr_per_thresh}th percentile of {pr_per_period} (number_of_days_with_lwe_thickness_of_precipitation_amount_above_daily_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation above the {pr_per_thresh}th daily percentile. Only days with at least {thresh} are counted. A {pr_per_window} day(s) window, centered on each calendar day in the {pr_per_period} period, is used to compute the {pr_per_thresh}th percentile(s).

xclim.indicators.atmos.days_over_precip_thresh(pr='pr', pr_per='pr_per', *, thresh='1 mm/day', freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Number of days with precipitation above a given percentile (realm: atmos)

Number of days in a period where precipitation is above a given percentile, calculated over a given period and a fixed threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice days_over_precip_thresh().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – Percentile of wet day precipitation flux. Either computed daily (one value per day of year) or computed over a period (one value per spatial point). Default : ds.pr_per. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

days_over_precip_thresh (DataArray) – Number of days with precipitation flux above the {pr_per_thresh}th percentile of {pr_per_period} (number_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation above the {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are counted.

xclim.indicators.atmos.days_with_snow(prsn='prsn', *, low='0 kg m-2 s-1', high='1E6 kg m-2 s-1', freq='AS-JUL', ds=None, **indexer)

Days with snowfall (realm: atmos)

Number of days with snow between a lower and upper limit.

This indicator will check for missing values according to the method “from_context”. Based on indice days_with_snow().

Parameters:

• prsn (str or DataArray) – Solid precipitation flux. Default : ds.prsn. [Required units : [precipitation]]

• low (quantity (string or DataArray, with units)) – Minimum threshold solid precipitation flux. Default : 0 kg m-2 s-1. [Required units : [precipitation]]

• high (quantity (string or DataArray, with units)) – Maximum threshold solid precipitation flux. Default : 1E6 kg m-2 s-1. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

days_with_snow (DataArray) – Number of days with solid precipitation flux between {low} and {high} thresholds [days], with additional attributes: description: {freq} number of days with solid precipitation flux larger than {low} and smaller or equal to {high}.

References

Matthews, Andrey, and Picketts [2017]

xclim.indicators.atmos.degree_days_exceedance_date(tas='tas', *, thresh='0 degC', sum_thresh='25 K days', op='>', after_date=None, freq='YS', ds=None)

Degree day exceedance date (realm: atmos)

The day of the year when the sum of degree days exceeds a threshold, occurring after a given date. Degree days are calculated above or below a given temperature threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice degree_days_exceedance_date().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base degree-days evaluation. Default : 0 degC. [Required units : [temperature]]

• sum_thresh (quantity (string or DataArray, with units)) – Threshold of the degree days sum. Default : 25 K days. [Required units : K days]

• op ({‘<’, ‘gt’, ‘ge’, ‘le’, ‘>’, ‘>=’, ‘<=’, ‘lt’}) – If equivalent to ‘>’, degree days are computed as tas - thresh and if equivalent to ‘<’, they are computed as thresh - tas. Default : >.

• after_date (date (string, MM-DD)) – Date at which to start the cumulative sum. In “mm-dd” format, defaults to the start of the sampling period. Default : None.

• freq (offset alias (string)) – Resampling frequency. If after_date is given, freq should be annual. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

degree_days_exceedance_date (DataArray) – Day of year when the integral of mean daily temperature {op} {thresh} exceeds {sum_thresh} (day_of_year), with additional attributes: description: <Dynamically generated string>

Notes

Let \(TG_{ij}\) be the daily mean temperature at day \(i\) of period \(j\), \(T\) is the reference threshold and \(ST\) is the sum threshold. Then, starting at day :math:i_0:, the degree days exceedance date is the first day \(k\) such that

\[\begin{split}\begin{cases} ST < \sum_{i=i_0}^{k} \max(TG_{ij} - T, 0) & \text{if $op$ is '>'} \\ ST < \sum_{i=i_0}^{k} \max(T - TG_{ij}, 0) & \text{if $op$ is '<'} \end{cases}\end{split}\]

The resulting \(k\) is expressed as a day of year.

Cumulated degree days have numerous applications including plant and insect phenology. See https://en.wikipedia.org/wiki/Growing_degree-day for examples (Wikipedia Contributors [2021]).

xclim.indicators.atmos.drought_code(tas='tas', pr='pr', lat='lat', snd=None, dc0=None, season_mask=None, *, season_method=None, overwintering=False, dry_start=None, initial_start_up=True, ds=None, **params)

Daily drought code (realm: atmos)

The Drought Index is part of the Canadian Forest-Weather Index system. It is a numerical code that estimates the average moisture content of organic layers.

This indicator will check for missing values according to the method “skip”. Based on indice drought_code().

Parameters:

• tas (str or DataArray) – Noon temperature. Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Rain fall in open over previous 24 hours, at noon. Default : ds.pr. [Required units : [precipitation]]

• lat (str or DataArray) – Latitude coordinate Default : ds.lat. [Required units : []]

• snd (str or DataArray, optional) – Noon snow depth. [Required units : [length]]

• dc0 (str or DataArray, optional) – Initial values of the drought code. [Required units : []]

• season_mask (str or DataArray, optional) – Boolean mask, True where/when the fire season is active. [Required units : []]

• season_method ({‘GFWED’, None, ‘WF93’, ‘LA08’}) – How to compute the start-up and shutdown of the fire season. If “None”, no start-ups or shutdowns are computed, similar to the R fire function. Ignored if season_mask is given. Default : None.

• overwintering (boolean) – Whether to activate DC overwintering or not. If True, either season_method or season_mask must be given. Default : False.

• dry_start ({‘GFWED’, None, ‘CFS’}) – Whether to activate the DC and DMC “dry start” mechanism and which method to use. See fire_weather_ufunc(). Default : None.

• initial_start_up (boolean) – If True (default), grid points where the fire season is active on the first timestep go through a start_up phase for that time step. Otherwise, previous codes must be given as a continuing fire season is assumed for those points. Any other keyword parameters as defined in xclim.indices.fire.fire_weather_ufunc and in default_params. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• params – Default : None.

Returns:

dc (DataArray) – Drought Code (drought_code), with additional attributes: description: Numerical code estimating the average moisture content of organic layers.

Notes

See Natural Resources Canada [n.d.], the xclim.indices.fire module documentation, and the docstring of fire_weather_ufunc() for more information. This algorithm follows the official R code released by the CFS, which contains revisions from the original 1982 Fortran code.

References

Wang, Anderson, and Suddaby [2015]

xclim.indicators.atmos.dry_days(pr='pr', *, thresh='0.2 mm/d', freq='YS', op='<', ds=None, **indexer)

Number of dry days (realm: atmos)

The number of days with daily precipitation under a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice dry_days().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0.2 mm/d. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

dry_days (DataArray) – Number of dry days (number_of_days_with_lwe_thickness_of_precipitation_amount_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with daily precipitation under {thresh}.

Notes

Let \(PR_{ij}\) be the daily precipitation at day \(i\) of period \(j\). Then counted is the number of days where:

\[\sum PR_{ij} < Threshold [mm/day]\]

xclim.indicators.atmos.dry_spell_frequency(pr='pr', *, thresh='1.0 mm', window=3, freq='YS', resample_before_rl=True, op='sum', ds=None)

Dry spell frequency (realm: atmos)

The frequency of dry periods of N days or more, during which the accumulated or maximum precipitation over a given time window of days is below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice dry_spell_frequency().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation amount under which a period is considered dry. The value against which the threshold is compared depends on op . Default : 1.0 mm. [Required units : [length]]

• window (number) – Minimum length of the spells. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• op ({‘max’, ‘sum’}) – Operation to perform on the window. Default is “sum”, which checks that the sum of accumulated precipitation over the whole window is less than the threshold. “max” checks that the maximal daily precipitation amount within the window is less than the threshold. This is the same as verifying that each individual day is below the threshold. Default : sum.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

dry_spell_frequency (DataArray) – Number of dry periods of {window} day(s) or more, during which the {op} precipitation on a window of {window} day(s) is below {thresh}., with additional attributes: description: The {freq} number of dry periods of {window} day(s) or more, during which the {op} precipitation on a window of {window} day(s) is below {thresh}.

xclim.indicators.atmos.dry_spell_total_length(pr='pr', *, thresh='1.0 mm', window=3, op='sum', freq='YS', resample_before_rl=True, ds=None, **indexer)

Dry spell total length (realm: atmos)

The total length of dry periods of N days or more, during which the accumulated or maximum precipitation over a given time window of days is below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice dry_spell_total_length().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Accumulated precipitation value under which a period is considered dry. Default : 1.0 mm. [Required units : [length]]

• window (number) – Number of days when the maximum or accumulated precipitation is under threshold. Default : 3.

• op ({‘max’, ‘sum’}) – Reduce operation. Default : sum.

• freq (offset alias (string)) – Resampling frequency. Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Indexing is done after finding the dry days, but before finding the spells. Default : YS.

• resample_before_rl (boolean) – Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Default : None.

Returns:

dry_spell_total_length (DataArray) – Number of days in dry periods of {window} day(s) or more, during which the {op} precipitation within windows of {window} day(s) is under {thresh}. [days], with additional attributes: description: The {freq} number of days in dry periods of {window} day(s) or more, during which the {op} precipitation within windows of {window} day(s) is under {thresh}.

Notes

The algorithm assumes days before and after the timeseries are “wet”, meaning that the condition for being considered part of a dry spell is stricter on the edges. For example, with window=3 and op=’sum’, the first day of the series is considered part of a dry spell only if the accumulated precipitation within the first three days is under the threshold. In comparison, a day in the middle of the series is considered part of a dry spell if any of the three 3-day periods of which it is part are considered dry (so a total of five days are included in the computation, compared to only three).

xclim.indicators.atmos.dryness_index(pr='pr', evspsblpot='evspsblpot', *, lat=None, wo='200 mm', freq='YS', ds=None)

Dryness index (realm: atmos)

The dryness index is a characterization of the water component in winegrowing regions which considers the precipitation and evapotranspiration factors without deduction for surface runoff or drainage. Metric originally published in Riou et al. (1994).

This indicator will check for missing values according to the method “from_context”. Based on indice dryness_index().

Parameters:

• pr (str or DataArray) – Precipitation. Default : ds.pr. [Required units : [precipitation]]

• evspsblpot (str or DataArray) – Potential evapotranspiration. Default : ds.evspsblpot. [Required units : [precipitation]]

• lat ({‘south’, ‘north’}) – Latitude coordinate as an array, float or string. If None, a CF-conformant “latitude” field must be available within the passed DataArray. Default : None.

• wo (quantity (string or DataArray, with units)) – The initial soil water reserve accessible to root systems [length]. Default: 200 mm. Default : 200 mm. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

dryness_index (DataArray) – Growing season humidity [mm], with additional attributes: description: Estimation of growing season humidity (precipitation minus adjusted evapotranspiration) for the period of April to September (Northern Hemisphere) or October to March (Southern Hemisphere), with initial soil moisture content set to {wo} and an adjustment based on monthly precipitation and evapotranspiration limits.

Notes

Given that this indice only examines monthly total accumulations for six-month periods depending on the hemisphere, it is possible to send in DataArrays containing only these timesteps. Users should be aware that due to the missing values checks in wrapped Indicators, datasets that are missing several months will be flagged as invalid. This check can be ignored by setting the following context:

with xclim.set_options(check_missing="skip"):
    di = dryness_index(pr, evspsblpot)

Let \(Wo\) be the initial useful soil water reserve (typically “200 mm”), \(P\) be precipitation, \(T_{v}\) be the potential transpiration in the vineyard, and \(E_{s}\) be the direct evaporation from the soil. Then the Dryness Index, or the estimate of soil water reserve at the end of a period (1 April to 30 September in the Northern Hemispherere or 1 October to 31 March in the Southern Hemisphere), can be given by the following formulae:

\[W = \sum_{\text{April 1}}^{\text{September 30}} \left( Wo + P - T_{v} - E_{s} \right)\]

or (for the Southern Hemisphere):

\[W = \sum_{\text{October 1}}^{\text{March 31}} \left( Wo + P - T_{v} - E_{s} \right)\]

Where \(T_{v}\) and \(E_{s}\) are given by the following formulae:

\[T_{v} = ETP * k\]

and

\[E_{s} = \frac{ETP}{N}\left( 1 - k \right) * JPm\]

Where \(ETP\) is evapotranspiration, \(N\) is the number of days in the given month. \(k\) is the coefficient for radiative absorption given by the vine plant architecture, and \(JPm\) is the number of days of effective evaporation from the soil per month, both provided by the following formulae:

\[\begin{split}k = \begin{cases} 0.1, & \text{if month = April (NH) or October (SH)} \\ 0.3, & \text{if month = May (NH) or November (SH)} \\ 0.5, & \text{if month = June - September (NH) or December - March (SH)} \\ \end{cases}\end{split}\]

\[JPm = \max\left( P / 5, N \right)\]

References

Riou [1994], Tonietto and Carbonneau [2004]

xclim.indicators.atmos.extreme_temperature_range(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Extreme temperature range (realm: atmos)

The maximum of the maximum temperature minus the minimum of the minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice extreme_temperature_range().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

etr (DataArray) – Intra-period extreme temperature range (air_temperature) [K], with additional attributes: description: {freq} range between the maximum of daily maximum temperature and the minimum of dailyminimum temperature.

Notes

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the extreme temperature range in period \(j\) is:

\[ETR_j = max(TX_{ij}) - min(TN_{ij})\]

xclim.indicators.atmos.fire_season(tas='tas', snd=None, *, method='WF93', freq=None, temp_start_thresh='12 degC', temp_end_thresh='5 degC', temp_condition_days=3, snow_condition_days=3, snow_thresh='0.01 m', ds=None)

Fire season mask. (realm: atmos)

Binary mask of the active fire season, defined by conditions on consecutive daily temperatures and, optionally, snow depths.

Based on indice fire_season().

Parameters:

• tas (str or DataArray) – Daily surface temperature, cffdrs recommends using maximum daily temperature. Default : ds.tas. [Required units : [temperature]]

• snd (str or DataArray, optional) – Snow depth, used with method == ‘LA08’. [Required units : [length]]

• method ({‘GFWED’, ‘LA08’, ‘WF93’}) – Which method to use. “LA08” and “GFWED” need the snow depth. Default : WF93.

• freq (offset alias (string)) – If given only the longest fire season for each period defined by this frequency, Every “seasons” are returned if None, including the short shoulder seasons. Default : None.

• temp_start_thresh (quantity (string or DataArray, with units)) – Minimal temperature needed to start the season. Must be scalar. Default : 12 degC. [Required units : [temperature]]

• temp_end_thresh (quantity (string or DataArray, with units)) – Maximal temperature needed to end the season. Must be scalar. Default : 5 degC. [Required units : [temperature]]

• temp_condition_days (number) – Number of days with temperature above or below the thresholds to trigger a start or an end of the fire season. Default : 3.

• snow_condition_days (number) – Parameters for the fire season determination. See fire_season(). Temperature is in degC, snow in m. The snow_thresh parameters is also used when dry_start is set to “GFWED”. Default : 3.

• snow_thresh (quantity (string or DataArray, with units)) – Minimal snow depth level to end a fire season, only used with method “LA08”. Must be scalar. Default : 0.01 m. [Required units : [length]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

fire_season (DataArray) – Fire season mask, with additional attributes: description: Fire season mask, computed with method {method}.

References

Lawson and Armitage [2008], Wotton and Flannigan [1993]

xclim.indicators.atmos.first_day_tg_above(tas='tas', *, thresh='0 degC', op='>', after_date='01-01', window=1, freq='YS', ds=None)

First day of temperatures superior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is superior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: January 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_above().

Parameters:

• tas (str or DataArray) – Daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 01-01.

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tg_above (DataArray) – First day of year with a period of at least {window} days of mean temperature above {thresh} (day_of_year), with additional attributes: description: First day of year with mean temperature above {thresh} for at least {window} days.

Notes

Let \(x_i\) be the daily mean|max|min temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The first day above temperature threshold is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j > thresh]\]

where \(w\) is the number of days the temperature threshold should be exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.first_day_tg_below(tas='tas', *, thresh='0 degC', op='<', after_date='07-01', window=1, freq='YS', ds=None)

First day of temperatures inferior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is inferior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: July 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_below().

Parameters:

• tas (str or DataArray) – Daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “>”. Default : <.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tg_below (DataArray) – First day of year with a period of at least {window} days of mean temperature below {thresh} (day_of_year), with additional attributes: description: First day of year with mean temperature below {thresh} for at least {window} days.

xclim.indicators.atmos.first_day_tn_above(tasmin='tasmin', *, thresh='0 degC', op='>', after_date='01-01', window=1, freq='YS', ds=None)

First day of temperatures superior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is superior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: January 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_above().

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 01-01.

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tn_above (DataArray) – First day of year with a period of at least {window} days of minimum temperature above {thresh} (day_of_year), with additional attributes: description: First day of year with minimum temperature above {thresh} for at least {window} days.

Notes

Let \(x_i\) be the daily mean|max|min temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The first day above temperature threshold is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j > thresh]\]

where \(w\) is the number of days the temperature threshold should be exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.first_day_tn_below(tasmin='tasmin', *, thresh='0 degC', op='<', after_date='07-01', window=1, freq='YS', ds=None)

First day of temperatures inferior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is inferior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: July 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_below().

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “>”. Default : <.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tn_below (DataArray) – First day of year with a period of at least {window} days of minimum temperature below {thresh} (day_of_year), with additional attributes: description: First day of year with minimum temperature below {thresh} for at least {window} days.

xclim.indicators.atmos.first_day_tx_above(tasmax='tasmax', *, thresh='0 degC', op='>', after_date='01-01', window=1, freq='YS', ds=None)

First day of temperatures superior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is superior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: January 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_above().

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 01-01.

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tx_above (DataArray) – First day of year with a period of at least {window} days of maximum temperature above {thresh} (day_of_year), with additional attributes: description: First day of year with maximum temperature above {thresh} for at least {window} days.

Notes

Let \(x_i\) be the daily mean|max|min temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The first day above temperature threshold is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j > thresh]\]

where \(w\) is the number of days the temperature threshold should be exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.first_day_tx_below(tasmax='tasmax', *, thresh='0 degC', op='<', after_date='07-01', window=1, freq='YS', ds=None)

First day of temperatures inferior to a given temperature threshold. (realm: atmos)

Returns first day of period where temperature is inferior to a threshold over a given number of days (default: 1), limited to a starting calendar date (default: July 1).

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_below().

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “>”. Default : <.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_day_tx_below (DataArray) – First day of year with a period of at least {window} days of maximum temperature below {thresh} (day_of_year), with additional attributes: description: First day of year with maximum temperature below {thresh} for at least {window} days.

xclim.indicators.atmos.first_snowfall(prsn='prsn', *, thresh='0.5 mm/day', freq='AS-JUL', ds=None, **indexer)

First day where solid precipitation flux exceeded a given threshold (realm: atmos)

The first day where the solid precipitation flux exceeded a given threshold during a time period.

This indicator will check for missing values according to the method “from_context”. Based on indice first_snowfall().

Parameters:

• prsn (str or DataArray) – Solid precipitation flux. Default : ds.prsn. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold precipitation flux on which to base evaluation. Default : 0.5 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

first_snowfall (DataArray) – Date of first day where the solid precipitation flux exceeded {thresh} (day_of_year), with additional attributes: description: {freq} first day where the solid precipitation flux exceeded {thresh}.

References

CBCL [2020].

xclim.indicators.atmos.fraction_over_precip_doy_thresh(pr='pr', pr_per='pr_per', *, thresh='1 mm/day', freq='YS', bootstrap=False, op='>', ds=None, **indexer)

(realm: atmos)

Percentage of the total precipitation over period occurring in days when the precipitation is above a threshold defining wet days and above a given percentile for that day.

This indicator will check for missing values according to the method “from_context”. Based on indice fraction_over_precip_thresh().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – Percentile of wet day precipitation flux. Either computed daily (one value per day of year) or computed over a period (one value per spatial point). Default : ds.pr_per. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

fraction_over_precip_doy_thresh (DataArray) – Fraction of precipitation due to days with daily precipitation above {pr_per_thresh}th daily percentile, with additional attributes: description: {freq} fraction of total precipitation due to days with precipitation above {pr_per_thresh}th daily percentile. Only days with at least {thresh} are included in the total. A {pr_per_window} day(s) window, centered on each calendar day in the {pr_per_period} period, is used to compute the {pr_per_thresh}th percentile(s).

xclim.indicators.atmos.fraction_over_precip_thresh(pr='pr', pr_per='pr_per', *, thresh='1 mm/day', freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Fraction of precipitation due to wet days with daily precipitation over a given percentile. (realm: atmos)

Percentage of the total precipitation over period occurring in days when the precipitation is above a threshold defining wet days and above a given percentile for that day.

This indicator will check for missing values according to the method “from_context”. Based on indice fraction_over_precip_thresh().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – Percentile of wet day precipitation flux. Either computed daily (one value per day of year) or computed over a period (one value per spatial point). Default : ds.pr_per. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

fraction_over_precip_thresh (DataArray) – Fraction of precipitation due to days with precipitation above {pr_per_thresh}th daily percentile, with additional attributes: description: {freq} fraction of total precipitation due to days with precipitation above {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are included in the total.

xclim.indicators.atmos.freezethaw_spell_frequency(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='0 degC', thresh_tasmax='0 degC', window=1, op_tasmin='<=', op_tasmax='>', freq='YS', resample_before_rl=True, ds=None)

Freeze-thaw spell frequency (realm: atmos)

Frequency of daily freeze-thaw spells. A freeze-thaw spell is defined as a number of consecutive days where maximum daily temperatures are above a given threshold and minimum daily temperatures are at or below a given threshold, usually 0°C for both.

This indicator will check for missing values according to the method “from_context”. Based on indice multiday_temperature_swing(). With injected parameters: op=count.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a freeze event. Default : 0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a thaw event. Default : 0 degC. [Required units : [temperature]]

• window (number) – The minimal length of spells to be included in the statistics. Default : 1.

• op_tasmin ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation for tasmin. Default: “<=”. Default : <=.

• op_tasmax ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation for tasmax. Default: “>”. Default : >.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

freezethaw_spell_frequency (DataArray) – Frequency of events where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s). [days], with additional attributes: description: {freq} number of freeze-thaw spells, where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s).

Notes

Let \(TX_{i}\) be the maximum temperature at day \(i\) and \(TN_{i}\) be the daily minimum temperature at day \(i\). Then freeze thaw spells during a given period are consecutive days where:

\[TX_{i} > 0℃ \land TN_{i} < 0℃\]

This indice returns a given statistic of the found lengths, optionally dropping those shorter than the window argument. For example, window=1 and op=’sum’ returns the same value as daily_freezethaw_cycles().

xclim.indicators.atmos.freezethaw_spell_max_length(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='0 degC', thresh_tasmax='0 degC', window=1, op_tasmin='<=', op_tasmax='>', freq='YS', resample_before_rl=True, ds=None)

Maximal length of freeze-thaw spells (realm: atmos)

Maximal length of daily freeze-thaw spells. A freeze-thaw spell is defined as a number of consecutive days where maximum daily temperatures are above a given threshold and minimum daily temperatures are at or below a threshold, usually 0°C for both.

This indicator will check for missing values according to the method “from_context”. Based on indice multiday_temperature_swing(). With injected parameters: op=max.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a freeze event. Default : 0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a thaw event. Default : 0 degC. [Required units : [temperature]]

• window (number) – The minimal length of spells to be included in the statistics. Default : 1.

• op_tasmin ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation for tasmin. Default: “<=”. Default : <=.

• op_tasmax ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation for tasmax. Default: “>”. Default : >.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

freezethaw_spell_max_length (DataArray) – Maximal length of events where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s). [days], with additional attributes: description: {freq} maximal length of freeze-thaw spells, where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s).

Notes

Let \(TX_{i}\) be the maximum temperature at day \(i\) and \(TN_{i}\) be the daily minimum temperature at day \(i\). Then freeze thaw spells during a given period are consecutive days where:

\[TX_{i} > 0℃ \land TN_{i} < 0℃\]

This indice returns a given statistic of the found lengths, optionally dropping those shorter than the window argument. For example, window=1 and op=’sum’ returns the same value as daily_freezethaw_cycles().

xclim.indicators.atmos.freezethaw_spell_mean_length(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='0 degC', thresh_tasmax='0 degC', window=1, freq='YS', resample_before_rl=True, ds=None)

Freeze-thaw spell mean length (realm: atmos)

Average length of daily freeze-thaw spells. A freeze-thaw spell is defined as a number of consecutive days where maximum daily temperatures are above a given threshold and minimum daily temperatures are at or below a given threshold, usually 0°C for both.

This indicator will check for missing values according to the method “from_context”. Based on indice multiday_temperature_swing(). With injected parameters: op=mean, op_tasmin=<=, op_tasmax=>.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a freeze event. Default : 0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The temperature threshold needed to trigger a thaw event. Default : 0 degC. [Required units : [temperature]]

• window (number) – The minimal length of spells to be included in the statistics. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

freezethaw_spell_mean_length (DataArray) – Average length of events where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s). [days], with additional attributes: description: {freq} average length of freeze-thaw spells, where maximum daily temperatures are above {thresh_tasmax} and minimum daily temperatures are at or below {thresh_tasmin} for at least {window} consecutive day(s).

Notes

Let \(TX_{i}\) be the maximum temperature at day \(i\) and \(TN_{i}\) be the daily minimum temperature at day \(i\). Then freeze thaw spells during a given period are consecutive days where:

\[TX_{i} > 0℃ \land TN_{i} < 0℃\]

This indice returns a given statistic of the found lengths, optionally dropping those shorter than the window argument. For example, window=1 and op=’sum’ returns the same value as daily_freezethaw_cycles().

xclim.indicators.atmos.freezing_degree_days(tas='tas', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Freezing degree days (realm: atmos)

The cumulative degree days for days when the average temperature is below a given threshold, typically 0°C.

This indicator will check for missing values according to the method “from_context”. Based on indice heating_degree_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

freezing_degree_days (DataArray) – Cumulative sum of temperature degrees for mean daily temperature below {thresh} (integral_of_air_temperature_deficit_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} freezing degree days (mean temperature below {thresh}).

Notes

This index intentionally differs from its ECA&D [Project team ECA&D and KNMI, 2013] equivalent: HD17. In HD17, values below zero are not clipped before the sum. The present definition should provide a better representation of the energy demand for heating buildings to the given threshold.

Let \(TG_{ij}\) be the daily mean temperature at day \(i\) of period \(j\). Then the heating degree days are:

\[HD17_j = \sum_{i=1}^{I} (17℃ - TG_{ij}) | TG_{ij} < 17℃)\]

xclim.indicators.atmos.freshet_start(tas='tas', *, thresh='0 degC', op='>', after_date='01-01', window=5, freq='YS', ds=None)

Day of year of spring freshet start (realm: atmos)

Day of year of the spring freshet start, defined as the first day when the temperature exceeds a certain threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice first_day_temperature_above().

Parameters:

• tas (str or DataArray) – Daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• after_date (date (string, MM-DD)) – Date of the year after which to look for the first event. Should have the format ‘%m-%d’. Default : 01-01.

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

freshet_start (DataArray) – First day where temperature threshold of {thresh} is exceeded for at least {window} days (day_of_year), with additional attributes: description: Day of year of the spring freshet start, defined as the first day a temperature threshold of {thresh} is exceeded for at least {window} days.

Notes

Let \(x_i\) be the daily mean|max|min temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The first day above temperature threshold is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j > thresh]\]

where \(w\) is the number of days the temperature threshold should be exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.frost_days(tasmin='tasmin', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Frost days (realm: atmos)

Number of days where the daily minimum temperature is below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice frost_days().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Freezing temperature. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

frost_days (DataArray) – Number of days where the daily minimum temperature is below {thresh} (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where the daily minimum temperature is below {thresh}.

Notes

Let \(TN_{ij}\) be the daily minimum temperature at day \(i\) of period \(j\) and :math`TT` the threshold. Then counted is the number of days where:

\[TN_{ij} < TT\]

xclim.indicators.atmos.frost_free_season_end(tasmin='tasmin', *, thresh='0 degC', mid_date='07-01', window=5, freq='YS', ds=None)

Frost free season end (realm: atmos)

First day when the temperature is below a given threshold for a given number of consecutive days after a median calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice frost_free_season_end().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• mid_date (date (string, MM-DD)) – Date of the year after which to look for the end of the season. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

frost_free_season_end (DataArray) – First day, after {mid_date}, following a period of {window} days with minimum daily temperature below {thresh} (day_of_year), with additional attributes: description: Day of the year of the end of the frost-free season, defined as the interval between the first set of {window} days when the minimum daily temperature is at or above {thresh} and the first set (after {mid_date}) of {window} days when it is below {thresh}.

xclim.indicators.atmos.frost_free_season_length(tasmin='tasmin', *, window=5, mid_date='07-01', thresh='0 degC', freq='YS', op='>=', ds=None)

Frost free season length (realm: atmos)

Duration of the frost free season, defined as the period when the minimum daily temperature is above 0°C without a freezing window of N days, with freezing occurring after a median calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice frost_free_season_length().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold to mark the beginning and end of frost free season. Default : 5.

• mid_date (date (string, MM-DD)) – Date the must be included in the season. It is the earliest the end of the season can be. If None, there is no limit. Default : 07-01.

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

frost_free_season_length (DataArray) – Number of days between the first occurrence of at least {window} consecutive days with minimum daily temperature at or above {thresh} and the first occurrence of at least {window} consecutive days with minimum daily temperature below {thresh} after {mid_date} (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days between the first occurrence of at least {window} consecutive days with minimum daily temperature at or above {thresh} and the first occurrence of at least {window} consecutive days with minimum daily temperature below {thresh} after {mid_date}.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then counted is the number of days between the first occurrence of at least N consecutive days with:

\[TN_{ij} >= 0 ℃\]

and the first subsequent occurrence of at least N consecutive days with:

\[TN_{ij} < 0 ℃\]

xclim.indicators.atmos.frost_free_season_start(tasmin='tasmin', *, thresh='0 degC', window=5, freq='YS', ds=None)

Frost free season start (realm: atmos)

First day when minimum daily temperature exceeds a given threshold for a given number of consecutive days

This indicator will check for missing values according to the method “from_context”. Based on indice frost_free_season_start().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

frost_free_season_start (DataArray) – First day following a period of {window} days with minimum daily temperature at or above {thresh} (day_of_year), with additional attributes: description: Day of the year of the beginning of the frost-free season, defined as the {window}th consecutive day when minimum daily temperature exceeds {thresh}.

Notes

Let \(x_i\) be the daily mean temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The start date of the start of growing season is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j >= thresh]\]

where \(w\) is the number of days the temperature threshold should be met or exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.frost_season_length(tasmin='tasmin', *, window=5, mid_date='01-01', thresh='0 degC', freq='AS-JUL', op='<', ds=None)

Frost season length (realm: atmos)

Duration of the freezing season, defined as the period when the daily minimum temperature is below 0°C without a thawing window of days, with the thaw occurring after a median calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice frost_season_length().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature below threshold to mark the beginning and end of frost season. Default : 5.

• mid_date (date (string, MM-DD)) – Date the must be included in the season. It is the earliest the end of the season can be. If None, there is no limit. Default : 01-01.

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

frost_season_length (DataArray) – Number of days between the first occurrence of at least {window} consecutive days with minimum daily temperature below {thresh} and the first occurrence of at least {window} consecutive days with minimum daily temperature at or above {thresh} after {mid_date} (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days between the first occurrence of at least {window} consecutive days with minimum daily temperature below {thresh} and the first occurrence of at least {window} consecutive days with minimum daily temperature at or above {thresh} after {mid_date}.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then counted is the number of days between the first occurrence of at least N consecutive days with:

\[TN_{ij} > 0 ℃\]

and the first subsequent occurrence of at least N consecutive days with:

\[TN_{ij} < 0 ℃\]

xclim.indicators.atmos.griffiths_drought_factor(pr='pr', smd='smd', *, limiting_func='xlim', ds=None)

Griffiths drought factor based on the soil moisture deficit. (realm: atmos)

The drought factor is a numeric indicator of the forest fire fuel availability in the deep litter bed. It is often used in the calculation of the McArthur Forest Fire Danger Index. The method implemented here follows Finkele et al. [2006].

This indicator will check for missing values according to the method “skip”. Based on indice griffiths_drought_factor().

Parameters:

• pr (str or DataArray) – Total rainfall over previous 24 hours [mm/day]. Default : ds.pr. [Required units : [precipitation]]

• smd (str or DataArray) – Daily soil moisture deficit (often KBDI) [mm/day]. Default : ds.smd. [Required units : [precipitation]]

• limiting_func ({‘xlim’, ‘discrete’}) – How to limit the values of the drought factor. If “xlim” (default), use equation (14) in Finkele et al. [2006]. If “discrete”, use equation Eq (13) in Finkele et al. [2006], but with the lower limit of each category bound adjusted to match the upper limit of the previous bound. Default : xlim.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

df (DataArray) – Griffiths Drought Factor (griffiths_drought_factor), with additional attributes: description: Numeric indicator of the forest fire fuel availability in the deep litter bed

Notes

Calculation of the Griffiths drought factor depends on the rainfall over the previous 20 days. Thus, the first non-NaN time point in the drought factor returned by this function corresponds to the 20th day of the input data.

References

Finkele, Mills, Beard, and Jones [2006], Griffiths [1999], Holgate, Van DIjk, Cary, and Yebra [2017]

xclim.indicators.atmos.growing_degree_days(tas='tas', *, thresh='4.0 degC', freq='YS', ds=None, **indexer)

Growing degree days (realm: atmos)

The cumulative degree days for days when the average temperature is above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_degree_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 4.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

growing_degree_days (DataArray) – Cumulative sum of temperature degrees for mean daily temperature above {thresh} (integral_of_air_temperature_excess_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} growing degree days (mean temperature above {thresh}).

Notes

Let \(TG_{ij}\) be the mean daily temperature at day \(i\) of period \(j\). Then the growing degree days are:

\[GD4_j = \sum_{i=1}^I (TG_{ij}-{4} | TG_{ij} > {4}℃)\]

xclim.indicators.atmos.growing_season_end(tas='tas', *, thresh='5.0 degC', mid_date='07-01', window=5, freq='YS', ds=None)

Growing season end (realm: atmos)

The first day when the temperature is below a certain threshold for a certain number of consecutive days after a given calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_season_end().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 5.0 degC. [Required units : [temperature]]

• mid_date (date (string, MM-DD)) – Date of the year after which to look for the end of the season. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

growing_season_end (DataArray) – First day of the first series of {window} days with mean daily temperature below {thresh}, occurring after {mid_date} (day_of_year), with additional attributes: description: Day of year of end of growing season, defined as the first day of consistent inferior threshold temperature of {thresh} after a run of {window} days superior to threshold temperature, occurring after {mid_date}.

Notes

Let \(x_i\) be the daily mean temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The start date of the end of growing season is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j < thresh]\]

where \(w\) is the number of days where temperature should be inferior to a given threshold after a given date, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.growing_season_length(tas='tas', *, thresh='5.0 degC', window=6, mid_date='07-01', freq='YS', op='>=', ds=None)

Growing season length (realm: atmos)

Number of days between the first occurrence of a series of days with a daily average temperature above a threshold and the first occurrence of a series of days with a daily average temperature below that same threshold, occurring after a given calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_season_length().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 5.0 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold to mark the beginning and end of growing season. Default : 6.

• mid_date (date (string, MM-DD)) – Date of the year after which to look for the end of the season. Should have the format ‘%m-%d’. Default : 07-01.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

growing_season_length (DataArray) – Number of days between the first occurrence of at least {window} consecutive days with mean daily temperature over {thresh} and the first occurrence of at least {window} consecutive days with mean daily temperature below {thresh}, occurring after {mid_date} (growing_season_length) [days], with additional attributes: description: {freq} number of days between the first occurrence of at least {window} consecutive days with mean daily temperature over {thresh} and the first occurrence of at least {window} consecutive days with mean daily temperature below {thresh}, occurring after {mid_date}.

Notes

Let \(TG_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then counted is the number of days between the first occurrence of at least 6 consecutive days with:

\[TG_{ij} > 5 ℃\]

and the first occurrence after 1 July of at least 6 consecutive days with:

\[TG_{ij} < 5 ℃\]

References

Project team ECA&D and KNMI [2013]

xclim.indicators.atmos.growing_season_start(tas='tas', *, thresh='5.0 degC', window=5, freq='YS', ds=None)

Growing season start (realm: atmos)

The first day when the temperature exceeds a certain threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_season_start().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 5.0 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold needed for evaluation. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

growing_season_start (DataArray) – First day of the first series of {window} days with mean daily temperature above or equal to {thresh} (day_of_year), with additional attributes: description: Day of the year marking the beginning of the growing season, defined as the first day of the first series of {window} days with mean daily temperature above or equal to {thresh}.

Notes

Let \(x_i\) be the daily mean temperature at day of the year \(i\) for values of \(i\) going from 1 to 365 or 366. The start date of the start of growing season is given by the smallest index \(i\):

\[\prod_{j=i}^{i+w} [x_j >= thresh]\]

where \(w\) is the number of days the temperature threshold should be met or exceeded, and \([P]\) is 1 if \(P\) is true, and 0 if false.

xclim.indicators.atmos.heat_index(tas='tas', hurs='hurs', *, ds=None)

Heat index (realm: atmos)

The heat index is an estimate of the temperature felt by a person in the shade when relative humidity is taken into account.

Based on indice heat_index().

Parameters:

• tas (str or DataArray) – Temperature. The equation assumes an instantaneous value. Default : ds.tas. [Required units : [temperature]]

• hurs (str or DataArray) – Relative humidity. The equation assumes an instantaneous value. Default : ds.hurs. [Required units : []]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

heat_index (DataArray) – Heat index (air_temperature) [C], with additional attributes: description: Perceived temperature after relative humidity is taken into account.

Notes

While both the humidex and the heat index are calculated using dew point the humidex uses a dew point of 7 °C (45 °F) as a base, whereas the heat index uses a dew point base of 14 °C (57 °F). Further, the heat index uses heat balance equations which account for many variables other than vapour pressure, which is used exclusively in the humidex calculation.

References

Blazejczyk, Epstein, Jendritzky, Staiger, and Tinz [2012]

xclim.indicators.atmos.heat_wave_frequency(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='22.0 degC', thresh_tasmax='30 degC', window=3, freq='YS', op='>', resample_before_rl=True, ds=None)

Heat wave frequency (realm: atmos)

Number of heat waves. A heat wave occurs when daily minimum and maximum temperatures exceed given thresholds for a number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice heat_wave_frequency(). Keywords : health,.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The minimum temperature threshold needed to trigger a heatwave event. Default : 22.0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed to trigger a heatwave event. Default : 30 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperatures above thresholds to qualify as a heatwave. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

heat_wave_frequency (DataArray) – Total number of series of at least {window} consecutive days with daily minimum temperature above {thresh_tasmin} and daily maximum temperature above {thresh_tasmax} (heat_wave_events), with additional attributes: description: {freq} number of heat wave events within a given period. A heat wave occurs when daily minimum and maximum temperatures exceed {thresh_tasmin} and {thresh_tasmax}, respectively, over at least {window} days.

Notes

The thresholds of 22° and 25°C for night temperatures and 30° and 35°C for day temperatures were selected by Health Canada professionals, following a temperature–mortality analysis. These absolute temperature thresholds characterize the occurrence of hot weather events that can result in adverse health outcomes for Canadian communities [Casati et al., 2013].

In Robinson [2001], the parameters would be thresh_tasmin=27.22, thresh_tasmax=39.44, window=2 (81F, 103F).

References

Casati, Yagouti, and Chaumont [2013], Robinson [2001]

xclim.indicators.atmos.heat_wave_index(tasmax='tasmax', *, thresh='25.0 degC', window=5, freq='YS', op='>', resample_before_rl=True, ds=None)

Heat wave index (realm: atmos)

Number of days that constitute heatwave events. A heat wave occurs when daily minimum and maximum temperatures exceed given thresholds for a number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice heat_wave_index().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to designate a heatwave. Default : 25.0 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold to qualify as a heatwave. Default : 5.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

heat_wave_index (DataArray) – Total number of days constituting events of at least {window} consecutive days with daily maximum temperature above {thresh} (heat_wave_index) [days], with additional attributes: description: {freq} total number of days that are part of a heatwave within a given period. A heat wave occurs when daily maximum temperatures exceed {thresh} over at least {window} days.

xclim.indicators.atmos.heat_wave_max_length(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='22.0 degC', thresh_tasmax='30 degC', window=3, freq='YS', op='>', resample_before_rl=True, ds=None)

Heat wave maximum length (realm: atmos)

Total duration of heat waves. A heat wave occurs when daily minimum and maximum temperatures exceed given thresholds for a number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice heat_wave_max_length(). Keywords : health,.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The minimum temperature threshold needed to trigger a heatwave event. Default : 22.0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed to trigger a heatwave event. Default : 30 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperatures above thresholds to qualify as a heatwave. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

heat_wave_max_length (DataArray) – Longest series of at least {window} consecutive days with daily minimum temperature above {thresh_tasmin} and daily maximum temperature above {thresh_tasmax} (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: description: {freq} maximum length of heat wave events occurring within a given period. A heat wave occurs when daily minimum and maximum temperatures exceed {thresh_tasmin} and {thresh_tasmax}, respectively, over at least {window} days.

Notes

The thresholds of 22° and 25°C for night temperatures and 30° and 35°C for day temperatures were selected by Health Canada professionals, following a temperature–mortality analysis. These absolute temperature thresholds characterize the occurrence of hot weather events that can result in adverse health outcomes for Canadian communities [Casati et al., 2013].

In Robinson [2001], the parameters would be: thresh_tasmin=27.22, thresh_tasmax=39.44, window=2 (81F, 103F).

References

Casati, Yagouti, and Chaumont [2013], Robinson [2001]

xclim.indicators.atmos.heat_wave_total_length(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='22.0 degC', thresh_tasmax='30 degC', window=3, freq='YS', op='>', resample_before_rl=True, ds=None)

Heat wave total length (realm: atmos)

Maximum length of heat waves. A heat wave occurs when daily minimum and maximum temperatures exceed given thresholds for a number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice heat_wave_total_length(). Keywords : health,.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – The minimum temperature threshold needed to trigger a heatwave event. Default : 22.0 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed to trigger a heatwave event. Default : 30 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperatures above thresholds to qualify as a heatwave. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

heat_wave_total_length (DataArray) – Total length of events of at least {window} consecutive days with daily minimum temperature above {thresh_tasmin} and daily maximum temperature above {thresh_tasmax} (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: description: {freq} total length of heat wave events occurring within a given period. A heat wave occurs when daily minimum and maximum temperatures exceed {thresh_tasmin} and {thresh_tasmax}, respectively, over at least {window} days.

Notes

See notes and references of heat_wave_max_length

xclim.indicators.atmos.heating_degree_days(tas='tas', *, thresh='17.0 degC', freq='YS', ds=None, **indexer)

Heating degree days (realm: atmos)

The cumulative degree days for days when the mean daily temperature is below a given threshold and buildings must be heated.

This indicator will check for missing values according to the method “from_context”. Based on indice heating_degree_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 17.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

heating_degree_days (DataArray) – Cumulative sum of temperature degrees for mean daily temperature below {thresh} (integral_of_air_temperature_deficit_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} cumulative heating degree days (mean temperature below {thresh}).

Notes

This index intentionally differs from its ECA&D [Project team ECA&D and KNMI, 2013] equivalent: HD17. In HD17, values below zero are not clipped before the sum. The present definition should provide a better representation of the energy demand for heating buildings to the given threshold.

Let \(TG_{ij}\) be the daily mean temperature at day \(i\) of period \(j\). Then the heating degree days are:

\[HD17_j = \sum_{i=1}^{I} (17℃ - TG_{ij}) | TG_{ij} < 17℃)\]

xclim.indicators.atmos.high_precip_low_temp(pr='pr', tas='tas', *, pr_thresh='0.4 mm/d', tas_thresh='-0.2 degC', freq='YS', ds=None, **indexer)

Days with precipitation and cold temperature (realm: atmos)

Number of days with precipitation above a given threshold and temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice high_precip_low_temp().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Daily mean, minimum or maximum temperature. Default : ds.tas. [Required units : [temperature]]

• pr_thresh (quantity (string or DataArray, with units)) – Precipitation threshold to exceed. Default : 0.4 mm/d. [Required units : [precipitation]]

• tas_thresh (quantity (string or DataArray, with units)) – Temperature threshold not to exceed. Default : -0.2 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

high_precip_low_temp (DataArray) – Days with precipitation at or above {pr_thresh} and temperature below {tas_thresh} [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation at or above {pr_thresh} and temperature below {tas_thresh}.

xclim.indicators.atmos.hot_spell_frequency(tasmax='tasmax', *, thresh_tasmax='30 degC', window=3, freq='YS', op='>', resample_before_rl=True, ds=None)

Hot spell frequency (realm: atmos)

Number of hot spells events within a given period. A hot spell occurs when the daily maximum temperatureexceeds a given threshold for a minimum number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice hot_spell_frequency(). Keywords : health,.

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed to trigger a heatwave event. Default : 30 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperatures above thresholds to qualify as a heatwave. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hot_spell_frequency (DataArray) – Total number of series of at least {window} consecutive days with daily maximum temperature above {thresh_tasmax} (hot_spell_events), with additional attributes: description: {freq} number of hot spell events within a given period. A hot spell event occurs when the maximum daily temperature exceeds {thresh_tasmax} over at least {window} days.

Notes

The thresholds of 22° and 25°C for night temperatures and 30° and 35°C for day temperatures were selected by Health Canada professionals, following a temperature–mortality analysis. These absolute temperature thresholds characterize the occurrence of hot weather events that can result in adverse health outcomes for Canadian communities [Casati et al., 2013].

In Robinson [2001], the parameters would be thresh_tasmin=27.22, thresh_tasmax=39.44, window=2 (81F, 103F).

References

Casati, Yagouti, and Chaumont [2013], Robinson [2001]

xclim.indicators.atmos.hot_spell_max_length(tasmax='tasmax', *, thresh_tasmax='30 degC', window=1, freq='YS', op='>', resample_before_rl=True, ds=None)

Hot spell maximum length (realm: atmos)

Maximum length of hot spells events within a given period. A hot spell occurs when the daily maximum temperature exceeds a given threshold for a minimum number of days.

This indicator will check for missing values according to the method “from_context”. Based on indice hot_spell_max_length(). Keywords : health,.

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – The maximum temperature threshold needed to trigger a heatwave event. Default : 30 degC. [Required units : [temperature]]

• window (number) – Minimum number of days with temperatures above thresholds to qualify as a heatwave. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hot_spell_max_length (DataArray) – Longest series of at least {window} consecutive days with daily maximum temperature above {thresh_tasmax} (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: description: {freq} maximum length of hot spell events occurring within a given period. A hot spell event occurs when the maximum daily temperature exceeds {thresh_tasmax} over at least {window} days.

Notes

The thresholds of 22° and 25°C for night temperatures and 30° and 35°C for day temperatures were selected by Health Canada professionals, following a temperature–mortality analysis. These absolute temperature thresholds characterize the occurrence of hot weather events that can result in adverse health outcomes for Canadian communities [Casati et al., 2013].

In Robinson [2001], the parameters would be thresh_tasmin=27.22, thresh_tasmax=39.44, window=2 (81F, 103F).

References

Casati, Yagouti, and Chaumont [2013], Robinson [2001]

xclim.indicators.atmos.huglin_index(tas='tas', tasmax='tasmax', lat='lat', *, thresh='10 degC', method='jones', start_date='04-01', end_date='10-01', freq='YS', ds=None)

Huglin heliothermal index (realm: atmos)

Heat-summation index for agroclimatic suitability estimation, developed specifically for viticulture. Considers daily minimum and maximum temperature with a given base threshold, typically between 1 April and 30September, and integrates a day-length coefficient calculation for higher latitudes. Metric originally published in Huglin (1978). Day-length coefficient based on Hall & Jones (2010).

This indicator will check for missing values according to the method “from_context”. Based on indice huglin_index().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• lat (str or DataArray) – Latitude coordinate. If None, a CF-conformant “latitude” field must be available within the passed DataArray. Default : ds.lat. [Required units : []]

• thresh (quantity (string or DataArray, with units)) – The temperature threshold. Default : 10 degC. [Required units : [temperature]]

• method ({‘icclim’, ‘smoothed’, ‘jones’}) – The formula to use for the latitude coefficient calculation. Default : jones.

• start_date (date (string, MM-DD)) – The hemisphere-based start date to consider (north = April, south = October). Default : 04-01.

• end_date (date (string, MM-DD)) – The hemisphere-based start date to consider (north = October, south = April). This date is non-inclusive. Default : 10-01.

• freq (offset alias (string)) – Resampling frequency (default: “YS”; For Southern Hemisphere, should be “AS-JUL”). Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hi (DataArray) – Integral of mean daily temperature above {thresh} multiplied by day-length coefficient with {method} method for days between {start_date} and {end_date}, with additional attributes: description: Heat-summation index for agroclimatic suitability estimation, developed specifically for viticulture, computed with {method} formula (Summation of ((Tn + Tx)/2 - {thresh}) * k), where coefficient k is a latitude-based day-length for days between {start_date} and {end_date}.

Notes

Let \(TX_{i}\) and \(TG_{i}\) be the daily maximum and mean temperature at day \(i\) and \(T_{thresh}\) the base threshold needed for heat summation (typically, 10 degC). A day-length multiplication, \(k\), based on latitude, \(lat\), is also considered. Then the Huglin heliothermal index for dates between 1 April and 30 September is:

\[HI = \sum_{i=\text{April 1}}^{\text{September 30}} \left( \frac{TX_i + TG_i)}{2} - T_{thresh} \right) * k\]

For the smoothed method, the day-length multiplication factor, \(k\), is calculated as follows:

\[\begin{split}k = f(lat) = \begin{cases} 1, & \text{if } |lat| <= 40 \\ 1 + ((abs(lat) - 40) / 10) * 0.06, & \text{if } 40 < |lat| <= 50 \\ NaN, & \text{if } |lat| > 50 \\ \end{cases}\end{split}\]

For compatibility with ICCLIM, end_date should be set to 11-01, method should be set to icclim. The day-length multiplication factor, \(k\), is calculated as follows:

\[\begin{split}k = f(lat) = \begin{cases} 1.0, & \text{if } |lat| <= 40 \\ 1.02, & \text{if } 40 < |lat| <= 42 \\ 1.03, & \text{if } 42 < |lat| <= 44 \\ 1.04, & \text{if } 44 < |lat| <= 46 \\ 1.05, & \text{if } 46 < |lat| <= 48 \\ 1.06, & \text{if } 48 < |lat| <= 50 \\ NaN, & \text{if } |lat| > 50 \\ \end{cases}\end{split}\]

A more robust day-length calculation based on latitude, calendar, day-of-year, and obliquity is available with method=”jones”. See: xclim.indices.generic.day_lengths() or Hall and Jones [2010] for more information.

References

Hall and Jones [2010], Huglin [1978]

xclim.indicators.atmos.humidex(tas='tas', tdps=None, hurs=None, *, ds=None)

Humidex (realm: atmos)

The humidex describes the temperature felt by a person when relative humidity is taken into account. It can be interpreted as the equivalent temperature felt when the air is dry.

Based on indice humidex().

Parameters:

• tas (str or DataArray) – Air temperature. Default : ds.tas. [Required units : [temperature]]

• tdps (str or DataArray, optional) – Dewpoint temperature. [Required units : [temperature]]

• hurs (str or DataArray, optional) – Relative humidity. [Required units : []]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

humidex (DataArray) – Humidex index (air_temperature) [C], with additional attributes: description: Humidex index describing the temperature felt by the average person in response to relative humidity.

Notes

The humidex is usually computed using hourly observations of dry bulb and dewpoint temperatures. It is computed using the formula based on Masterton and Richardson [1979]:

\[T + {\frac {5}{9}}\left[e - 10\right]\]

where \(T\) is the dry bulb air temperature (°C). The term \(e\) can be computed from the dewpoint temperature \(T_{dewpoint}\) in °K:

\[e = 6.112 \times \exp(5417.7530\left({\frac {1}{273.16}}-{\frac {1}{T_{\text{dewpoint}}}}\right)\]

where the constant 5417.753 reflects the molecular weight of water, latent heat of vaporization, and the universal gas constant [Mekis et al., 2015]. Alternatively, the term \(e\) can also be computed from the relative humidity h expressed in percent using Sirangelo et al. [2020]:

\[e = \frac{h}{100} \times 6.112 * 10^{7.5 T/(T + 237.7)}.\]

The humidex comfort scale [Canada, 2011] can be interpreted as follows:

• 20 to 29 : no discomfort;

• 30 to 39 : some discomfort;

• 40 to 45 : great discomfort, avoid exertion;

• 46 and over : dangerous, possible heat stroke;

Please note that while both the humidex and the heat index are calculated using dew point, the humidex uses a dew point of 7 °C (45 °F) as a base, whereas the heat index uses a dew point base of 14 °C (57 °F). Further, the heat index uses heat balance equations which account for many variables other than vapour pressure, which is used exclusively in the humidex calculation.

References

Canada [2011], Masterton and Richardson [1979], Mekis, Vincent, Shephard, and Zhang [2015], Sirangelo, Caloiero, Coscarelli, Ferrari, and Fusto [2020]

xclim.indicators.atmos.ice_days(tasmax='tasmax', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Ice days (realm: atmos)

Number of days where the daily maximum temperature is below 0°C

This indicator will check for missing values according to the method “from_context”. Based on indice ice_days().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Freezing temperature. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

ice_days (DataArray) – Number of days with maximum daily temperature below {thresh} (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where the maximum daily temperature is below {thresh}.

Notes

Let \(TX_{ij}\) be the daily maximum temperature at day \(i\) of period \(j\), and :math`TT` the threshold. Then counted is the number of days where:

\[TX_{ij} < TT\]

xclim.indicators.atmos.jetstream_metric_woollings(ua='ua', *, ds=None)

Strength and latitude of jetstream (realm: atmos)

Identify latitude and strength of maximum smoothed zonal wind speed in the region from 15 to 75°N and -60 to 0°E, using the formula outlined in [Woollings et al., 2010]. Wind is smoothened using a Lanczos filter approach.

Based on indice jetstream_metric_woollings().

Parameters:

• ua (str or DataArray) – Eastward wind component (u) at between 750 and 950 hPa. Default : ds.ua. [Required units : [speed]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

• jetlat (DataArray) – Latitude of maximum smoothed zonal wind speed [degrees_North], with additional attributes: description: Daily latitude of maximum Lanczos smoothed zonal wind speed.

• jetstr (DataArray) – Maximum strength of smoothed zonal wind speed [m s-1], with additional attributes: description: Daily maximum strength of Lanczos smoothed zonal wind speed.

References

Woollings, Hannachi, and Hoskins [2010]

xclim.indicators.atmos.keetch_byram_drought_index(pr='pr', tasmax='tasmax', pr_annual='pr_annual', kbdi0=None, *, ds=None)

Keetch-Byram drought index (KBDI) for soil moisture deficit. (realm: atmos)

The KBDI indicates the amount of water necessary to bring the soil moisture content back to field capacity. It is often used in the calculation of the McArthur Forest Fire Danger Index. The method implemented here follows Finkele et al. [2006] but limits the maximum KBDI to 203.2 mm, rather than 200 mm, in order to align best with the majority of the literature.

This indicator will check for missing values according to the method “skip”. Based on indice keetch_byram_drought_index().

Parameters:

• pr (str or DataArray) – Total rainfall over previous 24 hours [mm/day]. Default : ds.pr. [Required units : [precipitation]]

• tasmax (str or DataArray) – Maximum temperature near the surface over previous 24 hours [degC]. Default : ds.tasmax. [Required units : [temperature]]

• pr_annual (str or DataArray) – Mean (over years) annual accumulated rainfall [mm/year]. Default : ds.pr_annual. [Required units : [precipitation]]

• kbdi0 (str or DataArray, optional) – Previous KBDI values used to initialise the KBDI calculation [mm/day]. Defaults to 0. [Required units : [precipitation]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

kbdi (DataArray) – Keetch-Byran Drought Index (keetch_byram_drought_index) [mm/day], with additional attributes: description: Amount of water necessary to bring the soil moisture content back to field capacity

Notes

This method implements the method described in Finkele et al. [2006] (section 2.1.1) for calculating the KBDI with one small difference: in Finkele et al. [2006] the maximum KBDI is limited to 200 mm to represent the maximum field capacity of the soil (8 inches according to Keetch and Byram [1968]). However, it is more common in the literature to limit the KBDI to 203.2 mm which is a more accurate conversion from inches to mm. In this function, the KBDI is limited to 203.2 mm.

References

Dolling, Chu, and Fujioka [2005], Finkele, Mills, Beard, and Jones [2006], Holgate, Van DIjk, Cary, and Yebra [2017], Keetch and Byram [1968]

xclim.indicators.atmos.last_snowfall(prsn='prsn', *, thresh='0.5 mm/day', freq='AS-JUL', ds=None, **indexer)

Last day where solid precipitation flux exceeded a given threshold (realm: atmos)

The last day where the solid precipitation flux exceeded a given threshold during a time period.

This indicator will check for missing values according to the method “from_context”. Based on indice last_snowfall().

Parameters:

• prsn (str or DataArray) – Solid precipitation flux. Default : ds.prsn. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold precipitation flux on which to base evaluation. Default : 0.5 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

last_snowfall (DataArray) – Date of last day where the solid precipitation flux exceeded {thresh} (day_of_year), with additional attributes: description: {freq} last day where the solid precipitation flux exceeded {thresh}.

References

CBCL [2020].

xclim.indicators.atmos.last_spring_frost(tasmin='tasmin', *, thresh='0 degC', op='<', before_date='07-01', window=1, freq='YS', ds=None)

Last spring frost (realm: atmos)

The last day when minimum temperature is below a given threshold for a certain number of days, limited by a final calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice last_spring_frost().

Parameters:

• tasmin (str or DataArray) – Mean daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• before_date (date (string, MM-DD)) – Date of the year before which to look for the final frost event. Should have the format ‘%m-%d’. Default : 07-01.

• window (number) – Minimum number of days with temperature below threshold needed for evaluation. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

last_spring_frost (DataArray) – Last day of minimum daily temperature below a threshold of {thresh} for at least {window} days before a given date ({before_date}) (day_of_year), with additional attributes: description: Day of year of last spring frost, defined as the last day a minimum temperature remains below a threshold of {thresh} for at least {window} days before a given date ({before_date}).

xclim.indicators.atmos.latitude_temperature_index(tas='tas', lat='lat', *, freq='YS', ds=None)

Latitude temperature index (realm: atmos)

A climate indice based on mean temperature of the warmest month and a latitude-based coefficient to account for longer day-length favouring growing conditions. Developed specifically for viticulture. Mean temperature of warmest month multiplied by the difference of latitude factor coefficient minus latitude. Metric originally published in Jackson, D. I., & Cherry, N. J. (1988).

This indicator will check for missing values according to the method “from_context”. Based on indice latitude_temperature_index(). With injected parameters: lat_factor=60.

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• lat (str or DataArray) – Latitude coordinate. If None, a CF-conformant “latitude” field must be available within the passed DataArray. Default : ds.lat. [Required units : []]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

lti (DataArray) – Mean temperature of warmest month multiplied by the difference of {lat_factor} minus latitude, with additional attributes: description: A climate indice based on mean temperature of the warmest month and a latitude-based coefficient to account for longer day-length favouring growing conditions. Developed specifically for viticulture. Mean temperature of warmest month multiplied by the difference of {lat_factor} minus latitude.

Notes

The latitude factor of 75 is provided for examining the poleward expansion of wine-growing climates under scenarios of climate change (modified from Kenny and Shao [1992]). For comparing 20th century/observed historical records, the original scale factor of 60 is more appropriate.

Let \(Tn_{j}\) be the average temperature for a given month \(j\), \(lat_{f}\) be the latitude factor, and \(lat\) be the latitude of the area of interest. Then the Latitude-Temperature Index (\(LTI\)) is:

\[LTI = max(TN_{j}: j = 1..12)(lat_f - |lat|)\]

References

Jackson and Cherry [1988], Kenny and Shao [1992]

xclim.indicators.atmos.liquid_precip_accumulation(pr='pr', tas='tas', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Total accumulated liquid precipitation. (realm: atmos)

Total accumulated liquid precipitation. Precipitation is considered liquid when the average daily temperature is above 0°C.

This indicator will check for missing values according to the method “from_context”. Based on indice precip_accumulation(). With injected parameters: phase=liquid.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean, maximum or minimum daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold of tas over which the precipication is assumed to be liquid rain. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

liquidprcptot (DataArray) – Total accumulated precipitation when temperature is above {thresh} (lwe_thickness_of_liquid_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total {phase} precipitation, estimated as precipitation when temperature is above {thresh}.

Notes

Let \(PR_i\) be the mean daily precipitation of day \(i\), then for a period \(j\) starting at day \(a\) and finishing on day \(b\):

\[PR_{ij} = \sum_{i=a}^{b} PR_i\]

If tas and phase are given, the corresponding phase precipitation is estimated before computing the accumulation, using one of snowfall_approximation or rain_approximation with the binary method.

xclim.indicators.atmos.liquid_precip_ratio(pr='pr', tas='tas', *, thresh='0 degC', freq='QS-DEC', ds=None, **indexer)

Fraction of liquid to total precipitation (realm: atmos)

The ratio of total liquid precipitation over the total precipitation. Liquid precipitation is approximated from total precipitation on days where temperature is above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice liquid_precip_ratio(). With injected parameters: prsn=None.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature under which precipitation is assumed to be solid. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : QS-DEC.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

liquid_precip_ratio (DataArray) – Fraction of liquid to total precipitation (temperature above {thresh}), with additional attributes: description: The {freq} ratio of rainfall to total precipitation. Rainfall is estimated as precipitation on days where temperature is above {thresh}.

Notes

Let \(PR_i\) be the mean daily precipitation of day \(i\), then for a period \(j\) starting at day \(a\) and finishing on day \(b\):

\[ \begin{align}\begin{aligned}PR_{ij} = \sum_{i=a}^{b} PR_i\\PRwet_{ij}\end{aligned}\end{align} \]

xclim.indicators.atmos.longwave_upwelling_radiation_from_net_downwelling(rls='rls', rlds='rlds', *, ds=None)

Upwelling longwave radiation (realm: atmos)

Based on indice longwave_upwelling_radiation_from_net_downwelling().

Parameters:

• rls (str or DataArray) – Surface net thermal radiation. Default : ds.rls. [Required units : [radiation]]

• rlds (str or DataArray) – Surface downwelling thermal radiation. Default : ds.rlds. [Required units : [radiation]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rlus (DataArray) – Upwelling longwave flux (surface_upwelling_longwave_flux) [W m-2], with additional attributes: description: The calculation of upwelling longwave radiative flux from net surface longwave and downwelling surface longwave fluxes.

xclim.indicators.atmos.max_1day_precipitation_amount(pr='pr', *, freq='YS', ds=None, **indexer)

Maximum 1-day total precipitation (realm: atmos)

Maximum total daily precipitation for a given period.

This indicator will check for missing values according to the method “from_context”. Based on indice max_1day_precipitation_amount().

Parameters:

• pr (str or DataArray) – Daily precipitation values. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

rx1day (DataArray) – Maximum 1-day total precipitation (lwe_thickness_of_precipitation_amount) [mm/day], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum 1-day total precipitation

Notes

Let \(PR_i\) be the mean daily precipitation of day i, then for a period j:

\[PRx_{ij} = max(PR_{ij})\]

xclim.indicators.atmos.max_daily_temperature_range(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Maximum of daily temperature range (realm: atmos)

The maximum difference between the daily maximum and minimum temperatures.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range(). With injected parameters: op=max.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

dtrmax (DataArray) – Maximum diurnal temperature range (air_temperature) [K], with additional attributes: cell_methods: time range within days time: max over days; description: {freq} maximum diurnal temperature range.

Notes

For a default calculation using op=’mean’ :

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the mean diurnal temperature range in period \(j\) is:

\[DTR_j = \frac{ \sum_{i=1}^I (TX_{ij} - TN_{ij}) }{I}\]

xclim.indicators.atmos.max_n_day_precipitation_amount(pr='pr', *, window=1, freq='YS', ds=None)

maximum n-day total precipitation (realm: atmos)

Maximum of the moving sum of daily precipitation for a given period.

This indicator will check for missing values according to the method “from_context”. Based on indice max_n_day_precipitation_amount().

Parameters:

• pr (str or DataArray) – Daily precipitation values. Default : ds.pr. [Required units : [precipitation]]

• window (number) – Window size in days. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rx{window}day (DataArray) – maximum {window}-day total precipitation amount (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum {window}-day total precipitation amount.

xclim.indicators.atmos.max_pr_intensity(pr='pr', *, window=1, freq='YS', ds=None)

Maximum precipitation intensity over time window (realm: atmos)

Maximum precipitation intensity over a given rolling time window.

This indicator will check for missing values according to the method “from_context”. Based on indice max_pr_intensity(). Keywords : IDF curves.

Parameters:

• pr (str or DataArray) – Hourly precipitation values. Default : ds.pr. [Required units : [precipitation]]

• window (number) – Window size in hours. Default : 1.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

max_pr_intensity (DataArray) – Maximum precipitation intensity over rolling {window}h time window (precipitation) [mm h-1], with additional attributes: cell_methods: time: max; description: {freq} maximum precipitation intensity over rolling {window}h time window.

xclim.indicators.atmos.maximum_consecutive_dry_days(pr='pr', *, thresh='1 mm/day', freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive dry days (realm: atmos)

The longest number of consecutive days where daily precipitation below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_dry_days().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold precipitation on which to base evaluation. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cdd (DataArray) – Maximum consecutive days with daily precipitation below {thresh} (number_of_days_with_lwe_thickness_of_precipitation_amount_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} maximum number of consecutive days with daily precipitation below {thresh}.

Notes

Let \(\mathbf{p}=p_0, p_1, \ldots, p_n\) be a daily precipitation series and \(thresh\) the threshold under which a day is considered dry. Then let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([p_i < thresh] \neq [p_{i+1} < thresh]\), that is, the days where the precipitation crosses the threshold. Then the maximum number of consecutive dry days is given by

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [p_{s_j} < thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

xclim.indicators.atmos.maximum_consecutive_frost_free_days(tasmin='tasmin', *, thresh='0 degC', freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive frost free days (realm: atmos)

Maximum number of consecutive frost-free days: where the daily minimum temperature is above or equal to 0°C

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_frost_free_days().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

consecutive_frost_free_days (DataArray) – Maximum number of consecutive days with minimum temperature at or above {thresh} (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum number of consecutive days with minimum daily temperature at or above {thresh}.

Notes

Let \(\mathbf{t}=t_0, t_1, \ldots, t_n\) be a daily minimum temperature series and \(thresh\) the threshold above or equal to which a day is considered a frost free day. Let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([t_i <= thresh] \neq [t_{i+1} <= thresh]\), that is, the days where the temperature crosses the threshold. Then the maximum number of consecutive frost free days is given by:

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [t_{s_j} >= thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

xclim.indicators.atmos.maximum_consecutive_warm_days(tasmax='tasmax', *, thresh='25 degC', freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive warm days (realm: atmos)

Maximum number of consecutive days where the maximum daily temperature exceeds a certain threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_tx_days().

Parameters:

• tasmax (str or DataArray) – Max daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature. Default : 25 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

maximum_consecutive_warm_days (DataArray) – Maximum number of consecutive days with maximum daily temperature above {thresh} (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: maximum over days; description: {freq} longest spell of consecutive days with maximum daily temperature above {thresh}.

Notes

Let \(\mathbf{t}=t_0, t_1, \ldots, t_n\) be a daily maximum temperature series and \(thresh\) the threshold above which a day is considered a summer day. Let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([t_i < thresh] \neq [t_{i+1} < thresh]\), that is, the days where the temperature crosses the threshold. Then the maximum number of consecutive tx_days (summer days) is given by:

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [t_{s_j} > thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

xclim.indicators.atmos.maximum_consecutive_wet_days(pr='pr', *, thresh='1 mm/day', freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive wet days (realm: atmos)

The longest number of consecutive days where daily precipitation is at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_wet_days().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold precipitation on which to base evaluation. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cwd (DataArray) – Maximum consecutive days with daily precipitation at or above {thresh} (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} maximum number of consecutive days with daily precipitation at or above {thresh}.

Notes

Let \(\mathbf{x}=x_0, x_1, \ldots, x_n\) be a daily precipitation series and \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([p_i > thresh] \neq [p_{i+1} > thresh]\), that is, the days where the precipitation crosses the wet day threshold. Then the maximum number of consecutive wet days is given by:

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [x_{s_j} > 0^\circ C]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

xclim.indicators.atmos.mcarthur_forest_fire_danger_index(drought_factor='drought_factor', tasmax='tasmax', hurs='hurs', sfcWind='sfcWind', *, ds=None)

McArthur forest fire danger index (FFDI) Mark 5. (realm: atmos)

The FFDI is a numeric indicator of the potential danger of a forest fire.

This indicator will check for missing values according to the method “skip”. Based on indice mcarthur_forest_fire_danger_index().

Parameters:

• drought_factor (str or DataArray) – The drought factor, often the daily Griffiths drought factor (see griffiths_drought_factor()). Default : ds.drought_factor. [Required units : []]

• tasmax (str or DataArray) – The daily maximum temperature near the surface, or similar. Different applications have used different inputs here, including the previous/current day’s maximum daily temperature at a height of 2m, and the daily mean temperature at a height of 2m. Default : ds.tasmax. [Required units : [temperature]]

• hurs (str or DataArray) – The relative humidity near the surface and near the time of the maximum daily temperature, or similar. Different applications have used different inputs here, including the mid-afternoon relative humidity at a height of 2m, and the daily mean relative humidity at a height of 2m. Default : ds.hurs. [Required units : []]

• sfcWind (str or DataArray) – The wind speed near the surface and near the time of the maximum daily temperature, or similar. Different applications have used different inputs here, including the mid-afternoon wind speed at a height of 10m, and the daily mean wind speed at a height of 10m. Default : ds.sfcWind. [Required units : [speed]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ffdi (DataArray) – McArthur Forest Fire Danger Index (mcarthur_forest_fire_danger_index), with additional attributes: description: Numeric rating of the potential danger of a forest fire

References

Dowdy [2018], Holgate, Van DIjk, Cary, and Yebra [2017], Noble, Gill, and Bary [1980]

xclim.indicators.atmos.mean_radiant_temperature(rsds='rsds', rsus='rsus', rlds='rlds', rlus='rlus', *, stat='average', ds=None)

Mean radiant temperature (realm: atmos)

The average temperature of solar and thermal radiation incident on the body’s exterior.

Based on indice mean_radiant_temperature().

Parameters:

• rsds (str or DataArray) – Surface Downwelling Shortwave Radiation Default : ds.rsds. [Required units : [radiation]]

• rsus (str or DataArray) – Surface Upwelling Shortwave Radiation Default : ds.rsus. [Required units : [radiation]]

• rlds (str or DataArray) – Surface Downwelling Longwave Radiation Default : ds.rlds. [Required units : [radiation]]

• rlus (str or DataArray) – Surface Upwelling Longwave Radiation Default : ds.rlus. [Required units : [radiation]]

• stat ({‘average’, ‘sunlit’, ‘instant’}) – Which statistic to apply. If “average”, the average of the cosine of the solar zenith angle is calculated. If “instant”, the instantaneous cosine of the solar zenith angle is calculated. If “sunlit”, the cosine of the solar zenith angle is calculated during the sunlit period of each interval. If “instant”, the instantaneous cosine of the solar zenith angle is calculated. This is necessary if mrt is not None. Default : average.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mrt (DataArray) – Mean radiant temperature [K], with additional attributes: description: The incidence of radiation on the body from all directions.

Notes

This code was inspired by the thermofeel package [Brimicombe et al., 2021].

References

Di Napoli, Hogan, and Pappenberger [2020]

xclim.indicators.atmos.potential_evapotranspiration(tasmin=None, tasmax=None, tas=None, lat=None, hurs=None, rsds=None, rsus=None, rlds=None, rlus=None, sfcWind=None, *, method='BR65', peta=0.00516409319477, petb=0.0874972822289, ds=None)

Potential evapotranspiration (realm: atmos)

The potential for water evaporation from soil and transpiration by plants if the water supply is sufficient, calculated with a given method.

Based on indice potential_evapotranspiration().

Parameters:

• tasmin (str or DataArray, optional) – Minimum daily temperature. [Required units : [temperature]]

• tasmax (str or DataArray, optional) – Maximum daily temperature. [Required units : [temperature]]

• tas (str or DataArray, optional) – Mean daily temperature. [Required units : [temperature]]

• lat (str or DataArray, optional) – Latitude. If not given, it is sought on tasmin or tas using cf-xarray accessors. [Required units : []]

• hurs (str or DataArray, optional) – Relative humidity. [Required units : []]

• rsds (str or DataArray, optional) – Surface Downwelling Shortwave Radiation [Required units : [radiation]]

• rsus (str or DataArray, optional) – Surface Upwelling Shortwave Radiation [Required units : [radiation]]

• rlds (str or DataArray, optional) – Surface Downwelling Longwave Radiation [Required units : [radiation]]

• rlus (str or DataArray, optional) – Surface Upwelling Longwave Radiation [Required units : [radiation]]

• sfcWind (str or DataArray, optional) – Surface wind velocity (at 10 m) [Required units : [speed]]

• method ({‘mcguinnessbordne05’, ‘allen98’, ‘TW48’, ‘FAO_PM98’, ‘baierrobertson65’, ‘HG85’, ‘thornthwaite48’, ‘hargreaves85’, ‘BR65’, ‘MB05’}) – Which method to use, see notes. Default : BR65.

• peta (number) – Used only with method MB05 as \(a\) for calculation of PET, see Notes section. Default value resulted from calibration of PET over the UK. Default : 0.00516409319477.

• petb (number) – Used only with method MB05 as \(b\) for calculation of PET, see Notes section. Default value resulted from calibration of PET over the UK. Default : 0.0874972822289.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

evspsblpot (DataArray) – Potential evapotranspiration (“{method}” method) (water_potential_evapotranspiration_flux) [kg m-2 s-1], with additional attributes: description: The potential for water evaporation from soil and transpiration by plants if the water supply is sufficient, calculated with the {method} method.

Notes

Available methods are:

• “baierrobertson65” or “BR65”, based on Baier and Robertson [1965]. Requires tasmin and tasmax, daily [D] freq.

• “hargreaves85” or “HG85”, based on George H. Hargreaves and Zohrab A. Samani [1985]. Requires tasmin and tasmax, daily [D] freq. (optional: tas can be given in addition of tasmin and tasmax).

• “mcguinnessbordne05” or “MB05”, based on Tanguy et al. [2018]. Requires tas, daily [D] freq, with latitudes ‘lat’.

• “thornthwaite48” or “TW48”, based on Thornthwaite [1948]. Requires tasmin and tasmax, monthly [MS] or daily [D] freq. (optional: tas can be given instead of tasmin and tasmax).

• “allen98” or “FAO_PM98”, based on Allen et al. [1998]. Modification of Penman-Monteith method. Requires tasmin and tasmax, relative humidity, radiation flux and wind speed (10 m wind will be converted to 2 m).

The McGuinness-Bordne [McGuinness and Borone, 1972] equation is:

\[PET[mm day^{-1}] = a * \frac{S_0}{\lambda}T_a + b *\frsc{S_0}{\lambda}\]

where \(a\) and \(b\) are empirical parameters; \(S_0\) is the extraterrestrial radiation [MJ m-2 day-1], assuming a solar constant of 1367 W m-2; \(\\lambda\) is the latent heat of vaporisation [MJ kg-1] and \(T_a\) is the air temperature [°C]. The equation was originally derived for the USA, with \(a=0.0147\) and \(b=0.07353\). The default parameters used here are calibrated for the UK, using the method described in Tanguy et al. [2018].

Methods “BR65”, “HG85” and “MB05” use an approximation of the extraterrestrial radiation. See extraterrestrial_solar_radiation().

References

Allen, Pereira, Raes, and Smith [1998], Baier and Robertson [1965], McGuinness and Borone [1972], Tanguy, Prudhomme, Smith, and Hannaford [2018], Thornthwaite [1948], George H. Hargreaves and Zohrab A. Samani [1985]

xclim.indicators.atmos.precip_accumulation(pr='pr', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Total accumulated precipitation (solid and liquid) (realm: atmos)

Total accumulated precipitation. If the average daily temperature is given, the phase parameter can be used to restrict the calculation to precipitation of only one phase (liquid or solid). Precipitation is considered solid if the average daily temperature is below 0°C (and vice versa).

This indicator will check for missing values according to the method “from_context”. Based on indice precip_accumulation(). With injected parameters: tas=None, phase=None.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold of tas over which the precipication is assumed to be liquid rain. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

prcptot (DataArray) – Total accumulated precipitation (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total precipitation.

Notes

Let \(PR_i\) be the mean daily precipitation of day \(i\), then for a period \(j\) starting at day \(a\) and finishing on day \(b\):

\[PR_{ij} = \sum_{i=a}^{b} PR_i\]

If tas and phase are given, the corresponding phase precipitation is estimated before computing the accumulation, using one of snowfall_approximation or rain_approximation with the binary method.

xclim.indicators.atmos.rain_approximation(pr='pr', tas='tas', *, thresh='0 degC', method='binary', ds=None)

Rainfall approximation (realm: atmos)

Liquid precipitation estimated from total precipitation and temperature with a given method and temperature threshold.

Based on indice rain_approximation().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean, maximum, or minimum daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Freezing point temperature. Non-scalar values are not allowed with method ‘brown’. Default : 0 degC. [Required units : [temperature]]

• method ({‘auer’, ‘brown’, ‘binary’}) – Which method to use when approximating snowfall from total precipitation. See notes. Default : binary.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

prlp (DataArray) – Liquid precipitation (“{method}” method with temperature at or above {thresh}) (precipitation_flux) [kg m-2 s-1], with additional attributes: description: Liquid precipitation estimated from total precipitation and temperature with method {method} and threshold temperature {thresh}.

Notes

This method computes the snowfall approximation and subtracts it from the total precipitation to estimate the liquid rain precipitation.

xclim.indicators.atmos.rain_on_frozen_ground_days(pr='pr', tas='tas', *, thresh='1 mm/d', freq='YS', ds=None, **indexer)

Number of rain on frozen ground days (realm: atmos)

The number of days with rain above a given threshold after a series of seven days with average daily temperature below 0°C. Precipitation is assumed to be rain when the daily average temperature is above 0°C.

This indicator will check for missing values according to the method “from_context”. Based on indice rain_on_frozen_ground_days().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Precipitation threshold to consider a day as a rain event. Default : 1 mm/d. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

rain_frzgr (DataArray) – Number of rain on frozen ground days (mean daily temperature > 0℃ and precipitation > {thresh}) (number_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [days], with additional attributes: description: {freq} number of days with rain above {thresh} after a series of seven days with average daily temperature below 0℃. Precipitation is assumed to be rain when the daily average temperature is above 0℃.

Notes

Let \(PR_i\) be the mean daily precipitation and \(TG_i\) be the mean daily temperature of day \(i\). Then for a period \(j\), rain on frozen grounds days are counted where:

\[PR_{i} > Threshold [mm]\]

and where

\[TG_{i} ≤ 0℃\]

is true for continuous periods where \(i ≥ 7\)

xclim.indicators.atmos.relative_humidity(tas='tas', huss='huss', ps='ps', *, ice_thresh=None, method='sonntag90', ds=None)

Relative humidity from temperature, specific humidity, and pressure (realm: atmos)

Calculation of relative humidity from temperature, specific humidity, and pressure using the saturation vapour pressure.

Based on indice relative_humidity(). With injected parameters: tdps=None, invalid_values=mask.

Parameters:

• tas (str or DataArray) – Temperature array Default : ds.tas. [Required units : [temperature]]

• huss (str or DataArray) – Specific humidity. Must be given if tdps is not given. Default : ds.huss. [Required units : []]

• ps (str or DataArray) – Air Pressure. Must be given if tdps is not given. Default : ds.ps. [Required units : [pressure]]

• ice_thresh (quantity (string or DataArray, with units)) – Threshold temperature under which to switch to equations in reference to ice instead of water. If None (default) everything is computed with reference to water. Does nothing if ‘method’ is “bohren98”. Default : None. [Required units : [temperature]]

• method ({‘wmo08’, ‘tetens30’, ‘goffgratch46’, ‘sonntag90’, ‘bohren98’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hurs (DataArray) – Relative Humidity (“{method}” method) (relative_humidity) [%], with additional attributes: description: <Dynamically generated string>

Notes

In the following, let \(T\), \(T_d\), \(q\) and \(p\) be the temperature, the dew point temperature, the specific humidity and the air pressure.

For the “bohren98” method : This method does not use the saturation vapour pressure directly, but rather uses an approximation of the ratio of \(\frac{e_{sat}(T_d)}{e_{sat}(T)}\). With \(L\) the enthalpy of vaporization of water and \(R_w\) the gas constant for water vapour, the relative humidity is computed as:

\[RH = e^{\frac{-L (T - T_d)}{R_wTT_d}}\]

From Bohren and Albrecht [1998], formula taken from Lawrence [2005]. \(L = 2.5\times 10^{-6}\) J kg-1, exact for \(T = 273.15\) K, is used.

Other methods: With \(w\), \(w_{sat}\), \(e_{sat}\) the mixing ratio, the saturation mixing ratio and the saturation vapour pressure. If the dewpoint temperature is given, relative humidity is computed as:

\[RH = 100\frac{e_{sat}(T_d)}{e_{sat}(T)}\]

Otherwise, the specific humidity and the air pressure must be given so relative humidity can be computed as:

\[RH = 100\frac{w}{w_{sat}} w = \frac{q}{1-q} w_{sat} = 0.622\frac{e_{sat}}{P - e_{sat}}\]

The methods differ by how \(e_{sat}\) is computed. See the doc of xclim.core.utils.saturation_vapor_pressure().

References

Bohren and Albrecht [1998], Lawrence [2005]

xclim.indicators.atmos.relative_humidity_from_dewpoint(tas='tas', tdps='tdps', *, ice_thresh=None, method='sonntag90', ds=None)

Relative humidity from temperature and dewpoint temperature (realm: atmos)

Calculation of relative humidity from temperature and dew point using the saturation vapour pressure.

Based on indice relative_humidity(). With injected parameters: huss=None, ps=None, invalid_values=mask.

Parameters:

• tas (str or DataArray) – Temperature array Default : ds.tas. [Required units : [temperature]]

• tdps (str or DataArray) – Dewpoint temperature, if specified, overrides huss and ps. Default : ds.tdps. [Required units : [temperature]]

• ice_thresh (quantity (string or DataArray, with units)) – Threshold temperature under which to switch to equations in reference to ice instead of water. If None (default) everything is computed with reference to water. Does nothing if ‘method’ is “bohren98”. Default : None. [Required units : [temperature]]

• method ({‘wmo08’, ‘tetens30’, ‘goffgratch46’, ‘sonntag90’, ‘bohren98’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hurs (DataArray) – Relative humidity (“{method}” method) (relative_humidity) [%], with additional attributes: description: <Dynamically generated string>

Notes

In the following, let \(T\), \(T_d\), \(q\) and \(p\) be the temperature, the dew point temperature, the specific humidity and the air pressure.

For the “bohren98” method : This method does not use the saturation vapour pressure directly, but rather uses an approximation of the ratio of \(\frac{e_{sat}(T_d)}{e_{sat}(T)}\). With \(L\) the enthalpy of vaporization of water and \(R_w\) the gas constant for water vapour, the relative humidity is computed as:

\[RH = e^{\frac{-L (T - T_d)}{R_wTT_d}}\]

From Bohren and Albrecht [1998], formula taken from Lawrence [2005]. \(L = 2.5\times 10^{-6}\) J kg-1, exact for \(T = 273.15\) K, is used.

Other methods: With \(w\), \(w_{sat}\), \(e_{sat}\) the mixing ratio, the saturation mixing ratio and the saturation vapour pressure. If the dewpoint temperature is given, relative humidity is computed as:

\[RH = 100\frac{e_{sat}(T_d)}{e_{sat}(T)}\]

Otherwise, the specific humidity and the air pressure must be given so relative humidity can be computed as:

\[RH = 100\frac{w}{w_{sat}} w = \frac{q}{1-q} w_{sat} = 0.622\frac{e_{sat}}{P - e_{sat}}\]

The methods differ by how \(e_{sat}\) is computed. See the doc of xclim.core.utils.saturation_vapor_pressure().

References

Bohren and Albrecht [1998], Lawrence [2005]

xclim.indicators.atmos.rprctot(pr='pr', prc='prc', *, thresh='1.0 mm/day', freq='YS', op='>=', ds=None, **indexer)

Proportion of accumulated precipitation arising from convective processes (realm: atmos)

The proportion of total precipitation due to convective processes. Only days with surpassing a minimum precipitation flux are considered.

This indicator will check for missing values according to the method “from_context”. Based on indice rprctot().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• prc (str or DataArray) – Daily convective precipitation. Default : ds.prc. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1.0 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

rprctot (DataArray) – Proportion of accumulated precipitation arising from convective processeswith precipitation of at least {thresh}, with additional attributes: cell_methods: time: sum; description: {freq} proportion of accumulated precipitation arising from convective processes with precipitation of at least {thresh}.

xclim.indicators.atmos.saturation_vapor_pressure(tas='tas', *, ice_thresh=None, method='sonntag90', ds=None)

Saturation vapour pressure (e_sat) (realm: atmos)

Calculation of the saturation vapour pressure from the temperature, according to a given method. If ice_thresh is given, the calculation is done with reference to ice for temperatures below this threshold.

Based on indice saturation_vapor_pressure().

Parameters:

• tas (str or DataArray) – Temperature array. Default : ds.tas. [Required units : [temperature]]

• ice_thresh (quantity (string or DataArray, with units)) – Threshold temperature under which to switch to equations in reference to ice instead of water. If None (default) everything is computed with reference to water. Default : None. [Required units : [temperature]]

• method ({‘wmo08’, ‘tetens30’, ‘goffgratch46’, ‘sonntag90’, ‘its90’}) – Which method to use, see notes. Default : sonntag90.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

e_sat (DataArray) – Saturation vapour pressure (“{method}” method) [Pa], with additional attributes: description: <Dynamically generated string>

Notes

In all cases implemented here \(log(e_{sat})\) is an empirically fitted function (usually a polynomial) where coefficients can be different when ice is taken as reference instead of water. Available methods are:

• “goffgratch46” or “GG46”, based on Goff and Gratch [1946], values and equation taken from Vömel [2016].

• “sonntag90” or “SO90”, taken from SONNTAG [1990].

• “tetens30” or “TE30”, based on Tetens [1930], values and equation taken from Vömel [2016].

• “wmo08” or “WMO08”, taken from World Meteorological Organization [2008].

• “its90” or “ITS90”, taken from Hardy [1998].

References

Goff and Gratch [1946], Hardy [1998], SONNTAG [1990], Tetens [1930], Vömel [2016], World Meteorological Organization [2008]

xclim.indicators.atmos.shortwave_upwelling_radiation_from_net_downwelling(rss='rss', rsds='rsds', *, ds=None)

Upwelling shortwave radiation (realm: atmos)

Based on indice shortwave_upwelling_radiation_from_net_downwelling().

Parameters:

• rss (str or DataArray) – Surface net solar radiation. Default : ds.rss. [Required units : [radiation]]

• rsds (str or DataArray) – Surface downwelling solar radiation. Default : ds.rsds. [Required units : [radiation]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rsus (DataArray) – Upwelling shortwave flux (surface_upwelling_shortwave_flux) [W m-2], with additional attributes: description: The calculation of upwelling shortwave radiative flux from net surface shortwave and downwelling surface shortwave fluxes.

xclim.indicators.atmos.snowfall_approximation(pr='pr', tas='tas', *, thresh='0 degC', method='binary', ds=None)

Snowfall approximation (realm: atmos)

Solid precipitation estimated from total precipitation and temperature with a given method and temperature threshold.

Based on indice snowfall_approximation().

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean, maximum, or minimum daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Freezing point temperature. Non-scalar values are not allowed with method “brown”. Default : 0 degC. [Required units : [temperature]]

• method ({‘auer’, ‘brown’, ‘binary’}) – Which method to use when approximating snowfall from total precipitation. See notes. Default : binary.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

prsn (DataArray) – Solid precipitation (“{method}” method with temperature at or below {thresh}) (solid_precipitation_flux) [kg m-2 s-1], with additional attributes: description: Solid precipitation estimated from total precipitation and temperature with method {method} and threshold temperature {thresh}.

Notes

The following methods are available to approximate snowfall and are drawn from the Canadian Land Surface Scheme [Melton, 2019, Verseghy, 2009].

• 'binary' : When the temperature is under the freezing threshold, precipitation is assumed to be solid. The method is agnostic to the type of temperature used (mean, maximum or minimum).

• 'brown' : The phase between the freezing threshold goes from solid to liquid linearly over a range of 2°C over the freezing point.

• 'auer' : The phase between the freezing threshold goes from solid to liquid as a degree six polynomial over a range of 6°C over the freezing point.

References

Melton [2019], Verseghy [2009]

xclim.indicators.atmos.solid_precip_accumulation(pr='pr', tas='tas', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Total accumulated solid precipitation. (realm: atmos)

Total accumulated solid precipitation. Precipitation is considered solid when the average daily temperature is at or below 0°C.

This indicator will check for missing values according to the method “from_context”. Based on indice precip_accumulation(). With injected parameters: phase=solid.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean, maximum or minimum daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold of tas over which the precipication is assumed to be liquid rain. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

solidprcptot (DataArray) – Total accumulated solid precipitation (lwe_thickness_of_snowfall_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total solid precipitation, estimated as precipitation when temperature at or below {thresh}.

Notes

Let \(PR_i\) be the mean daily precipitation of day \(i\), then for a period \(j\) starting at day \(a\) and finishing on day \(b\):

\[PR_{ij} = \sum_{i=a}^{b} PR_i\]

If tas and phase are given, the corresponding phase precipitation is estimated before computing the accumulation, using one of snowfall_approximation or rain_approximation with the binary method.

xclim.indicators.atmos.specific_humidity(tas='tas', hurs='hurs', ps='ps', *, ice_thresh=None, method='sonntag90', ds=None)

Specific humidity from temperature, relative humidity, and pressure (realm: atmos)

Calculation of specific humidity from temperature, relative humidity, and pressure using the saturation vapour pressure.

Based on indice specific_humidity(). With injected parameters: invalid_values=mask.

Parameters:

• tas (str or DataArray) – Temperature array Default : ds.tas. [Required units : [temperature]]

• hurs (str or DataArray) – Relative Humidity. Default : ds.hurs. [Required units : []]

• ps (str or DataArray) – Air Pressure. Default : ds.ps. [Required units : [pressure]]

• ice_thresh (quantity (string or DataArray, with units)) – Threshold temperature under which to switch to equations in reference to ice instead of water. If None (default) everything is computed with reference to water. Default : None. [Required units : [temperature]]

• method ({‘tetens30’, ‘wmo08’, ‘goffgratch46’, ‘sonntag90’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

huss (DataArray) – Specific Humidity (“{method}” method) (specific_humidity), with additional attributes: description: <Dynamically generated string>

Notes

In the following, let \(T\), \(hurs\) (in %) and \(p\) be the temperature, the relative humidity and the air pressure. With \(w\), \(w_{sat}\), \(e_{sat}\) the mixing ratio, the saturation mixing ratio and the saturation vapour pressure, specific humidity \(q\) is computed as:

\[w_{sat} = 0.622\frac{e_{sat}}{P - e_{sat}} w = w_{sat} * hurs / 100 q = w / (1 + w)\]

The methods differ by how \(e_{sat}\) is computed. See xclim.core.utils.saturation_vapor_pressure().

If invalid_values is not None, the saturation specific humidity \(q_{sat}\) is computed as:

\[q_{sat} = w_{sat} / (1 + w_{sat})\]

References

World Meteorological Organization [2008]

xclim.indicators.atmos.specific_humidity_from_dewpoint(tdps='tdps', ps='ps', *, method='sonntag90', ds=None)

Specific humidity from dew point temperature and pressure (realm: atmos)

Calculation of the specific humidity from dew point temperature and pressure using the saturation vapour pressure.

Based on indice specific_humidity_from_dewpoint().

Parameters:

• tdps (str or DataArray) – Dewpoint temperature array. Default : ds.tdps. [Required units : [temperature]]

• ps (str or DataArray) – Air pressure array. Default : ds.ps. [Required units : [pressure]]

• method ({‘tetens30’, ‘wmo08’, ‘goffgratch46’, ‘sonntag90’}) – Method to compute the saturation vapour pressure. Default : sonntag90.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

huss_fromdewpoint (DataArray) – Specific humidity (“{method}” method) (specific_humidity), with additional attributes: description: Computed from dewpoint temperature and pressure through the saturation vapor pressure, which was calculated according to the {method} method.

Notes

If \(e\) is the water vapour pressure, and \(p\) the total air pressure, then specific humidity is given by

\[q = m_w e / ( m_a (p - e) + m_w e )\]

where \(m_w\) and \(m_a\) are the molecular weights of water and dry air respectively. This formula is often written with \(ε = m_w / m_a\), which simplifies to \(q = ε e / (p - e (1 - ε))\).

References

World Meteorological Organization [2008]

xclim.indicators.atmos.standardized_precipitation_evapotranspiration_index(wb='wb', *, wb_cal, freq='MS', window=1, dist='gamma', method='APP', ds=None)

Standardized Precipitation Evapotranspiration Index (SPEI) (realm: atmos)

Water budget (precipitation - evapotranspiration) over a moving window, normalized such that the SPEI averages to 0 for the calibration data. The window unit X is the minimal time period defined by the resampling frequency.

This indicator will check for missing values according to the method “from_context”. Based on indice standardized_precipitation_evapotranspiration_index().

Parameters:

• wb (str or DataArray) – Daily water budget (pr - pet). Default : ds.wb. [Required units : [precipitation]]

• wb_cal (quantity (string or DataArray, with units)) – Daily water budget used for calibration. Default : ds.wb. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. A monthly or daily frequency is expected. Default : MS.

• window (number) – Averaging window length relative to the resampling frequency. For example, if freq=”MS”, i.e. a monthly resampling, the window is an integer number of months. Default : 1.

• dist ({‘fisk’, ‘gamma’}) – Name of the univariate distribution. (see scipy.stats). Default : gamma.

• method ({‘APP’, ‘ML’}) – Name of the fitting method, such as ML (maximum likelihood), APP (approximate). The approximate method uses a deterministic function that doesn’t involve any optimization. Available methods vary with the distribution: ‘gamma’:{‘APP’, ‘ML’}, ‘fisk’:{‘ML’} Default : APP.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

spei (DataArray) – Standardized precipitation evapotranspiration index (SPEI) (spei), with additional attributes: description: Water budget (precipitation minus evapotranspiration) over a moving {window}-X window, normalized such that SPEI averages to 0 for calibration data. The window unit X is the minimal time period defined by the resampling frequency {freq}.

Notes

See Standardized Precipitation Index (SPI) for more details on usage.

xclim.indicators.atmos.standardized_precipitation_index(pr='pr', *, pr_cal, freq='MS', window=1, dist='gamma', method='APP', ds=None)

Standardized Precipitation Index (SPI) (realm: atmos)

Precipitation over a moving window, normalized such that SPI averages to 0 for the calibration data. The window unit X is the minimal time period defined by the resampling frequency.

This indicator will check for missing values according to the method “from_context”. Based on indice standardized_precipitation_index().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• pr_cal (quantity (string or DataArray, with units)) – Daily precipitation used for calibration. Usually this is a temporal subset of pr over some reference period. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. A monthly or daily frequency is expected. Default : MS.

• window (number) – Averaging window length relative to the resampling frequency. For example, if freq=”MS”, i.e. a monthly resampling, the window is an integer number of months. Default : 1.

• dist ({‘fisk’, ‘gamma’}) – Name of the univariate distribution. (see scipy.stats). Default : gamma.

• method ({‘APP’, ‘ML’}) – Name of the fitting method, such as ML (maximum likelihood), APP (approximate). The approximate method uses a deterministic function that doesn’t involve any optimization. Default : APP.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

spi (DataArray) – Standardized Precipitation Index (SPI) (spi), with additional attributes: description: Precipitations over a moving {window}-X window, normalized such that SPI averages to 0 for calibration data. The window unit X is the minimal time period defined by resampling frequency {freq}.

Notes

The length N of the N-month SPI is determined by choosing the window = N. Supported statistical distributions are: [“gamma”]

References

McKee, Doesken, and Kleist [1993]

xclim.indicators.atmos.tg(tasmin='tasmin', tasmax='tasmax', *, ds=None)

Mean temperature (realm: atmos)

The average daily temperature assuming a symmetrical temperature distribution (Tg = (Tx + Tn) / 2).

Based on indice tas().

Parameters:

• tasmin (str or DataArray) – Minimum (daily) temperature Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum (daily) temperature Default : ds.tasmax. [Required units : [temperature]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tg (DataArray) – Daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean within days; description: Estimated mean temperature from maximum and minimum temperatures.

xclim.indicators.atmos.tg10p(tas='tas', tas_per='tas_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with mean temperature below the 10th percentile (realm: atmos)

Number of days with mean temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tg10p().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tas_per (str or DataArray) – 10th percentile of daily mean temperature. Default : ds.tas_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg10p (DataArray) – Number of days with mean temperature below the 10th percentile (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with mean temperature below the 10th percentile. A {tas_per_window} day(s) window, centered on each calendar day in the {tas_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tg90p(tas='tas', tas_per='tas_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with mean temperature above the 90th percentile (realm: atmos)

Number of days with mean temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tg90p().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tas_per (str or DataArray) – 90th percentile of daily mean temperature. Default : ds.tas_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg90p (DataArray) – Number of days with mean temperature above the 90th percentile (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with mean temperature above the 90th percentile. A {tas_per_window} day(s) window, centered on each calendar day in the {tas_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tg_days_above(tas='tas', *, thresh='10.0 degC', freq='YS', op='>', ds=None, **indexer)

Number of days with mean temperature above a given threshold (realm: atmos)

The number of days with mean temperature above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_days_above().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 10.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg_days_above (DataArray) – The number of days with mean temperature above {thresh} (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily mean temperature exceeds {thresh}.

Notes

Let \(TG_{ij}\) be the mean daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TG_{ij} > Threshold [℃]\]

xclim.indicators.atmos.tg_days_below(tas='tas', *, thresh='10.0 degC', freq='YS', op='<', ds=None, **indexer)

Number of days with mean temperature below a given threshold (realm: atmos)

The number of days with mean temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_days_below().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 10.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg_days_below (DataArray) – The number of days with mean temperature below {thresh} (number_of_days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily mean temperature is below {thresh}.

Notes

Let \(TG_{ij}\) be the mean daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TG_{ij} < Threshold [℃]\]

xclim.indicators.atmos.tg_max(tas='tas', *, freq='YS', ds=None, **indexer)

Maximum of mean temperature (realm: atmos)

Maximum of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_max().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg_max (DataArray) – Maximum daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily mean temperature.

Notes

Let \(TN_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then the maximum daily mean temperature for period \(j\) is:

\[TNx_j = max(TN_{ij})\]

xclim.indicators.atmos.tg_mean(tas='tas', *, freq='YS', ds=None, **indexer)

Mean temperature (realm: atmos)

Mean of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg_mean (DataArray) – Mean daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily mean temperature.

Notes

Let \(TN_i\) be the mean daily temperature of day \(i\), then for a period \(p\) starting at day \(a\) and finishing on day \(b\):

\[TG_p = \frac{\sum_{i=a}^{b} TN_i}{b - a + 1}\]

xclim.indicators.atmos.tg_min(tas='tas', *, freq='YS', ds=None, **indexer)

Minimum of mean temperature (realm: atmos)

Minimum of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_min().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tg_min (DataArray) – Minimum daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily mean temperature.

Notes

Let \(TG_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then the minimum daily mean temperature for period \(j\) is:

\[TGn_j = min(TG_{ij})\]

xclim.indicators.atmos.thawing_degree_days(tas='tas', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Thawing degree days (realm: atmos)

The cumulative degree days for days when the average temperature is above a given threshold, typically 0°C.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_degree_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

thawing_degree_days (DataArray) – Cumulative sum of temperature degrees for mean daily temperature above {thresh} (integral_of_air_temperature_excess_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} thawing degree days (mean temperature above {thresh}).

Notes

Let \(TG_{ij}\) be the mean daily temperature at day \(i\) of period \(j\). Then the growing degree days are:

\[GD4_j = \sum_{i=1}^I (TG_{ij}-{4} | TG_{ij} > {4}℃)\]

xclim.indicators.atmos.tn10p(tasmin='tasmin', tasmin_per='tasmin_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with minimum temperature below the 10th percentile (realm: atmos)

Number of days with minimum temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tn10p().

Parameters:

• tasmin (str or DataArray) – Mean daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – 10th percentile of daily minimum temperature. Default : ds.tasmin_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn10p (DataArray) – Number of days with minimum temperature below the 10th percentile (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with minimum temperature below the 10th percentile. A {tasmin_per_window} day(s) window, centered on each calendar day in the {tasmin_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tn90p(tasmin='tasmin', tasmin_per='tasmin_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with minimum temperature above the 90th percentile (realm: atmos)

Number of days with minimum temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tn90p().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – 90th percentile of daily minimum temperature. Default : ds.tasmin_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn90p (DataArray) – Number of days with minimum temperature above the 90th percentile (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with minimum temperature above the 90th percentile. A {tasmin_per_window} day(s) window, centered on each calendar day in the {tasmin_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tn_days_above(tasmin='tasmin', *, thresh='20.0 degC', freq='YS', op='>', ds=None, **indexer)

Number of days with minimum temperature above a given threshold (realm: atmos)

The number of days with minimum temperature above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_days_above().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 20.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn_days_above (DataArray) – The number of days with minimum temperature above {thresh} (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily minimum temperature exceeds {thresh}.

Notes

Let \(TN_{ij}\) be the minimum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TN_{ij} > Threshold [℃]\]

xclim.indicators.atmos.tn_days_below(tasmin='tasmin', *, thresh='-10.0 degC', freq='YS', op='<', ds=None, **indexer)

Number of days with minimum temperature below a given threshold (realm: atmos)

The number of days with minimum temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_days_below().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : -10.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn_days_below (DataArray) – The number of days with minimum temperature below {thresh} (number_of_days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily minimum temperature is below {thresh}.

Notes

Let \(TN_{ij}\) be the minimum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TN_{ij} < Threshold [℃]\]

xclim.indicators.atmos.tn_max(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Maximum of minimum temperature (realm: atmos)

Maximum of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_max().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn_max (DataArray) – Maximum daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then the maximum daily minimum temperature for period \(j\) is:

\[TNx_j = max(TN_{ij})\]

xclim.indicators.atmos.tn_mean(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Mean of minimum temperature (realm: atmos)

Mean of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_mean().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn_mean (DataArray) – Mean daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then mean values in period \(j\) are given by:

\[TN_{ij} = \frac{ \sum_{i=1}^{I} TN_{ij} }{I}\]

xclim.indicators.atmos.tn_min(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Minimum temperature (realm: atmos)

Minimum of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_min().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tn_min (DataArray) – Minimum daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then the minimum daily minimum temperature for period \(j\) is:

\[TNn_j = min(TN_{ij})\]

xclim.indicators.atmos.tropical_nights(tasmin='tasmin', *, thresh='20.0 degC', freq='YS', op='>', ds=None, **indexer)

Tropical nights (realm: atmos)

Number of days where minimum temperature is above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_days_above().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 20.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tropical_nights (DataArray) – Number of days with minimum daily temperature above {thresh} (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of Tropical Nights, defined as days with minimum daily temperature above {thresh}.

Notes

Let \(TN_{ij}\) be the minimum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TN_{ij} > Threshold [℃]\]

xclim.indicators.atmos.tx10p(tasmax='tasmax', tasmax_per='tasmax_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with maximum temperature below the 10th percentile (realm: atmos)

Number of days with maximum temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tx10p().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – 10th percentile of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx10p (DataArray) – Number of days with maximum temperature below the 10th percentile (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with maximum temperature below the 10th percentile. A {tasmax_per_window} day(s) window, centered on each calendar day in the {tasmax_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tx90p(tasmax='tasmax', tasmax_per='tasmax_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with maximum temperature above the 90th percentile (realm: atmos)

Number of days with maximum temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tx90p().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – 90th percentile of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx90p (DataArray) – Number of days with maximum temperature above the 90th percentile (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with maximum temperature above the 90th percentile. A {tasmax_per_window} day(s) window, centered on each calendar day in the {tasmax_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

xclim.indicators.atmos.tx_days_above(tasmax='tasmax', *, thresh='25.0 degC', freq='YS', op='>', ds=None, **indexer)

Number of days with maximum temperature above a given threshold (realm: atmos)

The number of days with maximum temperature above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_days_above().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 25.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_days_above (DataArray) – The number of days with maximum temperature above {thresh} (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily maximum temperature exceeds {thresh}.

Notes

Let \(TX_{ij}\) be the maximum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TX_{ij} > Threshold [℃]\]

xclim.indicators.atmos.tx_days_below(tasmax='tasmax', *, thresh='25.0 degC', freq='YS', op='<', ds=None, **indexer)

Number of days with maximum temperature below a given threshold (realm: atmos)

The number of days with maximum temperature below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_days_below().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh (quantity (string or DataArray, with units)) – Threshold temperature on which to base evaluation. Default : 25.0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_days_below (DataArray) – The number of days with maximum temperature below {thresh} (number_of_days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily max temperature is below {thresh}.

Notes

Let \(TX_{ij}\) be the maximum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TX_{ij} < Threshold [℃]\]

xclim.indicators.atmos.tx_max(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Maximum temperature (realm: atmos)

Maximum of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_max().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_max (DataArray) – Maximum daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then the maximum daily maximum temperature for period \(j\) is:

\[TXx_j = max(TX_{ij})\]

xclim.indicators.atmos.tx_mean(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Mean of maximum temperature (realm: atmos)

Mean of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_mean().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_mean (DataArray) – Mean daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then mean values in period \(j\) are given by:

\[TX_{ij} = \frac{ \sum_{i=1}^{I} TX_{ij} }{I}\]

xclim.indicators.atmos.tx_min(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Minimum of maximum temperature (realm: atmos)

Minimum of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_min().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_min (DataArray) – Minimum daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then the minimum daily maximum temperature for period \(j\) is:

\[TXn_j = min(TX_{ij})\]

xclim.indicators.atmos.tx_tn_days_above(tasmin='tasmin', tasmax='tasmax', *, thresh_tasmin='22 degC', thresh_tasmax='30 degC', freq='YS', op='>', ds=None, **indexer)

Number of days with daily minimum and maximum temperatures exceeding thresholds (realm: atmos)

Number of days with daily maximum and minimum temperatures above given thresholds.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_tn_days_above().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• thresh_tasmin (quantity (string or DataArray, with units)) – Threshold temperature for tasmin on which to base evaluation. Default : 22 degC. [Required units : [temperature]]

• thresh_tasmax (quantity (string or DataArray, with units)) – Threshold temperature for tasmax on which to base evaluation. Default : 30 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

tx_tn_days_above (DataArray) – Number of days with daily minimum above {thresh_tasmin} and daily maximum temperatures above {thresh_tasmax} (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: description: {freq} number of days where daily maximum temperature exceeds {thresh_tasmax} and minimum temperature exceeds {thresh_tasmin}.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\), \(TN_{ij}\) the daily minimum temperature at day \(i\) of period \(j\), \(TX_{thresh}\) the threshold for maximum daily temperature, and \(TN_{thresh}\) the threshold for minimum daily temperature. Then counted is the number of days where:

\[TX_{ij} > TX_{thresh} [℃]\]

and where:

\[TN_{ij} > TN_{thresh} [℃]\]

xclim.indicators.atmos.universal_thermal_climate_index(tas='tas', hurs='hurs', sfcWind='sfcWind', mrt=None, rsds=None, rsus=None, rlds=None, rlus=None, *, stat='average', mask_invalid=True, ds=None)

Universal Thermal Climate Index (UTCI) (realm: atmos)

UTCI is the equivalent temperature for the environment derived from a reference environment and is used to evaluate heat stress in outdoor spaces.

Based on indice universal_thermal_climate_index().

Parameters:

• tas (str or DataArray) – Mean temperature Default : ds.tas. [Required units : [temperature]]

• hurs (str or DataArray) – Relative Humidity Default : ds.hurs. [Required units : []]

• sfcWind (str or DataArray) – Wind velocity Default : ds.sfcWind. [Required units : [speed]]

• mrt (str or DataArray, optional) – Mean radiant temperature [Required units : [temperature]]

• rsds (str or DataArray, optional) – Surface Downwelling Shortwave Radiation This is necessary if mrt is not None. [Required units : [radiation]]

• rsus (str or DataArray, optional) – Surface Upwelling Shortwave Radiation This is necessary if mrt is not None. [Required units : [radiation]]

• rlds (str or DataArray, optional) – Surface Downwelling Longwave Radiation This is necessary if mrt is not None. [Required units : [radiation]]

• rlus (str or DataArray, optional) – Surface Upwelling Longwave Radiation This is necessary if mrt is not None. [Required units : [radiation]]

• stat ({‘average’, ‘sunlit’, ‘instant’}) – Which statistic to apply. If “average”, the average of the cosine of the solar zenith angle is calculated. If “instant”, the instantaneous cosine of the solar zenith angle is calculated. If “sunlit”, the cosine of the solar zenith angle is calculated during the sunlit period of each interval. If “instant”, the instantaneous cosine of the solar zenith angle is calculated. This is necessary if mrt is not None. Default : average.

• mask_invalid (boolean) – If True (default), UTCI values are NaN where any of the inputs are outside their validity ranges : -50°C < tas < 50°C, -30°C < tas - mrt < 30°C and 0.5 m/s < sfcWind < 17.0 m/s. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

utci (DataArray) – Universal Thermal Climate Index (UTCI) [K], with additional attributes: description: UTCI is the equivalent temperature for the environment derived from a reference environment and is used to evaluate heat stress in outdoor spaces.

Notes

See: http://www.utci.org/utcineu/utcineu.php

References

Bröde [2009], Błażejczyk, Jendritzky, Bröde, Fiala, Havenith, Epstein, Psikuta, and Kampmann [2013]

xclim.indicators.atmos.warm_and_dry_days(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Warm and dry days (realm: atmos)

Number of days with temperature above a given percentile and precipitation below a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_and_dry_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Third quartile of daily mean temperature computed by month. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – First quartile of daily total precipitation computed by month. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

warm_and_dry_days (DataArray) – Number of days where temperature is above {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is above {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

Beniston [2009]

xclim.indicators.atmos.warm_and_wet_days(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Warm and wet days (realm: atmos)

Number of days with temperature above a given percentile and precipitation above a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_and_wet_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Third quartile of daily mean temperature computed by month. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Third quartile of daily total precipitation computed by month. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

warm_and_wet_days (DataArray) – Number of days where temperature above {tas_per_thresh}th percentile and precipitation above {pr_per_thresh}th percentile [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is above {tas_per_thresh}th percentile and precipitation is above {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

Beniston [2009]

xclim.indicators.atmos.warm_spell_duration_index(tasmax='tasmax', tasmax_per='tasmax_per', *, window=6, freq='YS', resample_before_rl=True, bootstrap=False, op='>', ds=None)

Warm spell duration index (realm: atmos)

Number of days part of a percentile-defined warm spell. A warm spell occurs when the maximum daily temperature is above a given percentile for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_spell_duration_index().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – percentile(s) of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• window (number) – Minimum number of days with temperature above threshold to qualify as a warm spell. Default : 6.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

warm_spell_duration_index (DataArray) – Number of days with at least {window} consecutive days where the maximum daily temperature is above the {tasmax_per_thresh}th percentile(s) (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with at least {window} consecutive days where the maximum daily temperature is above the {tasmax_per_thresh}th percentile(s). A {tasmax_per_window} day(s) window, centred on each calendar day in the {tasmax_per_period} period, is used to compute the {tasmax_per_thresh}th percentile(s).

References

From the Expert Team on Climate Change Detection, Monitoring and Indices (ETCCDMI; [Zhang et al., 2011]). Used in Alexander, Zhang, Peterson, Caesar, Gleason, Klein Tank, Haylock, Collins, Trewin, Rahimzadeh, Tagipour, Rupa Kumar, Revadekar, Griffiths, Vincent, Stephenson, Burn, Aguilar, Brunet, Taylor, New, Zhai, Rusticucci, and Vazquez-Aguirre [2006]

xclim.indicators.atmos.water_budget(pr='pr', evspsblpot=None, tasmin=None, tasmax=None, tas=None, lat=None, hurs=None, rsds=None, rsus=None, rlds=None, rlus=None, sfcWind=None, *, ds=None)

Water budget (realm: atmos)

Precipitation minus potential evapotranspiration as a measure of an approximated surface water budget.

Based on indice water_budget(). With injected parameters: method=dummy.

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• evspsblpot (str or DataArray, optional) – Potential evapotranspiration [Required units : [precipitation]]

• tasmin (str or DataArray, optional) – Minimum daily temperature. [Required units : [temperature]]

• tasmax (str or DataArray, optional) – Maximum daily temperature. [Required units : [temperature]]

• tas (str or DataArray, optional) – Mean daily temperature. [Required units : [temperature]]

• lat (str or DataArray, optional) – Latitude coordinate, needed if evspsblpot is not given. If None, a CF-conformant “latitude” field must be available within the pr DataArray. [Required units : []]

• hurs (str or DataArray, optional) – Relative humidity. [Required units : []]

• rsds (str or DataArray, optional) – Surface Downwelling Shortwave Radiation [Required units : [radiation]]

• rsus (str or DataArray, optional) – Surface Upwelling Shortwave Radiation [Required units : [radiation]]

• rlds (str or DataArray, optional) – Surface Downwelling Longwave Radiation [Required units : [radiation]]

• rlus (str or DataArray, optional) – Surface Upwelling Longwave Radiation [Required units : [radiation]]

• sfcWind (str or DataArray, optional) – Surface wind velocity (at 10 m) [Required units : [speed]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

water_budget (DataArray) – Water budget [kg m-2 s-1], with additional attributes: description: Precipitation minus potential evapotranspiration as a measure of an approximated surface water budget.

xclim.indicators.atmos.water_budget_from_tas(pr='pr', evspsblpot=None, tasmin=None, tasmax=None, tas=None, lat=None, hurs=None, rsds=None, rsus=None, rlds=None, rlus=None, sfcWind=None, *, method='BR65', ds=None)

Water budget (realm: atmos)

Precipitation minus potential evapotranspiration as a measure of an approximated surface water budget, where the potential evapotranspiration is calculated with a given method.

Based on indice water_budget().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• evspsblpot (str or DataArray, optional) – Potential evapotranspiration [Required units : [precipitation]]

• tasmin (str or DataArray, optional) – Minimum daily temperature. [Required units : [temperature]]

• tasmax (str or DataArray, optional) – Maximum daily temperature. [Required units : [temperature]]

• tas (str or DataArray, optional) – Mean daily temperature. [Required units : [temperature]]

• lat (str or DataArray, optional) – Latitude coordinate, needed if evspsblpot is not given. If None, a CF-conformant “latitude” field must be available within the pr DataArray. [Required units : []]

• hurs (str or DataArray, optional) – Relative humidity. [Required units : []]

• rsds (str or DataArray, optional) – Surface Downwelling Shortwave Radiation [Required units : [radiation]]

• rsus (str or DataArray, optional) – Surface Upwelling Shortwave Radiation [Required units : [radiation]]

• rlds (str or DataArray, optional) – Surface Downwelling Longwave Radiation [Required units : [radiation]]

• rlus (str or DataArray, optional) – Surface Upwelling Longwave Radiation [Required units : [radiation]]

• sfcWind (str or DataArray, optional) – Surface wind velocity (at 10 m) [Required units : [speed]]

• method (str) – Method to use to calculate the potential evapotranspiration. Default : BR65.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

water_budget_from_tas (DataArray) – Water budget (“{method}” method) [kg m-2 s-1], with additional attributes: description: Precipitation minus potential evapotranspiration as a measure of an approximated surface water budget, where the potential evapotranspiration is calculated with the {method} method.

xclim.indicators.atmos.wet_precip_accumulation(pr='pr', *, thresh='1 mm/day', freq='YS', ds=None, **indexer)

Total accumulated precipitation (solid and liquid) during wet days (realm: atmos)

Total accumulated precipitation on days with precipitation. A day is considered to have precipitation if the precipitation is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot().

Parameters:

• pr (str or DataArray) – Total precipitation flux [mm d-1], [mm week-1], [mm month-1] or similar. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold over which precipitation starts being cumulated. Default : 1 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

wet_prcptot (DataArray) – Total accumulated precipitation over days where precipitation exceeds {thresh} (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total precipitation over wet days, defined as days where precipitation exceeds {thresh}.

xclim.indicators.atmos.wetdays(pr='pr', *, thresh='1.0 mm/day', freq='YS', op='>=', ds=None, **indexer)

Number of wet days (realm: atmos)

The number of days with daily precipitation at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice wetdays().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1.0 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

wetdays (DataArray) – Number of days with daily precipitation at or above {thresh} (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with daily precipitation at or above {thresh}.

xclim.indicators.atmos.wetdays_prop(pr='pr', *, thresh='1.0 mm/day', freq='YS', op='>=', ds=None, **indexer)

Proportion of wet days (realm: atmos)

The proportion of days with daily precipitation at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice wetdays_prop().

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Precipitation value over which a day is considered wet. Default : 1.0 mm/day. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

wetdays_prop (DataArray) – Proportion of days with precipitation at or above {thresh} [1], with additional attributes: cell_methods: time: sum over days; description: {freq} proportion of days with precipitation at or above {thresh}.

xclim.indicators.atmos.wind_chill_index(tas='tas', sfcWind='sfcWind', *, method='CAN', ds=None)

Wind chill (realm: atmos)

Wind chill factor is an index that equates to how cold an average person feels. It is calculated from the temperature and the wind speed at 10 m. As defined by Environment and Climate Change Canada, a second formula is used for light winds. The standard formula is otherwise the same as used in the United States.

Based on indice wind_chill_index(). With injected parameters: mask_invalid=True.

Parameters:

• tas (str or DataArray) – Surface air temperature. Default : ds.tas. [Required units : [temperature]]

• sfcWind (str or DataArray) – Surface wind speed (10 m). Default : ds.sfcWind. [Required units : [speed]]

• method ({‘US’, ‘CAN’}) – If “CAN” (default), a “slow wind” equation is used where winds are slower than 5 km/h, see Notes. Default : CAN.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

wind_chill (DataArray) – Wind chill factor [degC], with additional attributes: description: <Dynamically generated string>

Notes

Following the calculations of Environment and Climate Change Canada, this function switches from the standardized index to another one for slow winds. The standard index is the same as used by the National Weather Service of the USA [US Department of Commerce, n.d.]. Given a temperature at surface \(T\) (in °C) and 10-m wind speed \(V\) (in km/h), the Wind Chill Index \(W\) (dimensionless) is computed as:

\[W = 13.12 + 0.6125*T - 11.37*V^0.16 + 0.3965*T*V^0.16\]

Under slow winds (\(V < 5\) km/h), and using the canadian method, it becomes:

\[W = T + \frac{-1.59 + 0.1345 * T}{5} * V\]

Both equations are invalid for temperature over 0°C in the canadian method.

The american Wind Chill Temperature index (WCT), as defined by USA’s National Weather Service, is computed when method=’US’. In that case, the maximal valid temperature is 50°F (10 °C) and minimal wind speed is 3 mph (4.8 km/h).

For more information, see:

• National Weather Service FAQ: [US Department of Commerce, n.d.].

• The New Wind Chill Equivalent Temperature Chart: [Osczevski and Bluestein, 2005].

References

Mekis, Vincent, Shephard, and Zhang [2015], US Department of Commerce [n.d.]

xclim.indicators.atmos.wind_speed_from_vector(uas='uas', vas='vas', *, calm_wind_thresh='0.5 m/s', ds=None)

Wind speed and direction from vector (realm: atmos)

Calculation of the magnitude and direction of the wind speed from the two components west-east and south-north.

Based on indice uas_vas_2_sfcwind().

Parameters:

• uas (str or DataArray) – Eastward wind velocity Default : ds.uas. [Required units : [speed]]

• vas (str or DataArray) – Northward wind velocity Default : ds.vas. [Required units : [speed]]

• calm_wind_thresh (quantity (string or DataArray, with units)) – The threshold under which winds are considered “calm” and for which the direction is set to 0. On the Beaufort scale, calm winds are defined as < 0.5 m/s. Default : 0.5 m/s. [Required units : [speed]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

• sfcWind (DataArray) – Near-surface wind speed (wind_speed) [m s-1], with additional attributes: description: Wind speed computed as the magnitude of the (uas, vas) vector.

• sfcWindfromdir (DataArray) – Near-surface wind from direction (wind_from_direction) [degree], with additional attributes: description: Wind direction computed as the angle of the (uas, vas) vector. A direction of 0° is attributed to winds with a speed under {calm_wind_thresh}.

Notes

Winds with a velocity less than calm_wind_thresh are given a wind direction of 0°, while stronger northerly winds are set to 360°.

xclim.indicators.atmos.wind_vector_from_speed(sfcWind='sfcWind', sfcWindfromdir='sfcWindfromdir', *, ds=None)

Wind vector from speed and direction (realm: atmos)

Calculation of the two components (west-east and north-south) of the wind from the magnitude of its speed and direction of origin.

Based on indice sfcwind_2_uas_vas().

Parameters:

• sfcWind (str or DataArray) – Wind velocity Default : ds.sfcWind. [Required units : [speed]]

• sfcWindfromdir (str or DataArray) – Direction from which the wind blows, following the meteorological convention where 360 stands for North. Default : ds.sfcWindfromdir. [Required units : []]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

• uas (DataArray) – Near-surface eastward wind (eastward_wind) [m s-1], with additional attributes: description: Eastward wind speed computed from the magnitude of its speed and direction of origin.

• vas (DataArray) – Near-surface northward wind (northward_wind) [m s-1], with additional attributes: description: Northward wind speed computed from magnitude of its speed and direction of origin.

xclim.indicators.atmos.windy_days(sfcWind='sfcWind', *, thresh='10.8 m s-1', freq='MS', ds=None, **indexer)

Windy days (realm: atmos)

Number of days with surface wind speed at or above threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice windy_days().

Parameters:

• sfcWind (str or DataArray) – Daily average near-surface wind speed. Default : ds.sfcWind. [Required units : [speed]]

• thresh (quantity (string or DataArray, with units)) – Threshold average near-surface wind speed on which to base evaluation. Default : 10.8 m s-1. [Required units : [speed]]

• freq (offset alias (string)) – Resampling frequency. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

windy_days (DataArray) – Number of days with surface wind speed at or above {thresh} (number_of_days_with_sfcWind_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with surface wind speed at or above {thresh}.

Notes

Let \(WS_{ij}\) be the windspeed at day \(i\) of period \(j\). Then counted is the number of days where:

\[WS_{ij} >= Threshold [m s-1]\]

Land Indicators

xclim.indicators.land.base_flow_index(q='q', *, freq='YS', ds=None)

Base flow index (realm: land)

Return the base flow index, defined as the minimum 7-day average flow divided by the mean flow.

This indicator will check for missing values according to the method “from_context”. Based on indice base_flow_index().

Parameters:

• q (str or DataArray) – Rate of river discharge. Default : ds.q. [Required units : [discharge]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

base_flow_index (DataArray) – Base flow index, with additional attributes: description: Minimum of the 7-day moving average flow divided by the mean flow.

Notes

Let \(\mathbf{q}=q_0, q_1, \ldots, q_n\) be the sequence of daily discharge and \(\overline{\mathbf{q}}\) the mean flow over the period. The base flow index is given by:

\[\frac{\min(\mathrm{CMA}_7(\mathbf{q}))}{\overline{\mathbf{q}}}\]

where \(\mathrm{CMA}_7\) is the seven days moving average of the daily flow:

\[\mathrm{CMA}_7(q_i) = \frac{\sum_{j=i-3}^{i+3} q_j}{7}\]

xclim.indicators.land.blowing_snow(snd='snd', sfcWind='sfcWind', *, snd_thresh='5 cm', sfcWind_thresh='15 km/h', window=3, freq='AS-JUL', ds=None)

Blowing snow days (realm: land)

The number of days with snowfall, snow depth, and windspeed over given thresholds for a period of days.

This indicator will check for missing values according to the method “from_context”. Based on indice blowing_snow().

Parameters:

• snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

• sfcWind (str or DataArray) – Wind velocity Default : ds.sfcWind. [Required units : [speed]]

• snd_thresh (quantity (string or DataArray, with units)) – Threshold on net snowfall accumulation over the last window days. Default : 5 cm. [Required units : [length]]

• sfcWind_thresh (quantity (string or DataArray, with units)) – Wind speed threshold. Default : 15 km/h. [Required units : [speed]]

• window (number) – Period over which snow is accumulated before comparing against threshold. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

{freq}_blowing_snow (DataArray) – Days with snowfall and wind speed at or above given thresholds [days], with additional attributes: description: The {freq} number of days with snowfall over last {window} days above {snd_thresh} and wind speed above {sfcWind_thresh}.

xclim.indicators.land.doy_qmax(da='da', *, freq='YS', ds=None, **indexer)

Day of year of the maximum streamflow (realm: land)

This indicator will check for missing values according to the method “from_context”. Based on indice select_resample_op(). With injected parameters: op=<function doymax at 0x7f4ebd027a30>.

Parameters:

• da (str or DataArray) – Input data. Default : ds.da. [Required units : [discharge]]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Time attribute and values over which to subset the array. For example, use season=’DJF’ to select winter values, month=1 to select January, or month=[6,7,8] to select summer months. If not indexer is given, all values are considered. Default : None.

Returns:

q{indexer}_doy_qmax (DataArray) – Day of the year of the maximum streamflow over {indexer}, with additional attributes: description: Day of the year of the maximum streamflow over {indexer}.

xclim.indicators.land.doy_qmin(da='da', *, freq='YS', ds=None, **indexer)

Day of year of the minimum streamflow (realm: land)

This indicator will check for missing values according to the method “from_context”. Based on indice select_resample_op(). With injected parameters: op=<function doymin at 0x7f4ebd027ac0>.

Parameters:

• da (str or DataArray) – Input data. Default : ds.da. [Required units : [discharge]]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Time attribute and values over which to subset the array. For example, use season=’DJF’ to select winter values, month=1 to select January, or month=[6,7,8] to select summer months. If not indexer is given, all values are considered. Default : None.

Returns:

q{indexer}_doy_qmin (DataArray) – Day of the year of the minimum streamflow over {indexer}, with additional attributes: description: Day of the year of the minimum streamflow over {indexer}.

xclim.indicators.land.rb_flashiness_index(q='q', *, freq='YS', ds=None)

Richards-Baker Flashiness Index (realm: land)

Measurement of flow oscillations relative to average flow, quantifying the frequency and speed of flow changes.

This indicator will check for missing values according to the method “from_context”. Based on indice rb_flashiness_index().

Parameters:

• q (str or DataArray) – Rate of river discharge. Default : ds.q. [Required units : [discharge]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rbi (DataArray) – Richards-Baker Flashiness Index, with additional attributes: description: {freq} of Richards-Baker Index, an index measuring the flashiness of flow.

Notes

Let \(\mathbf{q}=q_0, q_1, \ldots, q_n\) be the sequence of daily discharge, the R-B Index is given by:

\[\frac{\sum_{i=1}^n |q_i - q_{i-1}|}{\sum_{i=1}^n q_i}\]

References

Baker, Richards, Loftus, and Kramer [2004]

xclim.indicators.land.snd_max_doy(snd='snd', *, freq='AS-JUL', ds=None, **indexer)

Day of year of maximum snow depth (realm: land)

Day of the year when snow depth reaches its maximum value.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_max_doy().

Parameters:

• snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

{freq}_snd_max_doy (DataArray) – Day of the year when snow depth reaches its maximum value (day_of_year), with additional attributes: description: The {freq} day of the year when snow depth reaches its maximum value.

xclim.indicators.land.snd_season_end(snd='snd', *, thresh='2 cm', window=14, freq='AS-JUL', ds=None)

End date of continuous snow depth cover (realm: land)

The first date on which snow depth is below a given threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_end().

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow thickness. Default : 2 cm. [Required units : [length]]

• window (number) – Minimum number of days with snow depth below threshold. Default : 14.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snd_season_end (DataArray) – End date of continuous snow depth cover (day_of_year), with additional attributes: description: Day of year when snow depth is below {thresh} for {window} consecutive days.

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

xclim.indicators.land.snd_season_length(snd='snd', *, thresh='2 cm', freq='AS-JUL', op='>=', ds=None, **indexer)

Snow cover duration (depth) (realm: land)

Number of days when the snow depth is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_length().

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow thickness. Default : 2 cm. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

snd_season_length (DataArray) – Snow cover duration [days], with additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

xclim.indicators.land.snd_season_start(snd='snd', *, thresh='2 cm', window=14, freq='AS-JUL', ds=None)

Start date of continuous snow depth cover (realm: land)

The first date on which snow depth is greater than or equal to a given threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_start().

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow thickness. Default : 2 cm. [Required units : [length]]

• window (number) – Minimum number of days with snow depth above or equal to threshold. Default : 14.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snd_season_start (DataArray) – Start date of continuous snow depth cover (day_of_year), with additional attributes: description: Day of year when snow depth is above or equal to {thresh} for {window} consecutive days.

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

xclim.indicators.land.snd_to_snw(snd='snd', snr=None, *, const='312 kg m-3', ds=None)

Surface snow amount (realm: atmos)

Based on indice snd_to_snw().

Parameters:

• snd (str or DataArray) – Snow depth [m]. Default : ds.snd. [Required units : [length]]

• snr (str or DataArray, optional) – Snow density [kg/m^3]. [Required units : [mass]/[volume]]

• const (quantity (string or DataArray, with units)) – Constant snow density [kg/m^3] const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snw (DataArray) – Approximation of daily snow amount from snow depth and density (surface_snow_amount) [kg m-2], with additional attributes: description: The approximation of daily snow amount from snow depth and density.

Notes

The estimated mean snow density value of 312 kg m-3 is taken from Sturm et al. [2010].

References

Sturm, Taras, Liston, Derksen, Jonas, and Lea [2010]

xclim.indicators.land.snow_depth(snd='snd', *, freq='YS', ds=None, **indexer)

Mean snow depth (realm: land)

Mean of daily snow depth.

This indicator will check for missing values according to the method “from_context”. Based on indice snow_depth().

Parameters:

• snd (str or DataArray) – Mean daily snow depth. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

snow_depth (DataArray) – Mean of daily snow depth (surface_snow_thickness) [cm], with additional attributes: cell_methods: time: mean over days; description: The {freq} mean of daily mean snow depth.

xclim.indicators.land.snow_melt_we_max(snw='snw', *, window=3, freq='AS-JUL', ds=None)

Maximum snow melt (realm: land)

The water equivalent of the maximum snow melt.

This indicator will check for missing values according to the method “from_context”. Based on indice snow_melt_we_max().

Parameters:

• snw (str or DataArray) – Snow amount (mass per area). Default : ds.snw. [Required units : [mass]/[area]]

• window (number) – Number of days during which the melt is accumulated. Default : 3.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

{freq}_snow_melt_we_max (DataArray) – Maximum snow melt (change_over_time_in_surface_snow_amount) [kg m-2], with additional attributes: description: The {freq} maximum negative change in melt amount over {window} days.

xclim.indicators.land.snw_max(snw='snw', *, freq='AS-JUL', ds=None, **indexer)

Maximum snow amount (realm: land)

The maximum snow amount equivalent on the surface.

This indicator will check for missing values according to the method “from_context”. Based on indice snw_max().

Parameters:

• snw (str or DataArray) – Snow amount (mass per area). Default : ds.snw. [Required units : [mass]/[area]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

{freq}_snw_max (DataArray) – Maximum snow amount equivalent (surface_snow_amount) [kg m-2], with additional attributes: description: The {freq} maximum snow amount equivalent on the surface.

xclim.indicators.land.snw_max_doy(snw='snw', *, freq='AS-JUL', ds=None, **indexer)

Day of year of maximum snow amount (realm: land)

The day of year when snow amount equivalent on the surface reaches its maximum.

This indicator will check for missing values according to the method “from_context”. Based on indice snw_max_doy().

Parameters:

• snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [mass]/[area]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

{freq}_snw_max_doy (DataArray) – Day of year of maximum daily snow amount equivalent (day_of_year), with additional attributes: description: The {freq} day of year when snow amount equivalent on the surface reaches its maximum.

xclim.indicators.land.snw_season_end(snw='snw', *, thresh='20 kg m-2', window=14, freq='AS-JUL', ds=None)

End date of continuous snow amount cover (realm: land)

The first date on which snow amount is below a given threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice snw_season_end().

Parameters:

• snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [mass]/[area]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 20 kg m-2. [Required units : [mass]/[area]]

• window (number) – Minimum number of days with snow water below threshold. Default : 14.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snw_season_end (DataArray) – End date of continuous snow amount cover (day_of_year), with additional attributes: description: Day of year when snow amount is below {thresh} for {window} consecutive days.

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

xclim.indicators.land.snw_season_length(snw='snw', *, thresh='20 kg m-2', freq='AS-JUL', op='>=', ds=None, **indexer)

Snow cover duration (amount) (realm: land)

Number of days when the snow amount is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice snw_season_length().

Parameters:

• snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [mass]/[area]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 20 kg m-2. [Required units : [mass]/[area]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

snw_season_length (DataArray) – Snow cover duration [days], with additional attributes: description: The {freq} number of days with snow amount greater than or equal to {thresh}.

xclim.indicators.land.snw_season_start(snw='snw', *, thresh='20 kg m-2', window=14, freq='AS-JUL', ds=None)

Start date of continuous snow amount cover (realm: land)

The first date on which snow amount is greater than or equal to a given threshold for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice snw_season_start().

Parameters:

• snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [mass]/[area]]

• thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 20 kg m-2. [Required units : [mass]/[area]]

• window (number) – Minimum number of days with snow water above or equal to threshold. Default : 14.

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snw_season_start (DataArray) – Start date of continuous snow amount cover (day_of_year), with additional attributes: description: Day of year when snow amount is above or equal to {thresh} for {window} consecutive days.

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

xclim.indicators.land.snw_to_snd(snw='snw', snr=None, *, const='312 kg m-3', ds=None)

Surface snow depth (realm: atmos)

Based on indice snw_to_snd().

Parameters:

• snw (str or DataArray) – Snow amount [kg/m^2]. If snow water equivalent (swe [m]) is provided instead, will be converted to snw before calculating. Default : ds.snw. [Required units : [mass]/[area]]

• snr (str or DataArray, optional) – Snow density [kg/m^3]. [Required units : [mass]/[volume]]

• const (quantity (string or DataArray, with units)) – Constant snow density [kg/m^3] const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snd (DataArray) – Approximation of daily snow depth from snow amount and density (surface_snow_thickness) [m], with additional attributes: description: The approximation of daily snow depth from snow amount and density.

Notes

The estimated mean snow density value of 312 kg m-3 is taken from Sturm et al. [2010].

References

Sturm, Taras, Liston, Derksen, Jonas, and Lea [2010]

xclim.indicators.land.winter_storm(snd='snd', *, thresh='25 cm', freq='AS-JUL', ds=None, **indexer)

Winter storm days (realm: land)

Number of days with snowfall accumulation greater or equal to threshold (default: 25 cm).

This indicator will check for missing values according to the method “from_context”. Based on indice winter_storm().

Parameters:

• snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

• thresh (quantity (string or DataArray, with units)) – Threshold on snowfall accumulation require to label an event a winter storm. Default : 25 cm. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

{freq}_winter_storm (DataArray) – Days with snowfall at or above a given threshold [days], with additional attributes: description: The {freq} number of days with snowfall accumulation above {thresh}.

Notes

Snowfall accumulation is estimated by the change in snow depth.

Ice-related indicators

xclim.indicators.seaIce.sea_ice_area(siconc='siconc', areacello='areacello', *, thresh='15 pct', ds=None)

Sea ice area (realm: seaIce)

A measure of total ocean surface covered by sea ice.

This indicator will check for missing values according to the method “skip”. Based on indice sea_ice_area().

Parameters:

• siconc (str or DataArray) – Sea ice concentration (area fraction). Default : ds.siconc. [Required units : []]

• areacello (str or DataArray) – Grid cell area (usually over the ocean). Default : ds.areacello. [Required units : [area]]

• thresh (quantity (string or DataArray, with units)) – Minimum sea ice concentration for a grid cell to contribute to the sea ice extent. Default : 15 pct. [Required units : []]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

sea_ice_area (DataArray) – Sum of ice-covered areas where sea ice concentration exceeds {thresh} (sea_ice_area) [m2], with additional attributes: cell_methods: lon: sum lat: sum; description: The sum of ice-covered areas where sea ice concentration exceeds {thresh}.

Notes

To compute sea ice area over a subregion, first mask or subset the input sea ice concentration data.

References

“What is the difference between sea ice area and extent?” - NSIDC [2008]

xclim.indicators.seaIce.sea_ice_extent(siconc='siconc', areacello='areacello', *, thresh='15 pct', ds=None)

Sea ice extent (realm: seaIce)

A measure of the extent of all areas where sea ice concentration exceeds a threshold.

This indicator will check for missing values according to the method “skip”. Based on indice sea_ice_extent().

Parameters:

• siconc (str or DataArray) – Sea ice concentration (area fraction). Default : ds.siconc. [Required units : []]

• areacello (str or DataArray) – Grid cell area. Default : ds.areacello. [Required units : [area]]

• thresh (quantity (string or DataArray, with units)) – Minimum sea ice concentration for a grid cell to contribute to the sea ice extent. Default : 15 pct. [Required units : []]

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

sea_ice_extent (DataArray) – Sum of ocean areas where sea ice concentration exceeds {thresh} (sea_ice_extent) [m2], with additional attributes: cell_methods: lon: sum lat: sum; description: The sum of ocean areas where sea ice concentration exceeds {thresh}.

Notes

To compute sea ice area over a subregion, first mask or subset the input sea ice concentration data.

References

“What is the difference between sea ice area and extent?” - NSIDC [2008]

Virtual Indicator Submodules

CF Standard indices

Indicators found here are defined by the clix-meta project. Adapted documentation from that repository follows:

The repository aims to provide a platform for thinking about, and developing, a unified view of metadata elements required to describe climate indices (aka climate indicators).

To facilitate data exchange and dissemination the metadata should, as far as possible, follow the Climate and Forecasting (CF) Conventions. Considering the very rich and diverse flora of climate indices, this is however not always possible. By collecting a wide range of different indices it is easier to discover any common patterns and features that are currently not well covered by the CF Conventions. Currently identified issues frequently relate to standard_name and/or cell_methods which both are controlled vocabularies of the CF Conventions.

xclim.indicators.cf.cdd(pr='pr', *, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: threshold=1 mm day-1, reducer=max, op=<.

Parameters:

• pr (str or DataArray) – Surface precipitation flux (all phases). Default : ds.pr. [Required units : kg m-2 s-1]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cdd (DataArray) – Maximum consecutive dry days (Precip < 1mm) (spell_length_of_days_with_lwe_thickness_of_precipitation_amount_below_threshold) [day], with additional attributes: cell_methods: time: sum over days; proposed_standard_name: spell_length_with_lwe_thickness_of_precipitation_amount_below_threshold

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.cddcoldTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=>.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cddcold{threshold} (DataArray) – Cooling Degree Days (Tmean > {threshold}C) (integral_wrt_time_of_air_temperature_excess) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

ET-SCI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.cfd(tasmin='tasmin', *, freq='YS', constrain=None, ds=None)

Calculate the number of times some condition is met. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, then this counts the number of times data < threshold. Finally, count the number of occurrences when condition is met.

This indicator will check for missing values according to the method “from_context”. Based on indice count_occurrences(). With injected parameters: threshold=0 degree_Celsius, op=<.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• constrain (Any) – Optionally allowed conditions. Default : None.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cfd (DataArray) – Maximum number of consecutive frost days (Tmin < 0 C) (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_below_threshold

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.csu(tasmax='tasmax', *, freq='YS', constrain=None, ds=None)

Calculate the number of times some condition is met. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, then this counts the number of times data < threshold. Finally, count the number of occurrences when condition is met.

This indicator will check for missing values according to the method “from_context”. Based on indice count_occurrences(). With injected parameters: threshold=25 degree_Celsius, op=>.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• constrain (Any) – Optionally allowed conditions. Default : None.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

csu (DataArray) – Maximum number of consecutive summer days (Tmax >25 C) (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_above_threshold

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctmgeTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctmge{threshold} (DataArray) – Maximum number of consecutive days with Tmean >= {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctmgtTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctmgt{threshold} (DataArray) – Maximum number of consecutive days with Tmean > {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctmleTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctmle{threshold} (DataArray) – Maximum number of consecutive days with Tmean <= {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctmltTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctmlt{threshold} (DataArray) – Maximum number of consecutive days with Tmean < {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctngeTT(tasmin='tasmin', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmin. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctnge{threshold} (DataArray) – Maximum number of consecutive days with Tmin >= {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctngtTT(tasmin='tasmin', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmin. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctngt{threshold} (DataArray) – Maximum number of consecutive days with Tmin > {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctnleTT(tasmin='tasmin', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmin. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctnle{threshold} (DataArray) – Maximum number of consecutive days with Tmin <= {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctnltTT(tasmin='tasmin', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmin. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctnlt{threshold} (DataArray) – Maximum number of consecutive days with Tmin < {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctxgeTT(tasmax='tasmax', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmax. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctxge{threshold} (DataArray) – Maximum number of consecutive days with Tmax >= {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctxgtTT(tasmax='tasmax', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=>.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmax. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctxgt{threshold} (DataArray) – Maximum number of consecutive days with Tmax > {threshold}C (spell_length_of_days_with_air_temperature_above_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_above_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctxleTT(tasmax='tasmax', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmax. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctxle{threshold} (DataArray) – Maximum number of consecutive days with Tmax <= {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_at_or_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ctxltTT(tasmax='tasmax', *, threshold, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: reducer=max, op=<.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tasmax. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ctxlt{threshold} (DataArray) – Maximum number of consecutive days with Tmax < {threshold}C (spell_length_of_days_with_air_temperature_below_threshold) [day], with additional attributes: cell_methods: time: maximum over days; proposed_standard_name: spell_length_with_air_temperature_below_threshold

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.cwd(pr='pr', *, freq='YS', ds=None)

Calculate statistics on lengths of spells. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Then the spells are determined, and finally the statistics according to the specified reducer are calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice spell_length(). With injected parameters: threshold=1 mm day-1, reducer=max, op=>.

Parameters:

• pr (str or DataArray) – Surface precipitation flux (all phases). Default : ds.pr. [Required units : kg m-2 s-1]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

cwd (DataArray) – Maximum consecutive wet days (Precip >= 1mm) (spell_length_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [day], with additional attributes: cell_methods: time: sum over days; proposed_standard_name: spell_length_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ddgtTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=>.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ddgt{threshold} (DataArray) – Degree Days (Tmean > {threshold}C) (integral_wrt_time_of_air_temperature_excess) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ddltTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=<.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ddlt{threshold} (DataArray) – Degree Days (Tmean < {threshold}C) (integral_wrt_time_of_air_temperature_deficit) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.dtr(tasmax='tasmax', tasmin='tasmin', *, freq='MS', ds=None)

Calculate the diurnal temperature range and reduce according to a statistic. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice diurnal_temperature_range(). With injected parameters: reducer=mean.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

dtr (DataArray) – Mean Diurnal Temperature Range [degree_Celsius], with additional attributes: cell_methods: time: range within days time: mean over days; proposed_standard_name: air_temperature_range

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.etr(tasmax='tasmax', tasmin='tasmin', *, freq='MS', ds=None)

Calculate the extreme temperature range as the maximum of daily maximum temperature minus the minimum of daily minimum temperature. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice extreme_temperature_range().

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

etr (DataArray) – Intra-period extreme temperature range [degree_Celsius], with additional attributes: cell_methods: time: range; proposed_standard_name: air_temperature_range

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.fg(sfcWind='sfcWind', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• sfcWind (str or DataArray) – Surface wind speed. Default : ds.sfcWind. [Required units : m s-1]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

fg (DataArray) – Mean of daily mean wind strength (wind_speed) [meter second-1], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.fxx(wsgsmax='wsgsmax', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• wsgsmax (str or DataArray) – Maximum surface wind speed. Default : ds.wsgsmax. [Required units : m s-1]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

fxx (DataArray) – Maximum value of daily maximum wind gust strength (wind_speed_of_gust) [meter second-1], with additional attributes: cell_methods: time: maximum

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.gd4(tas='tas', *, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=>, threshold=4 degree_Celsius.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

gd4 (DataArray) – Growing degree days (sum of Tmean > 4 C) (integral_wrt_time_of_air_temperature_excess) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.gddgrowTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=>.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

gddgrow{threshold} (DataArray) – Annual Growing Degree Days (Tmean > {threshold}C) (integral_wrt_time_of_air_temperature_excess) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

ET-SCI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.hd17(tas='tas', *, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=<, threshold=17 degree_Celsius.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hd17 (DataArray) – Heating degree days (sum of Tmean < 17 C) (integral_wrt_time_of_air_temperature_excess) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.hddheatTT(tas='tas', *, threshold, freq='YS', ds=None)

Calculate the temperature sum above/below a threshold. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the sum is calculated for those data values that fulfill the condition after subtraction of the threshold value. If the sum is for values below the threshold the result is multiplied by -1.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_sum(). With injected parameters: op=<.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• threshold (quantity (string or DataArray, with units)) – air temperature Default : ds.tas. [Required units : degree_Celsius]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

hddheat{threshold} (DataArray) – Heating Degree Days (Tmean < {threshold}C) (integral_wrt_time_of_air_temperature_deficit) [degree_Celsius day], with additional attributes: cell_methods: time: sum over days

References

ET-SCI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.iter_indicators()

Iterate over the (name, indicator) pairs in the cf indicator module.

xclim.indicators.cf.maxdtr(tasmax='tasmax', tasmin='tasmin', *, freq='MS', ds=None)

Calculate the diurnal temperature range and reduce according to a statistic. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice diurnal_temperature_range(). With injected parameters: reducer=max.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

maxdtr (DataArray) – Maximum Diurnal Temperature Range [degree_Celsius], with additional attributes: cell_methods: time: range within days time: maximum over days; proposed_standard_name: air_temperature_range

References

SMHI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.pp(psl='psl', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• psl (str or DataArray) – Air pressure at sea level. Default : ds.psl. [Required units : Pa]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

pp (DataArray) – Mean of daily sea level pressure (air_pressure_at_sea_level) [hPa], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.rh(hurs='hurs', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• hurs (str or DataArray) – Relative humidity. Default : ds.hurs. [Required units : %]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rh (DataArray) – Mean of daily relative humidity (relative_humidity) [%], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.sd(snd='snd', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : m]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

sd (DataArray) – Mean of daily snow depth (surface_snow_thickness) [cm], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.sdii(pr='pr', *, freq='YS', constrain=None, ds=None)

Calculate a simple statistic of the data for which some condition is met. (realm: atmos)

First, the threshold is transformed to the same standard_name and units as the input data. Then the thresholding is performed as condition(data, threshold), i.e. if condition is <, data < threshold. Finally, the statistic is calculated for those data values that fulfill the condition.

This indicator will check for missing values according to the method “from_context”. Based on indice thresholded_statistics(). With injected parameters: op=>, threshold=1 mm day-1, reducer=mean.

Parameters:

• pr (str or DataArray) – Surface precipitation flux (all phases). Default : ds.pr. [Required units : kg m-2 s-1]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• constrain (Any) – Optionally allowed conditions. Default: None. Default : None.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

sdii (DataArray) – Average precipitation during Wet Days (SDII) (lwe_precipitation_rate) [mm day-1], with additional attributes: cell_methods: time: mean over days

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.ss(sund='sund', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=sum.

Parameters:

• sund (str or DataArray) – Duration of sunshine. Default : ds.sund. [Required units : s]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ss (DataArray) – Sunshine duration, sum (duration_of_sunshine) [hour]

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tg(tas='tas', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tg (DataArray) – Mean of daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmm(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmm (DataArray) – Mean daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmmax(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmmax (DataArray) – Maximum daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmmean(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmmean (DataArray) – Mean daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmmin(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmmin (DataArray) – Minimum daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmn(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmn (DataArray) – Minimum daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: minimum over days

References

clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tmx(tas='tas', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tas (str or DataArray) – Mean surface temperature. Default : ds.tas. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tmx (DataArray) – Maximum daily mean temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tn(tasmin='tasmin', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tn (DataArray) – Mean of daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnm(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnm (DataArray) – Mean daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnmax(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnmax (DataArray) – Maximum daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnmean(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnmean (DataArray) – Mean daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnmin(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnmin (DataArray) – Minimum daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: minimum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnn(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnn (DataArray) – Minimum daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: minimum over days

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tnx(tasmin='tasmin', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tnx (DataArray) – Maximum daily minimum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.tx(tasmax='tasmax', *, freq='MS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tx (DataArray) – Mean of daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txm(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txm (DataArray) – Mean daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txmax(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txmax (DataArray) – Maximum daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txmean(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=mean.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txmean (DataArray) – Mean daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: mean over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txmin(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txmin (DataArray) – Minimum daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: minimum over days

References

CLIPC clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txn(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=min.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txn (DataArray) – Minimum daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: minimum over days

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.txx(tasmax='tasmax', *, freq='YS', ds=None)

Calculate a simple statistic of the data. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice statistics(). With injected parameters: reducer=max.

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

txx (DataArray) – Maximum daily maximum temperature (air_temperature) [degree_Celsius], with additional attributes: cell_methods: time: maximum over days

References

ETCCDI clix-meta https://github.com/clix-meta/clix-meta

xclim.indicators.cf.vdtr(tasmax='tasmax', tasmin='tasmin', *, freq='MS', ds=None)

Calculate the average absolute day-to-day difference in diurnal temperature range. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice interday_diurnal_temperature_range().

Parameters:

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Default : MS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

vdtr (DataArray) – Mean day-to-day variation in Diurnal Temperature Range [degree_Celsius], with additional attributes: proposed_standard_name: air_temperature_difference

References

ECA&D clix-meta https://github.com/clix-meta/clix-meta

ICCLIM indices

The European Climate Assessment & Dataset project (ECAD) defines a set of 26 core climate indices. Those have been made accessible directly in xclim through their ECAD name for compatibility. However, the methods in this module are only wrappers around the corresponding methods of xclim.indices. Note that none of the checks performed by the xclim.utils.Indicator class (like with xclim.atmos indicators)are performed in this module.

xclim.indicators.icclim.BEDD(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None)

Biologically effective growing degree days. (realm: atmos)

Growing-degree days with a base of 10°C and an upper limit of 19°C and adjusted for latitudes between 40°N and 50°N for April to October (Northern Hemisphere; October to April in Southern Hemisphere). A temperature range adjustment also promotes small and large swings in daily temperature range. Used as a heat-summation metric in viticulture agroclimatology.

This indicator will check for missing values according to the method “from_context”. Based on indice biologically_effective_degree_days(). With injected parameters: lat=None, thresh_tasmin=10 degC, method=icclim, low_dtr=None, high_dtr=None, max_daily_degree_days=9 degC, start_date=04-01, end_date=10-01.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency (default: “YS”; For Southern Hemisphere, should be “AS-JUL”). Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

BEDD (DataArray) – Biologically effective growing degree days (Summation of min(max((Tmin + Tmax)/2 - 10°C, 0), 9°C), for days between 1 April and 30 September) [K days], with additional attributes: description: Heat-summation index for agroclimatic suitability estimation, developed specifically for viticulture. Computed with {method} formula (Summation of min((max((Tn + Tx)/2 - {thresh_tasmin}, 0) * k) + TR_adj, Dmax), where coefficient k is a latitude-based day-length for days between {start_date} and {end_date}), coefficient TR_adj is a modifier accounting for large temperature swings, and Dmax is the maximum possibleamount of degree days that can be gained within a day ({max_daily_degree_days}).

Notes

The tasmax ceiling of 19°C is assumed to be the max temperature beyond which no further gains from daily temperature occur. Indice originally published in Gladstones [1992].

Let \(TX_{i}\) and \(TN_{i}\) be the daily maximum and minimum temperature at day \(i\), \(lat\) the latitude of the point of interest, \(degdays_{max}\) the maximum amount of degrees that can be summed per day (typically, 9). Then the sum of daily biologically effective growing degree day (BEDD) units between 1 April and 31 October is:

\[BEDD_i = \sum_{i=\text{April 1}}^{\text{October 31}} min\left( \left( max\left( \frac{TX_i + TN_i)}{2} - 10, 0 \right) * k \right) + TR_{adj}, degdays_{max}\right)\]

\[\begin{split}TR_{adj} = f(TX_{i}, TN_{i}) = \begin{cases} 0.25(TX_{i} - TN_{i} - 13), & \text{if } (TX_{i} - TN_{i}) > 13 \\ 0, & \text{if } 10 < (TX_{i} - TN_{i}) < 13\\ 0.25(TX_{i} - TN_{i} - 10), & \text{if } (TX_{i} - TN_{i}) < 10 \\ \end{cases}\end{split}\]

\[k = f(lat) = 1 + \left(\frac{\left| lat \right|}{50} * 0.06, \text{if }40 < |lat| <50, \text{else } 0\right)\]

A second version of the BEDD (method=”icclim”) does not consider \(TR_{adj}\) and \(k\) and employs a different end date (30 September) [Project team ECA&D and KNMI, 2013]. The simplified formula is as follows:

\[BEDD_i = \sum_{i=\text{April 1}}^{\text{September 30}} min\left( max\left(\frac{TX_i + TN_i)}{2} - 10, 0\right), degdays_{max}\right)\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CD(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Cold and dry days (realm: atmos)

Number of days with temperature below a given percentile and precipitation below a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_and_dry_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Daily 25th percentile of temperature. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Daily 25th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

CD (DataArray) – Cold and dry days [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is below {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CDD(pr='pr', *, freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive dry days (realm: atmos)

The longest number of consecutive days where daily precipitation below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_dry_days(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

CDD (DataArray) – Maximum number of consecutive dry days (RR<1 mm) (number_of_days_with_lwe_thickness_of_precipitation_amount_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} maximum number of consecutive days with daily precipitation below {thresh}.

Notes

Let \(\mathbf{p}=p_0, p_1, \ldots, p_n\) be a daily precipitation series and \(thresh\) the threshold under which a day is considered dry. Then let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([p_i < thresh] \neq [p_{i+1} < thresh]\), that is, the days where the precipitation crosses the threshold. Then the maximum number of consecutive dry days is given by

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [p_{s_j} < thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CFD(tasmin='tasmin', *, freq='AS-JUL', resample_before_rl=True, ds=None)

Consecutive frost days (realm: atmos)

Maximum number of consecutive days where the daily minimum temperature is below 0°C

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_frost_days(). With injected parameters: thresh=0 degC.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

CFD (DataArray) – Maximum number of consecutive frost days (TN<0°C) (spell_length_of_days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum number of consecutive days where minimum daily temperature is below {thresh}.

Notes

Let \(\mathbf{t}=t_0, t_1, \ldots, t_n\) be a minimum daily temperature series and \(thresh\) the threshold below which a day is considered a frost day. Let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([t_i < thresh] \neq [t_{i+1} < thresh]\), that is, the days where the temperature crosses the threshold. Then the maximum number of consecutive frost days is given by

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [t_{s_j} < thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CSDI(tasmin='tasmin', tasmin_per='tasmin_per', *, freq='YS', resample_before_rl=True, bootstrap=False, op='<', ds=None)

Cold Spell Duration Index (CSDI) (realm: atmos)

Number of days part of a percentile-defined cold spell. A cold spell occurs when the daily minimum temperature is below a given percentile for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_spell_duration_index(). With injected parameters: window=6.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – nth percentile of daily minimum temperature with dayofyear coordinate. Default : ds.tasmin_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

CSDI (DataArray) – Cold-spell duration index (cold_spell_duration_index) [days], with additional attributes: description: {freq} number of days with at least {window} consecutive days where the daily minimum temperature is below the {tasmin_per_thresh}th percentile. A {tasmin_per_window} day(s) window, centred on each calendar day in the {tasmin_per_period} period, is used to compute the {tasmin_per_thresh}th percentile(s).

Notes

Let \(TN_i\) be the minimum daily temperature for the day of the year \(i\) and \(TN10_i\) the 10th percentile of the minimum daily temperature over the 1961-1990 period for day of the year \(i\), the cold spell duration index over period \(\phi\) is defined as:

\[\sum_{i \in \phi} \prod_{j=i}^{i+6} \left[ TN_j < TN10_j \right]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CSU(tasmax='tasmax', *, freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive warm days (realm: atmos)

Maximum number of consecutive days where the maximum daily temperature exceeds a certain threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_tx_days(). With injected parameters: thresh=25 degC.

Parameters:

• tasmax (str or DataArray) – Max daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

CSU (DataArray) – Maximum number of consecutive summer day (spell_length_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: maximum over days; description: {freq} longest spell of consecutive days with maximum daily temperature above {thresh}.

Notes

Let \(\mathbf{t}=t_0, t_1, \ldots, t_n\) be a daily maximum temperature series and \(thresh\) the threshold above which a day is considered a summer day. Let \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([t_i < thresh] \neq [t_{i+1} < thresh]\), that is, the days where the temperature crosses the threshold. Then the maximum number of consecutive tx_days (summer days) is given by:

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [t_{s_j} > thresh]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CW(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Cold and wet days (realm: atmos)

Number of days with temperature below a given percentile and precipitation above a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice cold_and_wet_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Daily 25th percentile of temperature. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Daily 75th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

CW (DataArray) – cold and wet days [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is below {tas_per_thresh}th percentile and precipitation is above {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.CWD(pr='pr', *, freq='YS', resample_before_rl=True, ds=None)

Maximum consecutive wet days (realm: atmos)

The longest number of consecutive days where daily precipitation is at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice maximum_consecutive_wet_days(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

CWD (DataArray) – Maximum number of consecutive wet days (RR≥1 mm) (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} maximum number of consecutive days with daily precipitation at or above {thresh}.

Notes

Let \(\mathbf{x}=x_0, x_1, \ldots, x_n\) be a daily precipitation series and \(\mathbf{s}\) be the sorted vector of indices \(i\) where \([p_i > thresh] \neq [p_{i+1} > thresh]\), that is, the days where the precipitation crosses the wet day threshold. Then the maximum number of consecutive wet days is given by:

\[\max(\mathbf{d}) \quad \mathrm{where} \quad d_j = (s_j - s_{j-1}) [x_{s_j} > 0^\circ C]\]

where \([P]\) is 1 if \(P\) is true, and 0 if false. Note that this formula does not handle sequences at the start and end of the series, but the numerical algorithm does.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.DTR(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Mean of daily temperature range (realm: atmos)

The average difference between the daily maximum and minimum temperatures.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range(). With injected parameters: op=mean.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

DTR (DataArray) – Mean of diurnal temperature range (air_temperature) [K], with additional attributes: cell_methods: time range within days time: mean over days; description: {freq} mean diurnal temperature range.

Notes

For a default calculation using op=’mean’ :

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the mean diurnal temperature range in period \(j\) is:

\[DTR_j = \frac{ \sum_{i=1}^I (TX_{ij} - TN_{ij}) }{I}\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.ETR(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Extreme temperature range (realm: atmos)

The maximum of the maximum temperature minus the minimum of the minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice extreme_temperature_range().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

ETR (DataArray) – Intra-period extreme temperature range (air_temperature) [K], with additional attributes: description: {freq} range between the maximum of daily maximum temperature and the minimum of dailyminimum temperature.

Notes

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the extreme temperature range in period \(j\) is:

\[ETR_j = max(TX_{ij}) - min(TN_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.FD(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Frost days (realm: atmos)

Number of days where the daily minimum temperature is below a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice frost_days(). With injected parameters: thresh=0 degC.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

FD (DataArray) – Frost days (TN<0°C) (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where the daily minimum temperature is below {thresh}.

Notes

Let \(TN_{ij}\) be the daily minimum temperature at day \(i\) of period \(j\) and :math`TT` the threshold. Then counted is the number of days where:

\[TN_{ij} < TT\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.GD4(tas='tas', *, freq='YS', ds=None, **indexer)

Growing degree days (realm: atmos)

The cumulative degree days for days when the average temperature is above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_degree_days(). With injected parameters: thresh=4 degC.

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

GD4 (DataArray) – Growing degree days (sum of TG>4°C) (integral_of_air_temperature_excess_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} growing degree days (mean temperature above {thresh}).

Notes

Let \(TG_{ij}\) be the mean daily temperature at day \(i\) of period \(j\). Then the growing degree days are:

\[GD4_j = \sum_{i=1}^I (TG_{ij}-{4} | TG_{ij} > {4}℃)\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.GSL(tas='tas', *, mid_date='07-01', freq='YS', op='>=', ds=None)

Growing season length (realm: atmos)

Number of days between the first occurrence of a series of days with a daily average temperature above a threshold and the first occurrence of a series of days with a daily average temperature below that same threshold, occurring after a given calendar date.

This indicator will check for missing values according to the method “from_context”. Based on indice growing_season_length(). With injected parameters: thresh=5 degC, window=6.

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• mid_date (date (string, MM-DD)) – Date of the year after which to look for the end of the season. Should have the format ‘%m-%d’. Default : 07-01.

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

GSL (DataArray) – Growing season length (growing_season_length) [days], with additional attributes: description: {freq} number of days between the first occurrence of at least {window} consecutive days with mean daily temperature over {thresh} and the first occurrence of at least {window} consecutive days with mean daily temperature below {thresh}, occurring after {mid_date}.

Notes

Let \(TG_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then counted is the number of days between the first occurrence of at least 6 consecutive days with:

\[TG_{ij} > 5 ℃\]

and the first occurrence after 1 July of at least 6 consecutive days with:

\[TG_{ij} < 5 ℃\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.HD17(tas='tas', *, freq='YS', ds=None, **indexer)

Heating degree days (realm: atmos)

The cumulative degree days for days when the mean daily temperature is below a given threshold and buildings must be heated.

This indicator will check for missing values according to the method “from_context”. Based on indice heating_degree_days(). With injected parameters: thresh=17 degC.

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

HD17 (DataArray) – Heating degree days (sum of17°C - TG) (integral_of_air_temperature_deficit_wrt_time) [K days], with additional attributes: cell_methods: time: sum over days; description: {freq} cumulative heating degree days (mean temperature below {thresh}).

Notes

This index intentionally differs from its ECA&D [Project team ECA&D and KNMI, 2013] equivalent: HD17. In HD17, values below zero are not clipped before the sum. The present definition should provide a better representation of the energy demand for heating buildings to the given threshold.

Let \(TG_{ij}\) be the daily mean temperature at day \(i\) of period \(j\). Then the heating degree days are:

\[HD17_j = \sum_{i=1}^{I} (17℃ - TG_{ij}) | TG_{ij} < 17℃)\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.HI(tas='tas', tasmax='tasmax', lat=None, *, freq='YS', ds=None)

Huglin Heliothermal Index. (realm: atmos)

Growing-degree days with a base of 10°C and adjusted for latitudes between 40°N and 50°N for April-September (Northern Hemisphere; October-March in Southern Hemisphere). Originally proposed in Huglin [1978]. Used as a heat-summation metric in viticulture agroclimatology.

This indicator will check for missing values according to the method “from_context”. Based on indice huglin_index(). With injected parameters: thresh=10 degC, method=icclim, start_date=04-01, end_date=11-01.

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• lat (str or DataArray, optional) – Latitude coordinate. If None, a CF-conformant “latitude” field must be available within the passed DataArray. [Required units : []]

• freq (offset alias (string)) – Resampling frequency (default: “YS”; For Southern Hemisphere, should be “AS-JUL”). Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

• HI (DataArray) – Huglin heliothermal index (Summation of ((Tmean + Tmax)/2 - 10°C) * Latitude-based day-length coefficient (k), for days between 1 April and 31 October)

• , with additional attributes (description: Heat-summation index for agroclimatic suitability estimation, developed specifically for viticulture, computed with {method} formula (Summation of ((Tn + Tx)/2 - {thresh}) * k), where coefficient k is a latitude-based day-length for days between {start_date} and {end_date}.)

Notes

Let \(TX_{i}\) and \(TG_{i}\) be the daily maximum and mean temperature at day \(i\) and \(T_{thresh}\) the base threshold needed for heat summation (typically, 10 degC). A day-length multiplication, \(k\), based on latitude, \(lat\), is also considered. Then the Huglin heliothermal index for dates between 1 April and 30 September is:

\[HI = \sum_{i=\text{April 1}}^{\text{September 30}} \left( \frac{TX_i + TG_i)}{2} - T_{thresh} \right) * k\]

For the smoothed method, the day-length multiplication factor, \(k\), is calculated as follows:

\[\begin{split}k = f(lat) = \begin{cases} 1, & \text{if } |lat| <= 40 \\ 1 + ((abs(lat) - 40) / 10) * 0.06, & \text{if } 40 < |lat| <= 50 \\ NaN, & \text{if } |lat| > 50 \\ \end{cases}\end{split}\]

For compatibility with ICCLIM, end_date should be set to 11-01, method should be set to icclim. The day-length multiplication factor, \(k\), is calculated as follows:

\[\begin{split}k = f(lat) = \begin{cases} 1.0, & \text{if } |lat| <= 40 \\ 1.02, & \text{if } 40 < |lat| <= 42 \\ 1.03, & \text{if } 42 < |lat| <= 44 \\ 1.04, & \text{if } 44 < |lat| <= 46 \\ 1.05, & \text{if } 46 < |lat| <= 48 \\ 1.06, & \text{if } 48 < |lat| <= 50 \\ NaN, & \text{if } |lat| > 50 \\ \end{cases}\end{split}\]

A more robust day-length calculation based on latitude, calendar, day-of-year, and obliquity is available with method=”jones”. See: xclim.indices.generic.day_lengths() or Hall and Jones [2010] for more information.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.ID(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Ice days (realm: atmos)

Number of days where the daily maximum temperature is below 0°C

This indicator will check for missing values according to the method “from_context”. Based on indice ice_days(). With injected parameters: thresh=0 degC.

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

ID (DataArray) – Ice days (TX<0°C) (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where the maximum daily temperature is below {thresh}.

Notes

Let \(TX_{ij}\) be the daily maximum temperature at day \(i\) of period \(j\), and :math`TT` the threshold. Then counted is the number of days where:

\[TX_{ij} < TT\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.PRCPTOT(pr='pr', *, freq='YS', ds=None, **indexer)

Total accumulated precipitation (solid and liquid) during wet days (realm: atmos)

Total accumulated precipitation on days with precipitation. A day is considered to have precipitation if the precipitation is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Total precipitation flux [mm d-1], [mm week-1], [mm month-1] or similar. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

PRCPTOT (DataArray) – Precipitation sum over wet days (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total precipitation over wet days, defined as days where precipitation exceeds {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R10mm(pr='pr', *, freq='YS', op='>=', ds=None, **indexer)

Number of wet days (realm: atmos)

The number of days with daily precipitation at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice wetdays(). With injected parameters: thresh=10 mm/day.

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R10mm (DataArray) – Heavy precipitation days (precipitation≥10 mm) (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with daily precipitation at or above {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R20mm(pr='pr', *, freq='YS', op='>=', ds=None, **indexer)

Number of wet days (realm: atmos)

The number of days with daily precipitation at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice wetdays(). With injected parameters: thresh=20 mm/day.

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R20mm (DataArray) – Very heavy precipitation days (precipitation≥20 mm) (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with daily precipitation at or above {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R75p(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Number of days with precipitation above a given percentile (realm: atmos)

Number of days in a period where precipitation is above a given percentile, calculated over a given period and a fixed threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice days_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 75th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R75p (DataArray) – Number of days with precipitation flux above the {pr_per_thresh}th percentile of {pr_per_period} (number_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation above the {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are counted.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R75pTOT(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Fraction of precipitation due to wet days with daily precipitation over a given percentile. (realm: atmos)

Percentage of the total precipitation over period occurring in days when the precipitation is above a threshold defining wet days and above a given percentile for that day.

This indicator will check for missing values according to the method “from_context”. Based on indice fraction_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 75th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R75pTOT (DataArray) – Precipitation fraction due to moderate wet days (>75th percentile), with additional attributes: description: {freq} fraction of total precipitation due to days with precipitation above {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are included in the total.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R95p(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Number of days with precipitation above a given percentile (realm: atmos)

Number of days in a period where precipitation is above a given percentile, calculated over a given period and a fixed threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice days_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 95th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R95p (DataArray) – Number of days with precipitation flux above the {pr_per_thresh}th percentile of {pr_per_period} (number_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation above the {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are counted.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R95pTOT(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Fraction of precipitation due to wet days with daily precipitation over a given percentile. (realm: atmos)

Percentage of the total precipitation over period occurring in days when the precipitation is above a threshold defining wet days and above a given percentile for that day.

This indicator will check for missing values according to the method “from_context”. Based on indice fraction_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 95th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R95pTOT (DataArray) – Precipitation fraction due to very wet days (>95th percentile), with additional attributes: description: {freq} fraction of total precipitation due to days with precipitation above {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are included in the total.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R99p(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Number of days with precipitation above a given percentile (realm: atmos)

Number of days in a period where precipitation is above a given percentile, calculated over a given period and a fixed threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice days_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 99th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R99p (DataArray) – Number of days with precipitation flux above the {pr_per_thresh}th percentile of {pr_per_period} (number_of_days_with_lwe_thickness_of_precipitation_amount_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with precipitation above the {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are counted.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.R99pTOT(pr='pr', pr_per='pr_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Fraction of precipitation due to wet days with daily precipitation over a given percentile. (realm: atmos)

Percentage of the total precipitation over period occurring in days when the precipitation is above a threshold defining wet days and above a given percentile for that day.

This indicator will check for missing values according to the method “from_context”. Based on indice fraction_over_precip_thresh(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• pr_per (str or DataArray) – 99th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

R99pTOT (DataArray) – Precipitation fraction due to extremely wet days (>99th percentile), with additional attributes: description: {freq} fraction of total precipitation due to days with precipitation above {pr_per_thresh}th percentile of {pr_per_period} period. Only days with at least {thresh} are included in the total.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.RR(pr='pr', *, thresh='0 degC', freq='YS', ds=None, **indexer)

Total accumulated precipitation (solid and liquid) (realm: atmos)

Total accumulated precipitation. If the average daily temperature is given, the phase parameter can be used to restrict the calculation to precipitation of only one phase (liquid or solid). Precipitation is considered solid if the average daily temperature is below 0°C (and vice versa).

This indicator will check for missing values according to the method “from_context”. Based on indice precip_accumulation(). With injected parameters: tas=None, phase=None.

Parameters:

• pr (str or DataArray) – Mean daily precipitation flux. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold of tas over which the precipication is assumed to be liquid rain. Default : 0 degC. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

RR (DataArray) – Precipitation sum (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum over days; description: {freq} total precipitation.

Notes

Let \(PR_i\) be the mean daily precipitation of day \(i\), then for a period \(j\) starting at day \(a\) and finishing on day \(b\):

\[PR_{ij} = \sum_{i=a}^{b} PR_i\]

If tas and phase are given, the corresponding phase precipitation is estimated before computing the accumulation, using one of snowfall_approximation or rain_approximation with the binary method.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.RR1(pr='pr', *, freq='YS', op='>=', ds=None, **indexer)

Number of wet days (realm: atmos)

The number of days with daily precipitation at or above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice wetdays(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

RR1 (DataArray) – Wet days (RR≥1 mm) (number_of_days_with_lwe_thickness_of_precipitation_amount_at_or_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with daily precipitation at or above {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.RX1day(pr='pr', *, freq='YS', ds=None, **indexer)

Maximum 1-day total precipitation (realm: atmos)

Maximum total daily precipitation for a given period.

This indicator will check for missing values according to the method “from_context”. Based on indice max_1day_precipitation_amount().

Parameters:

• pr (str or DataArray) – Daily precipitation values. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

RX1day (DataArray) – Highest 1-day precipitation amount (lwe_thickness_of_precipitation_amount) [mm/day], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum 1-day total precipitation

Notes

Let \(PR_i\) be the mean daily precipitation of day i, then for a period j:

\[PRx_{ij} = max(PR_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.RX5day(pr='pr', *, freq='YS', ds=None)

maximum n-day total precipitation (realm: atmos)

Maximum of the moving sum of daily precipitation for a given period.

This indicator will check for missing values according to the method “from_context”. Based on indice max_n_day_precipitation_amount(). With injected parameters: window=5.

Parameters:

• pr (str or DataArray) – Daily precipitation values. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

RX5day (DataArray) – Highest 5-day precipitation amount (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum {window}-day total precipitation amount.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SD(snd='snd', *, freq='YS', ds=None, **indexer)

Mean snow depth (realm: atmos)

Mean of daily snow depth.

This indicator will check for missing values according to the method “from_context”. Based on indice snow_depth().

Parameters:

• snd (str or DataArray) – Mean daily snow depth. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SD (DataArray) – Mean of daily snow depth (surface_snow_thickness) [cm], with additional attributes: cell_methods: time: mean over days; description: The {freq} mean of daily mean snow depth.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SD1(snd='snd', *, freq='AS-JUL', op='>=', ds=None, **indexer)

Snow cover duration (depth) (realm: atmos)

Number of days when the snow depth is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_length(). With injected parameters: thresh=1 cm.

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SD1 (DataArray) – Snow days (SD≥1 cm) [days], with additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SD50cm(snd='snd', *, freq='AS-JUL', op='>=', ds=None, **indexer)

Snow cover duration (depth) (realm: atmos)

Number of days when the snow depth is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_length(). With injected parameters: thresh=50 cm.

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SD50cm (DataArray) – Snow days (SD≥50 cm) [days], with additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SD5cm(snd='snd', *, freq='AS-JUL', op='>=', ds=None, **indexer)

Snow cover duration (depth) (realm: atmos)

Number of days when the snow depth is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice snd_season_length(). With injected parameters: thresh=5 cm.

Parameters:

• snd (str or DataArray) – Surface snow thickness. Default : ds.snd. [Required units : [length]]

• freq (offset alias (string)) – Resampling frequency. Default : AS-JUL.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SD5cm (DataArray) – Snow days (SD≥5 cm) [days], with additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SDII(pr='pr', *, freq='YS', op='>=', ds=None, **indexer)

Simple Daily Intensity Index (realm: atmos)

Average precipitation for days with daily precipitation above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_pr_intensity(). With injected parameters: thresh=1 mm/day.

Parameters:

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>=”. Default : >=.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SDII (DataArray) – Average precipitation during days with daily precipitation over {thresh} (Simple Daily Intensity Index: SDII) (lwe_thickness_of_precipitation_amount) [mm d-1], with additional attributes: description: {freq} Simple Daily Intensity Index (SDII) or {freq} average precipitation for days with daily precipitation over {thresh}.

Notes

Let \(\mathbf{p} = p_0, p_1, \ldots, p_n\) be the daily precipitation and \(thresh\) be the precipitation threshold defining wet days. Then the daily precipitation intensity is defined as:

\[\frac{\sum_{i=0}^n p_i [p_i \leq thresh]}{\sum_{i=0}^n [p_i \leq thresh]}\]

where \([P]\) is 1 if \(P\) is true, and 0 if false.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.SU(tasmax='tasmax', *, freq='YS', op='>', ds=None, **indexer)

Number of days with maximum temperature above a given threshold (realm: atmos)

The number of days with maximum temperature above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_days_above(). With injected parameters: thresh=25 degC.

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

SU (DataArray) – Summer days (TX>25°C) (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where daily maximum temperature exceeds {thresh}.

Notes

Let \(TX_{ij}\) be the maximum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TX_{ij} > Threshold [℃]\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TG(tas='tas', *, freq='YS', ds=None, **indexer)

Mean temperature (realm: atmos)

Mean of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TG (DataArray) – Mean daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily mean temperature.

Notes

Let \(TN_i\) be the mean daily temperature of day \(i\), then for a period \(p\) starting at day \(a\) and finishing on day \(b\):

\[TG_p = \frac{\sum_{i=a}^{b} TN_i}{b - a + 1}\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TG10p(tas='tas', tas_per='tas_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with mean temperature below the 10th percentile (realm: atmos)

Number of days with mean temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tg10p().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tas_per (str or DataArray) – 10th percentile of daily mean temperature. Default : ds.tas_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TG10p (DataArray) – Days with TG<10th percentile of daily mean temperature (cold days) (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with mean temperature below the 10th percentile. A {tas_per_window} day(s) window, centered on each calendar day in the {tas_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TG90p(tas='tas', tas_per='tas_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with mean temperature above the 90th percentile (realm: atmos)

Number of days with mean temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tg90p().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• tas_per (str or DataArray) – 90th percentile of daily mean temperature. Default : ds.tas_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TG90p (DataArray) – Days with TG>90th percentile of daily mean temperature (warm days) (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with mean temperature above the 90th percentile. A {tas_per_window} day(s) window, centered on each calendar day in the {tas_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TGn(tas='tas', *, freq='YS', ds=None, **indexer)

Minimum of mean temperature (realm: atmos)

Minimum of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_min().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TGn (DataArray) – Minimum daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily mean temperature.

Notes

Let \(TG_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then the minimum daily mean temperature for period \(j\) is:

\[TGn_j = min(TG_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TGx(tas='tas', *, freq='YS', ds=None, **indexer)

Maximum of mean temperature (realm: atmos)

Maximum of daily mean temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_max().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TGx (DataArray) – Maximum daily mean temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily mean temperature.

Notes

Let \(TN_{ij}\) be the mean temperature at day \(i\) of period \(j\). Then the maximum daily mean temperature for period \(j\) is:

\[TNx_j = max(TN_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TN(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Mean of minimum temperature (realm: atmos)

Mean of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_mean().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TN (DataArray) – Mean daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then mean values in period \(j\) are given by:

\[TN_{ij} = \frac{ \sum_{i=1}^{I} TN_{ij} }{I}\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TN10p(tasmin='tasmin', tasmin_per='tasmin_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with minimum temperature below the 10th percentile (realm: atmos)

Number of days with minimum temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tn10p().

Parameters:

• tasmin (str or DataArray) – Mean daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – 10th percentile of daily minimum temperature. Default : ds.tasmin_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TN10p (DataArray) – Days with TN<10th percentile of daily minimum temperature (cold nights) (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with minimum temperature below the 10th percentile. A {tasmin_per_window} day(s) window, centered on each calendar day in the {tasmin_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TN90p(tasmin='tasmin', tasmin_per='tasmin_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with minimum temperature above the 90th percentile (realm: atmos)

Number of days with minimum temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tn90p().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmin_per (str or DataArray) – 90th percentile of daily minimum temperature. Default : ds.tasmin_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TN90p (DataArray) – Days with TN>90th percentile of daily minimum temperature (warm nights) (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with minimum temperature above the 90th percentile. A {tasmin_per_window} day(s) window, centered on each calendar day in the {tasmin_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TNn(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Minimum temperature (realm: atmos)

Minimum of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_min().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TNn (DataArray) – Minimum daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then the minimum daily minimum temperature for period \(j\) is:

\[TNn_j = min(TN_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TNx(tasmin='tasmin', *, freq='YS', ds=None, **indexer)

Maximum of minimum temperature (realm: atmos)

Maximum of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_max().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TNx (DataArray) – Maximum daily minimum temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily minimum temperature.

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then the maximum daily minimum temperature for period \(j\) is:

\[TNx_j = max(TN_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TR(tasmin='tasmin', *, freq='YS', op='>', ds=None, **indexer)

Tropical nights (realm: atmos)

Number of days where minimum temperature is above a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_days_above(). With injected parameters: thresh=20 degC.

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TR (DataArray) – Tropical nights (TN>20°C) (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of Tropical Nights, defined as days with minimum daily temperature above {thresh}.

Notes

Let \(TN_{ij}\) be the minimum daily temperature at day \(i\) of period \(j\). Then counted is the number of days where:

\[TN_{ij} > Threshold [℃]\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TX(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Mean of maximum temperature (realm: atmos)

Mean of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_mean().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TX (DataArray) – Mean daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean over days; description: {freq} mean of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then mean values in period \(j\) are given by:

\[TX_{ij} = \frac{ \sum_{i=1}^{I} TX_{ij} }{I}\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TX10p(tasmax='tasmax', tasmax_per='tasmax_per', *, freq='YS', bootstrap=False, op='<', ds=None, **indexer)

Days with maximum temperature below the 10th percentile (realm: atmos)

Number of days with maximum temperature below the 10th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tx10p().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – 10th percentile of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘<’, ‘lt’, ‘le’, ‘<=’}) – Comparison operation. Default: “<”. Default : <.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TX10p (DataArray) – Days with TX<10th percentile of daily maximum temperature (cold day-times) (days_with_air_temperature_below_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with maximum temperature below the 10th percentile. A {tasmax_per_window} day(s) window, centered on each calendar day in the {tasmax_per_period} period, is used to compute the 10th percentile.

Notes

The 10th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TX90p(tasmax='tasmax', tasmax_per='tasmax_per', *, freq='YS', bootstrap=False, op='>', ds=None, **indexer)

Days with maximum temperature above the 90th percentile (realm: atmos)

Number of days with maximum temperature above the 90th percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice tx90p().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – 90th percentile of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TX90p (DataArray) – Days with TX>90th percentile of daily maximum temperature (warm day-times) (days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with maximum temperature above the 90th percentile. A {tasmax_per_window} day(s) window, centered on each calendar day in the {tasmax_per_period} period, is used to compute the 90th percentile.

Notes

The 90th percentile should be computed for a 5-day window centered on each calendar day for a reference period.

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TXn(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Minimum of maximum temperature (realm: atmos)

Minimum of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_min().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TXn (DataArray) – Minimum daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: minimum over days; description: {freq} minimum of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then the minimum daily maximum temperature for period \(j\) is:

\[TXn_j = min(TX_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.TXx(tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Maximum temperature (realm: atmos)

Maximum of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_max().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

TXx (DataArray) – Maximum daily maximum temperature (air_temperature) [K], with additional attributes: cell_methods: time: maximum over days; description: {freq} maximum of daily maximum temperature.

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then the maximum daily maximum temperature for period \(j\) is:

\[TXx_j = max(TX_{ij})\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.WD(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Warm and dry days (realm: atmos)

Number of days with temperature above a given percentile and precipitation below a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_and_dry_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Daily 75th percentile of temperature. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Daily 25th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

WD (DataArray) – Warm and dry days [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is above {tas_per_thresh}th percentile and precipitation is below {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.WSDI(tasmax='tasmax', tasmax_per='tasmax_per', *, freq='YS', resample_before_rl=True, bootstrap=False, op='>', ds=None)

Warm spell duration index (realm: atmos)

Number of days part of a percentile-defined warm spell. A warm spell occurs when the maximum daily temperature is above a given percentile for a given number of consecutive days.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_spell_duration_index(). With injected parameters: window=6.

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• tasmax_per (str or DataArray) – percentile(s) of daily maximum temperature. Default : ds.tasmax_per. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• bootstrap (boolean) – Flag to run bootstrapping of percentiles. Used by percentile_bootstrap decorator. Bootstrapping is only useful when the percentiles are computed on a part of the studied sample. This period, common to percentiles and the sample must be bootstrapped to avoid inhomogeneities with the rest of the time series. Keep bootstrap to False when there is no common period, it would give wrong results plus, bootstrapping is computationally expensive. Default : False.

• op ({‘>’, ‘gt’, ‘ge’, ‘>=’}) – Comparison operation. Default: “>”. Default : >.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

WSDI (DataArray) – Warm-spell duration index (number_of_days_with_air_temperature_above_threshold) [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days with at least {window} consecutive days where the maximum daily temperature is above the {tasmax_per_thresh}th percentile(s). A {tasmax_per_window} day(s) window, centred on each calendar day in the {tasmax_per_period} period, is used to compute the {tasmax_per_thresh}th percentile(s).

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.WW(tas='tas', pr='pr', tas_per='tas_per', pr_per='pr_per', *, freq='YS', ds=None, **indexer)

Warm and wet days (realm: atmos)

Number of days with temperature above a given percentile and precipitation above a given percentile.

This indicator will check for missing values according to the method “from_context”. Based on indice warm_and_wet_days().

Parameters:

• tas (str or DataArray) – Mean daily temperature values Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]

• tas_per (str or DataArray) – Daily 75th percentile of temperature. Default : ds.tas_per. [Required units : [temperature]]

• pr_per (str or DataArray) – Daily 75th percentile of wet day precipitation flux. Default : ds.pr_per. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

WW (DataArray) – Warm and wet days [days], with additional attributes: cell_methods: time: sum over days; description: {freq} number of days where temperature is above {tas_per_thresh}th percentile and precipitation is above {pr_per_thresh}th percentile.

Notes

Bootstrapping is not available for quartiles because it would make no significant difference to bootstrap percentiles so far from the extremes.

Formula to be written (Beniston [2009])

References

European Climate Assessment & Dataset https://www.ecad.eu/

xclim.indicators.icclim.iter_indicators()

Iterate over the (name, indicator) pairs in the icclim indicator module.

xclim.indicators.icclim.vDTR(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None, **indexer)

Variability of daily temperature range (realm: atmos)

The average day-to-day variation in daily temperature range.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range_variability().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

• indexer – Indexing parameters to compute the indicator on a temporal subset of the data. It accepts the same arguments as xclim.indices.generic.select_time(). Default : None.

Returns:

vDTR (DataArray) – Mean absolute day-to-day difference in DTR (air_temperature) [K], with additional attributes: cell_methods: time range within days time: difference over days time: mean over days; description: {freq} mean diurnal temperature range variability, defined as the average day-to-day variation in daily temperature range for the given time period.

Notes

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then calculated is the absolute day-to-day differences in period \(j\) is:

\[vDTR_j = \frac{ \sum_{i=2}^{I} |(TX_{ij}-TN_{ij})-(TX_{i-1,j}-TN_{i-1,j})| }{I}\]

References

European Climate Assessment & Dataset https://www.ecad.eu/

ANUCLIM indices

The ANUCLIM (v6.1) software package BIOCLIM sub-module produces a set of bioclimatic parameters derived values of temperature and precipitation. The methods in this module are wrappers around a subset of corresponding methods of xclim.indices.

Furthermore, according to the ANUCLIM user-guide [Xu and Hutchinson, 2010], input values should be at a weekly or monthly frequency. However, the implementation here expands these definitions and can calculate the result with daily input data.

xclim.indicators.anuclim.P10_MeanTempWarmestQuarter(tas='tas', *, freq='YS', ds=None)

Mean temperature of warmest/coldest quarter. (realm: atmos)

The warmest (or coldest) quarter of the year is determined, and the mean temperature of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”), quarters are defined as 13-week periods, otherwise as three (3) months.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean_warmcold_quarter(). With injected parameters: op=warmest.

Parameters:

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P10_MeanTempWarmestQuarter (DataArray) – (air_temperature) [K], with additional attributes: cell_methods: time: mean

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P11_MeanTempColdestQuarter(tas='tas', *, freq='YS', ds=None)

Mean temperature of warmest/coldest quarter. (realm: atmos)

The warmest (or coldest) quarter of the year is determined, and the mean temperature of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”), quarters are defined as 13-week periods, otherwise as three (3) months.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean_warmcold_quarter(). With injected parameters: op=coldest.

Parameters:

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P11_MeanTempColdestQuarter (DataArray) – (air_temperature) [K], with additional attributes: cell_methods: time: mean

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P12_AnnualPrecip(pr='pr', *, thresh='0 mm/d', freq='YS', ds=None)

Accumulated total precipitation. (realm: atmos)

The total accumulated precipitation from days where precipitation exceeds a given amount. A threshold is provided in order to allow the option of reducing the impact of days with trace precipitation amounts on period totals.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot().

Parameters:

• pr (str or DataArray) – Total precipitation flux [mm d-1], [mm week-1], [mm month-1] or similar. Default : ds.pr. [Required units : [precipitation]]

• thresh (quantity (string or DataArray, with units)) – Threshold over which precipitation starts being cumulated. Default : 0 mm/d. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P12_AnnualPrecip (DataArray) – Annual Precipitation (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P13_PrecipWettestPeriod(pr='pr', *, freq='YS', ds=None)

Precipitation of the wettest/driest day, week, or month, depending on the time step. (realm: atmos)

The wettest (or driest) period is determined, and the total precipitation of this period is calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_wetdry_period(). With injected parameters: op=wettest.

Parameters:

• pr (str or DataArray) – Total precipitation flux [mm d-1], [mm week-1], [mm month-1] or similar. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P13_PrecipWettestPeriod (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P14_PrecipDriestPeriod(pr='pr', *, freq='YS', ds=None)

Precipitation of the wettest/driest day, week, or month, depending on the time step. (realm: atmos)

The wettest (or driest) period is determined, and the total precipitation of this period is calculated.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_wetdry_period(). With injected parameters: op=driest.

Parameters:

• pr (str or DataArray) – Total precipitation flux [mm d-1], [mm week-1], [mm month-1] or similar. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P14_PrecipDriestPeriod (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P15_PrecipSeasonality(pr='pr', *, freq='YS', ds=None)

Precipitation Seasonality (C of V). (realm: atmos)

The annual precipitation Coefficient of Variation (C of V) expressed in percent. Calculated as the standard deviation of precipitation values for a given year expressed as a percentage of the mean of those values.

This indicator will check for missing values according to the method “from_context”. Based on indice precip_seasonality().

Parameters:

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Units need to be defined as a rate (e.g. mm d-1, mm week-1). Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P15_PrecipSeasonality (DataArray) – , with additional attributes: cell_methods: time: standard_deviation; description: “The standard deviation of the precipitation estimates expressed as a percentage of the mean of those estimates.”

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

If input units are in mm s-1 (or equivalent), values are converted to mm/day to avoid potentially small denominator values.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P16_PrecipWettestQuarter(pr='pr', *, freq='YS', ds=None)

Total precipitation of wettest/driest quarter. (realm: atmos)

The wettest (or driest) quarter of the year is determined, and the total precipitation of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”) quarters are defined as 13-week periods, otherwise are three (3) months.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_wetdry_quarter(). With injected parameters: op=wettest.

Parameters:

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P16_PrecipWettestQuarter (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P17_PrecipDriestQuarter(pr='pr', *, freq='YS', ds=None)

Total precipitation of wettest/driest quarter. (realm: atmos)

The wettest (or driest) quarter of the year is determined, and the total precipitation of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”) quarters are defined as 13-week periods, otherwise are three (3) months.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_wetdry_quarter(). With injected parameters: op=driest.

Parameters:

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P17_PrecipDriestQuarter (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P18_PrecipWarmestQuarter(pr='pr', tas='tas', *, freq='YS', ds=None)

Total precipitation of warmest/coldest quarter. (realm: atmos)

The warmest (or coldest) quarter of the year is determined, and the total precipitation of this period is calculated. If the input data frequency is daily (“D) or weekly (“W”), quarters are defined as 13-week periods, otherwise are 3 months.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_warmcold_quarter(). With injected parameters: op=warmest.

Parameters:

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P18_PrecipWarmestQuarter (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P19_PrecipColdestQuarter(pr='pr', tas='tas', *, freq='YS', ds=None)

Total precipitation of warmest/coldest quarter. (realm: atmos)

The warmest (or coldest) quarter of the year is determined, and the total precipitation of this period is calculated. If the input data frequency is daily (“D) or weekly (“W”), quarters are defined as 13-week periods, otherwise are 3 months.

This indicator will check for missing values according to the method “from_context”. Based on indice prcptot_warmcold_quarter(). With injected parameters: op=coldest.

Parameters:

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P19_PrecipColdestQuarter (DataArray) – (lwe_thickness_of_precipitation_amount) [mm], with additional attributes: cell_methods: time: sum

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P1_AnnMeanTemp(tas='tas', *, freq='YS', ds=None)

Mean of daily average temperature. (realm: atmos)

Resample the original daily mean temperature series by taking the mean over each period.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean().

Parameters:

• tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P1_AnnMeanTemp (DataArray) – Annual Mean Temperature (air_temperature) [K], with additional attributes: cell_methods: time: mean

Notes

Let \(TN_i\) be the mean daily temperature of day \(i\), then for a period \(p\) starting at day \(a\) and finishing on day \(b\):

\[TG_p = \frac{\sum_{i=a}^{b} TN_i}{b - a + 1}\]

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P2_MeanDiurnalRange(tasmin='tasmin', tasmax='tasmax', *, freq='YS', op='mean', ds=None)

Statistics of daily temperature range. (realm: atmos)

The mean difference between the daily maximum temperature and the daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice daily_temperature_range().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• op ({‘max’, ‘std’, ‘min’, ‘mean’}) – Reduce operation. Can either be a DataArray method or a function that can be applied to a DataArray. Default : mean.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P2_MeanDiurnalRange (DataArray) – Mean Diurnal Range [K], with additional attributes: cell_methods: time: range

Notes

For a default calculation using op=’mean’ :

Let \(TX_{ij}\) and \(TN_{ij}\) be the daily maximum and minimum temperature at day \(i\) of period \(j\). Then the mean diurnal temperature range in period \(j\) is:

\[DTR_j = \frac{ \sum_{i=1}^I (TX_{ij} - TN_{ij}) }{I}\]

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P3_Isothermality(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None)

Isothermality. (realm: atmos)

The mean diurnal temperature range divided by the annual temperature range.

This indicator will check for missing values according to the method “from_context”. Based on indice isothermality().

Parameters:

• tasmin (str or DataArray) – Average daily minimum temperature at daily, weekly, or monthly frequency. Default : ds.tasmin. [Required units : [temperature]]

• tasmax (str or DataArray) – Average daily maximum temperature at daily, weekly, or monthly frequency. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P3_Isothermality (DataArray) – , with additional attributes: cell_methods: time: range; description: The mean diurnal range (P2) divided by the Annual Temperature Range (P7).

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the output with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P4_TempSeasonality(tas='tas', *, freq='YS', ds=None)

Temperature seasonality (coefficient of variation). (realm: atmos)

The annual temperature coefficient of variation expressed in percent. Calculated as the standard deviation of temperature values for a given year expressed as a percentage of the mean of those temperatures.

This indicator will check for missing values according to the method “from_context”. Based on indice temperature_seasonality().

Parameters:

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P4_TempSeasonality (DataArray) – , with additional attributes: cell_methods: time: standard_deviation; description: “The standard deviation of the mean temperatures expressed as a percentage of the mean of those temperatures. For this calculation, the mean in degrees Kelvin is used. This avoids the possibility of having to divide by zero, but it does mean that the values are usually quite small.”

Notes

For this calculation, the mean in degrees Kelvin is used. This avoids the possibility of having to divide by zero, but it does mean that the values are usually quite small.

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P5_MaxTempWarmestPeriod(tasmax='tasmax', *, freq='YS', ds=None)

Highest max temperature. (realm: atmos)

The maximum value of daily maximum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tx_max().

Parameters:

• tasmax (str or DataArray) – Maximum daily temperature. Default : ds.tasmax. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P5_MaxTempWarmestPeriod (DataArray) – Max Temperature of Warmest Period (air_temperature) [K], with additional attributes: description: The highest maximum temperature in all periods of the year.; cell_methods: time: maximum

Notes

Let \(TX_{ij}\) be the maximum temperature at day \(i\) of period \(j\). Then the maximum daily maximum temperature for period \(j\) is:

\[TXx_j = max(TX_{ij})\]

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P6_MinTempColdestPeriod(tasmin='tasmin', *, freq='YS', ds=None)

Lowest minimum temperature. (realm: atmos)

Minimum of daily minimum temperature.

This indicator will check for missing values according to the method “from_context”. Based on indice tn_min().

Parameters:

• tasmin (str or DataArray) – Minimum daily temperature. Default : ds.tasmin. [Required units : [temperature]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P6_MinTempColdestPeriod (DataArray) – Min Temperature of Coldest Period (air_temperature) [K], with additional attributes: description: The lowest minimum temperature in all periods of the year.; cell_methods: time: minimum

Notes

Let \(TN_{ij}\) be the minimum temperature at day \(i\) of period \(j\). Then the minimum daily minimum temperature for period \(j\) is:

\[TNn_j = min(TN_{ij})\]

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P7_TempAnnualRange(tasmin='tasmin', tasmax='tasmax', *, freq='YS', ds=None)

Calculate the extreme temperature range as the maximum of daily maximum temperature minus the minimum of daily minimum temperature. (realm: atmos)

This indicator will check for missing values according to the method “from_context”. Based on indice extreme_temperature_range().

Parameters:

• tasmin (str or DataArray) – Minimum surface temperature. Default : ds.tasmin. [Required units : K]

• tasmax (str or DataArray) – Maximum surface temperature. Default : ds.tasmax. [Required units : K]

• freq (offset alias (string)) – Resampling frequency defining the periods as defined in https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#resampling. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P7_TempAnnualRange (DataArray) – Temperature Annual Range [K], with additional attributes: cell_methods: time: range

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P8_MeanTempWettestQuarter(tas='tas', pr='pr', *, freq='YS', ds=None)

Mean temperature of wettest/driest quarter. (realm: atmos)

The wettest (or driest) quarter of the year is determined, and the mean temperature of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”), quarters are defined as 13-week periods, otherwise are 3 months.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean_wetdry_quarter(). With injected parameters: op=wettest.

Parameters:

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P8_MeanTempWettestQuarter (DataArray) – (air_temperature) [K], with additional attributes: cell_methods: time: mean

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.P9_MeanTempDriestQuarter(tas='tas', pr='pr', *, freq='YS', ds=None)

Mean temperature of wettest/driest quarter. (realm: atmos)

The wettest (or driest) quarter of the year is determined, and the mean temperature of this period is calculated. If the input data frequency is daily (“D”) or weekly (“W”), quarters are defined as 13-week periods, otherwise are 3 months.

This indicator will check for missing values according to the method “from_context”. Based on indice tg_mean_wetdry_quarter(). With injected parameters: op=driest.

Parameters:

• tas (str or DataArray) – Mean temperature at daily, weekly, or monthly frequency. Default : ds.tas. [Required units : [temperature]]

• pr (str or DataArray) – Total precipitation rate at daily, weekly, or monthly frequency. Default : ds.pr. [Required units : [precipitation]]

• freq (offset alias (string)) – Resampling frequency. Restricted to frequencies equivalent to one of [‘A’] Default : YS.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

P9_MeanTempDriestQuarter (DataArray) – (air_temperature) [K], with additional attributes: cell_methods: time: mean

Notes

According to the ANUCLIM user-guide (Xu and Hutchinson [2010], ch. 6), input values should be at a weekly (or monthly) frequency. However, the xclim.indices implementation here will calculate the result with input data with daily frequency as well. As such weekly or monthly input values, if desired, should be calculated prior to calling the function.

References

ANUCLIM https://fennerschool.anu.edu.au/files/anuclim61.pdf (ch. 6)

xclim.indicators.anuclim.iter_indicators()

Iterate over the (name, indicator) pairs in the anuclim indicator module.

Indices

See: Climate Indices

Health Checks

See: Health Checks

Translation Tools

See: Internationalization

Ensembles Module

Ensemble tools

This submodule defines some useful methods for dealing with ensembles of climate simulations. In xclim, an “ensemble” is a Dataset or a DataArray where multiple climate realizations or models are concatenated along the realization dimension.

xclim.ensembles.create_ensemble(datasets, multifile=False, resample_freq=None, calendar=None, realizations=None, cal_kwargs=None, mf_flag='UNSET', **xr_kwargs)

Create an xarray dataset of an ensemble of climate simulation from a list of netcdf files.

Input data is concatenated along a newly created data dimension (‘realization’). Returns an xarray dataset object containing input data from the list of netcdf files concatenated along a new dimension (name:’realization’). In the case where input files have unequal time dimensions, the output ensemble Dataset is created for maximum time-step interval of all input files. Before concatenation, datasets not covering the entire time span have their data padded with NaN values. Dataset and variable attributes of the first dataset are copied to the resulting dataset.

Parameters:

• datasets (list or dict or string) – List of netcdf file paths or xarray Dataset/DataArray objects . If multifile is True, ncfiles should be a list of lists where each sublist contains input .nc files of an xarray multifile Dataset. If DataArray objects are passed, they should have a name in order to be transformed into Datasets. A dictionary can be passed instead of a list, in which case the keys are used as coordinates along the new realization axis. If a string is passed, it is assumed to be a glob pattern for finding datasets.

• multifile (bool) – If True, climate simulations are treated as xarray multifile Datasets before concatenation. Only applicable when “datasets” is sequence of list of file paths. Default: False.

• resample_freq (Optional[str]) – If the members of the ensemble have the same frequency but not the same offset, they cannot be properly aligned. If resample_freq is set, the time coordinate of each member will be modified to fit this frequency.

• calendar (str, optional) – The calendar of the time coordinate of the ensemble. By default, the smallest common calendar is chosen. For example, a mixed input of “noleap” and “360_day” will default to “noleap”. ‘default’ is the standard calendar using np.datetime64 objects (xarray’s “standard” with use_cftime=False).

• realizations (sequence, optional) – The coordinate values for the new realization axis. If None (default), the new axis has a simple integer coordinate. This argument shouldn’t be used if datasets is a glob pattern as the dataset order is random.

• cal_kwargs (dict, optional) – Additional arguments to pass to py:func:xclim.core.calendar.convert_calendar. For conversions involving ‘360_day’, the align_on=’date’ option is used by default.

• **xr_kwargs – Any keyword arguments to be given to xr.open_dataset when opening the files (or to xr.open_mfdataset if multifile is True)

Return type:

Dataset

Returns:

xr.Dataset – Dataset containing concatenated data from all input files.

Notes

Input netcdf files require equal spatial dimension size (e.g. lon, lat dimensions). If input data contains multiple cftime calendar types they must be at monthly or coarser frequency.

Examples

from pathlib import Path
from xclim.ensembles import create_ensemble

ens = create_ensemble(temperature_datasets)

# Using multifile datasets, through glob patterns.
# Simulation 1 is a list of .nc files (e.g. separated by time):
datasets = list(Path("/dir").glob("*.nc"))

# Simulation 2 is also a list of .nc files:
datasets.extend(Path("/dir2").glob("*.nc"))
ens = create_ensemble(datasets, multifile=True)

xclim.ensembles.ensemble_mean_std_max_min(ens, weights=None)

Calculate ensemble statistics between a results from an ensemble of climate simulations.

Returns an xarray Dataset containing ensemble mean, standard-deviation, minimum and maximum for input climate simulations.

Parameters:

• ens (xr.Dataset) – Ensemble dataset (see xclim.ensembles.create_ensemble).

• weights (xr.DataArray) – Weights to apply along the ‘realization’ dimension. This array cannot contain missing values.

Return type:

Dataset

Returns:

xr.Dataset – Dataset with data variables of ensemble statistics.

Examples

from xclim.ensembles import create_ensemble, ensemble_mean_std_max_min

# Create the ensemble dataset:
ens = create_ensemble(temperature_datasets)

# Calculate ensemble statistics:
ens_mean_std = ensemble_mean_std_max_min(ens)

xclim.ensembles.ensemble_percentiles(ens, values=None, keep_chunk_size=None, weights=None, split=True)

Calculate ensemble statistics between a results from an ensemble of climate simulations.

Returns a Dataset containing ensemble percentiles for input climate simulations.

Parameters:

• ens (xr.Dataset or xr.DataArray) – Ensemble dataset or dataarray (see xclim.ensembles.create_ensemble).

• values (Sequence[int], optional) – Percentile values to calculate. Default: (10, 50, 90).

• keep_chunk_size (bool, optional) – For ensembles using dask arrays, all chunks along the ‘realization’ axis are merged. If True, the dataset is rechunked along the dimension with the largest chunks, so that the chunks keep the same size (approximately). If False, no shrinking is performed, resulting in much larger chunks. If not defined, the function decides which is best.

• weights (xr.DataArray) – Weights to apply along the ‘realization’ dimension. This array cannot contain missing values. When given, the function uses xarray’s quantile method which is slower than xclim’s NaN-optimized algorithm.

• split (bool) – Whether to split each percentile into a new variable or concatenate the output along a new “percentiles” dimension.

Return type:

DataArray | Dataset

Returns:

xr.Dataset or xr.DataArray – If split is True, same type as ens; dataset otherwise, containing data variable(s) of requested ensemble statistics

Examples

from xclim.ensembles import create_ensemble, ensemble_percentiles

# Create ensemble dataset:
ens = create_ensemble(temperature_datasets)

# Calculate default ensemble percentiles:
ens_percs = ensemble_percentiles(ens)

# Calculate non-default percentiles (25th and 75th)
ens_percs = ensemble_percentiles(ens, values=(25, 50, 75))

# If the original array has many small chunks, it might be more efficient to do:
ens_percs = ensemble_percentiles(ens, keep_chunk_size=False)

Ensemble Reduction

Ensemble reduction is the process of selecting a subset of members from an ensemble in order to reduce the volume of computation needed while still covering a good portion of the simulated climate variability.

xclim.ensembles.kkz_reduce_ensemble(data, num_select, *, dist_method='euclidean', standardize=True, **cdist_kwargs)

Return a sample of ensemble members using KKZ selection.

The algorithm selects num_select ensemble members spanning the overall range of the ensemble. The selection is ordered, smaller groups are always subsets of larger ones for given criteria. The first selected member is the one nearest to the centroid of the ensemble, all subsequent members are selected in a way maximizing the phase-space coverage of the group. Algorithm taken from Cannon [2015].

Parameters:

• data (xr.DataArray) – Selection criteria data : 2-D xr.DataArray with dimensions ‘realization’ (N) and ‘criteria’ (P). These are the values used for clustering. Realizations represent the individual original ensemble members and criteria the variables/indicators used in the grouping algorithm.

• num_select (int) – The number of members to select.

• dist_method (str) – Any distance metric name accepted by scipy.spatial.distance.cdist.

• standardize (bool) – Whether to standardize the input before running the selection or not. Standardization consists in translation as to have a zero mean and scaling as to have a unit standard deviation.

• **cdist_kwargs – All extra arguments are passed as-is to scipy.spatial.distance.cdist, see its docs for more information.

Return type:

list

Returns:

list – Selected model indices along the realization dimension.

References

Cannon [2015], Katsavounidis, Jay Kuo, and Zhang [1994]

xclim.ensembles.kmeans_reduce_ensemble(data, *, method=None, make_graph=True, max_clusters=None, variable_weights=None, model_weights=None, sample_weights=None, random_state=None)

Return a sample of ensemble members using k-means clustering.

The algorithm attempts to reduce the total number of ensemble members while maintaining adequate coverage of the ensemble uncertainty in an N-dimensional data space. K-Means clustering is carried out on the input selection criteria data-array in order to group individual ensemble members into a reduced number of similar groups. Subsequently, a single representative simulation is retained from each group.

Parameters:

• data (xr.DataArray) – Selection criteria data : 2-D xr.DataArray with dimensions ‘realization’ (N) and ‘criteria’ (P). These are the values used for clustering. Realizations represent the individual original ensemble members and criteria the variables/indicators used in the grouping algorithm.

• method (dict, optional) – Dictionary defining selection method and associated value when required. See Notes.

• max_clusters (int, optional) – Maximum number of members to include in the output ensemble selection. When using ‘rsq_optimize’ or ‘rsq_cutoff’ methods, limit the final selection to a maximum number even if method results indicate a higher value. Defaults to N.

• variable_weights (np.ndarray, optional) – An array of size P. This weighting can be used to influence of weight of the climate indices (criteria dimension) on the clustering itself.

• model_weights (np.ndarray, optional) – An array of size N. This weighting can be used to influence which realization is selected from within each cluster. This parameter has no influence on the clustering itself.

• sample_weights (np.ndarray, optional) – An array of size N. sklearn.cluster.KMeans() sample_weights parameter. This weighting can be used to influence of weight of simulations on the clustering itself. See: https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html

• random_state (int or np.random.RandomState, optional) – sklearn.cluster.KMeans() random_state parameter. Determines random number generation for centroid initialization. Use an int to make the randomness deterministic. See: https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html

• make_graph (bool) – output a dictionary of input for displays a plot of R² vs. the number of clusters. Defaults to True if matplotlib is installed in runtime environment.

Notes

Parameters for method in call must follow these conventions:

rsq_optimize

Calculate coefficient of variation (R²) of cluster results for n = 1 to N clusters and determine an optimal number of clusters that balances cost/benefit tradeoffs. This is the default setting. See supporting information S2 text in Casajus et al. [2016].

method={‘rsq_optimize’:None}

rsq_cutoff

Calculate Coefficient of variation (R²) of cluster results for n = 1 to N clusters and determine the minimum numbers of clusters needed for R² > val.

val : float between 0 and 1. R² value that must be exceeded by clustering results.

method={‘rsq_cutoff’: val}

n_clusters

Create a user determined number of clusters.

val : integer between 1 and N

method={‘n_clusters’: val}

Return type:

tuple[list, ndarray, dict]

Returns:

• list – Selected model indexes (positions)

• np.ndarray – KMeans clustering results

• dict – Dictionary of input data for creating R² profile plot. ‘None’ when make_graph=False

References

Casajus, Périé, Logan, Lambert, Blois, and Berteaux [2016]

Examples

import xclim
from xclim.ensembles import create_ensemble, kmeans_reduce_ensemble
from xclim.indices import hot_spell_frequency

# Start with ensemble datasets for temperature:

ensTas = create_ensemble(temperature_datasets)

# Calculate selection criteria -- Use annual climate change Δ fields between 2071-2100 and 1981-2010 normals.
# First, average annual temperature:

tg = xclim.atmos.tg_mean(tas=ensTas.tas)
his_tg = tg.sel(time=slice("1990", "2019")).mean(dim="time")
fut_tg = tg.sel(time=slice("2020", "2050")).mean(dim="time")
dtg = fut_tg - his_tg

# Then, hot spell frequency as second indicator:

hs = hot_spell_frequency(tasmax=ensTas.tas, window=2, thresh_tasmax="10 degC")
his_hs = hs.sel(time=slice("1990", "2019")).mean(dim="time")
fut_hs = hs.sel(time=slice("2020", "2050")).mean(dim="time")
dhs = fut_hs - his_hs

# Create a selection criteria xr.DataArray:

from xarray import concat

crit = concat((dtg, dhs), dim="criteria")

# Finally, create clusters and select realization ids of reduced ensemble:

ids, cluster, fig_data = kmeans_reduce_ensemble(
    data=crit, method={"rsq_cutoff": 0.9}, random_state=42, make_graph=False
)
ids, cluster, fig_data = kmeans_reduce_ensemble(
    data=crit, method={"rsq_optimize": None}, random_state=42, make_graph=True
)

xclim.ensembles.plot_rsqprofile(fig_data)

Create an R² profile plot using kmeans_reduce_ensemble output.

The R² plot allows evaluation of the proportion of total uncertainty in the original ensemble that is provided by the reduced selected.

Examples

>>> from xclim.ensembles import kmeans_reduce_ensemble, plot_rsqprofile
>>> is_matplotlib_installed()
>>> crit = xr.open_dataset(path_to_ensemble_file).data
>>> ids, cluster, fig_data = kmeans_reduce_ensemble(
...     data=crit, method={"rsq_cutoff": 0.9}, random_state=42, make_graph=True
... )
>>> plot_rsqprofile(fig_data)

Ensemble Robustness Metrics

Robustness metrics are used to estimate the confidence of the climate change signal of an ensemble. This submodule is inspired by and tries to follow the guidelines of the IPCC, more specifically the 12th chapter of the Working Group 1’s contribution to the AR5 [Collins et al., 2013] (see box 12.1).

xclim.ensembles.change_significance(fut, ref=None, test='ttest', weights=None, p_vals=False, **kwargs)

Robustness statistics qualifying how members of an ensemble agree on the existence of change and on its sign.

Parameters:

• fut (xr.DataArray or xr.Dataset) – Future period values along ‘realization’ and ‘time’ (…, nr, nt1) or if ref is None, Delta values along realization (…, nr).

• ref (Union[xr.DataArray, xr.Dataset], optional) – Reference period values along realization’ and ‘time’ (…, nt2, nr). The size of the ‘time’ axis does not need to match the one of fut. But their ‘realization’ axes must be identical. If None (default), values of fut are assumed to be deltas instead of a distribution across the future period. fut and ref must be of the same type (Dataset or DataArray). If they are Dataset, they must have the same variables (name and coords).

• test ({‘ttest’, ‘welch-ttest’, ‘mannwhitney-utest’, ‘brownforsythe-test’, ‘threshold’, None}) – Name of the statistical test used to determine if there was significant change. See notes.

• weights (xr.DataArray) – Weights to apply along the ‘realization’ dimension. This array cannot contain missing values. Only tests “threshold” and “None” are currently supported with weighted arrays.

• p_vals (bool) – If True, return the estimated p-values.

• **kwargs – Other arguments specific to the statistical test.

  For ‘ttest’, ‘welch-ttest’, ‘mannwhitney-utest’ and ‘brownforsythe-test’:

  p_changefloat (default0.05)

  p-value threshold for rejecting the hypothesis of no significant change.

  For ‘threshold’: (Only one of those must be given.)

  abs_threshfloat (no default)

  Threshold for the (absolute) change to be considered significative.

  rel_threshfloat (no default, in [0, 1])

  Threshold for the relative change (in reference to ref) to be significative. Only valid if ref is given.

Return type:

tuple[DataArray | Dataset, DataArray | Dataset] | tuple[DataArray | Dataset, DataArray | Dataset, UnionType[DataArray, Dataset, None]]

Returns:

• change_frac (xr.DataArray or xr.Dataset) – The fraction of members that show significant change [0, 1]. Passing test=None yields change_frac = 1 everywhere. Same type as fut.

• pos_frac (xr.DataArray or xr.Dataset) – The fraction of members showing significant change that show a positive change ]0, 1]. Null values are returned where no members show significant change.

• pvals [Optional] (xr.DataArray or xr.Dataset or None) – The p-values estimated by the significance tests. Only returned if p_vals is True. None if test is one of ‘ttest’, ‘welch-ttest’, ‘mannwhitney-utest’ or ‘brownforsythe-test’.

  The table below shows the coefficient needed to retrieve the number of members that have the indicated characteristics, by multiplying it to the total number of members (fut.realization.size).

  	Significant change	Non-significant change
  Any direction	change_frac	1 - change_frac
  Positive change	pos_frac * change_frac	N.A.
  Negative change	(1 - pos_frac) * change_frac

Notes

Available statistical tests are :

‘ttest’ :

Single sample T-test. Same test as used by Tebaldi et al. [2011]. The future values are compared against the reference mean (over ‘time’). Change is qualified as ‘significant’ when the test’s p-value is below the user-provided p_change value.

‘welch-ttest’ :

Two-sided T-test, without assuming equal population variance. Same significance criterion as ‘ttest’.

‘mannwhitney-utest’ :

Two-sided Mann-Whiney U-test. Same significance criterion as ‘ttest’.

‘brownforsythe-test’ :

Brown-Forsythe test assuming skewed, non-normal distributions. Same significance criterion as ‘ttest’.

‘threshold’ :

Change is considered significative if the absolute delta exceeds a given threshold (absolute or relative).

None :

Significant change is not tested and, thus, members showing no change are included in the sign_frac output.

References

Tebaldi, Arblaster, and Knutti [2011]

Example

This example computes the mean temperature in an ensemble and compares two time periods, qualifying significant change through a single sample T-test.

>>> from xclim import ensembles
>>> ens = ensembles.create_ensemble(temperature_datasets)
>>> tgmean = xclim.atmos.tg_mean(tas=ens.tas, freq="YS")
>>> fut = tgmean.sel(time=slice("2020", "2050"))
>>> ref = tgmean.sel(time=slice("1990", "2020"))
>>> chng_f, pos_f = ensembles.change_significance(fut, ref, test="ttest")

If the deltas were already computed beforehand, the ‘threshold’ test can still be used, here with a 2 K threshold.

>>> delta = fut.mean("time") - ref.mean("time")
>>> chng_f, pos_f = ensembles.change_significance(
...     delta, test="threshold", abs_thresh=2
... )

xclim.ensembles.robustness_coefficient(fut, ref)

Robustness coefficient quantifying the robustness of a climate change signal in an ensemble.

Taken from Knutti and Sedláček [2013].

The robustness metric is defined as R = 1 − A1 / A2 , where A1 is defined as the integral of the squared area between two cumulative density functions characterizing the individual model projections and the multimodel mean projection and A2 is the integral of the squared area between two cumulative density functions characterizing the multimodel mean projection and the historical climate. Description taken from Knutti and Sedláček [2013].

A value of R equal to one implies perfect model agreement. Higher model spread or smaller signal decreases the value of R.

Parameters:

• fut (Union[xr.DataArray, xr.Dataset]) – Future ensemble values along ‘realization’ and ‘time’ (nr, nt). Can be a dataset, in which case the coefficient is computed on each variable.

• ref (Union[xr.DataArray, xr.Dataset]) – Reference period values along ‘time’ (nt). Same type as fut.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – The robustness coefficient, ]-inf, 1], float. Same type as fut or ref.

References

Knutti and Sedláček [2013]

Units Handling Submodule

Units Handling Submodule

Pint is used to define the xclim.core.units.units UnitRegistry. This module defines most unit handling methods.

xclim.core.units.amount2lwethickness(amount, out_units=None)

Convert a liquid water amount (mass over area) to its equivalent area-averaged thickness (length).

This will simply divide the amount by the density of liquid water, 1000 kg/m³. This is equivalent to using the “hydro” context of xclim.core.units.units.

Parameters:

• amount (xr.DataArray) – A DataArray storing a liquid water amount quantity.

• out_units (str) – Specific output units if needed.

Returns:

lwe_thickness – The standard_name of amount is modified if a conversion is found (see xclim.core.units.cf_conversion()), it is removed otherwise. Other attributes are left untouched.

See also

lwethickness2amount

xclim.core.units.amount2rate(amount, dim='time', sampling_rate_from_coord=False, out_units=None)

Convert an amount variable to a rate by dividing by the sampling period length.

If the sampling period length cannot be inferred, the amount values are divided by the duration between their time coordinate and the next one. The last period is estimated with the duration of the one just before.

This is the inverse operation of xclim.core.units.rate2amount().

Parameters:

• amount (xr.DataArray) – “amount” variable. Ex: Precipitation amount in “mm”.

• dim (str) – The time dimension.

• sampling_rate_from_coord (boolean) – For data with irregular time coordinates. If True, the diff of the time coordinate will be used as the sampling rate, meaning each data point will be assumed to span the interval ending at the next point. See notes of xclim.core.units.rate2amount(). Defaults to False, which raises an error if the time coordinate is irregular.

• out_units (str, optional) – Output units to convert to.

Raises:

ValueError – If the time coordinate is irregular and sampling_rate_from_coord is False (default).

Return type:

DataArray

Returns:

xr.DataArray

See also

rate2amount

xclim.core.units.check_units(val, dim)

Check units for appropriate convention compliance.

Return type:

None

xclim.core.units.convert_units_to(source, target, context=None)

Convert a mathematical expression into a value with the same units as a DataArray.

If the dimensionalities of source and target units differ, automatic CF conversions will be applied when possible. See xclim.core.units.cf_conversion().

Parameters:

• source (str or xr.DataArray or units.Quantity) – The value to be converted, e.g. ‘4C’ or ‘1 mm/d’.

• target (str or xr.DataArray or units.Quantity or units.Unit) – Target array of values to which units must conform.

• context (str, optional) – The unit definition context. Default: None. If “infer”, it will be inferred with xclim.core.units.infer_context() using the standard name from the source or, if none is found, from the target. This means that the ‘hydro’ context could be activated if any one of the standard names allows it.

Return type:

TypeVar(Quantified, DataArray, str, Quantity)

Returns:

str or xr.DataArray or units.Quantity – The source value converted to target’s units. The outputted type is always similar to source initial type. Attributes are preserved unless an automatic CF conversion is performed, in which case only the new standard_name appears in the result.

See also

cf_conversion, amount2rate, rate2amount, amount2lwethickness, lwethickness2amount

xclim.core.units.declare_units(**units_by_name)

Create a decorator to check units of function arguments.

The decorator checks that input and output values have units that are compatible with expected dimensions. It also stores the input units as a ‘in_units’ attribute.

Parameters:

units_by_name (dict[str, str]) – Mapping from the input parameter names to their units or dimensionality (“[…]”).

Return type:

Callable

Returns:

Callable

Examples

In the following function definition:

@declare_units(tas=["temperature"])
def func(tas):
    ...

The decorator will check that tas has units of temperature (C, K, F).

xclim.core.units.infer_context(standard_name=None, dimension=None)

Return units context based on either the variable’s standard name or the pint dimension.

Valid standard names for the hydro context are those including the terms “rainfall”, “lwe” (liquid water equivalent) and “precipitation”. The latter is technically incorrect, as any phase of precipitation could be referenced. Standard names for evapotranspiration, evaporation and canopy water amounts are also associated with the hydro context.

Parameters:

• standard_name (str) – CF-Convention standard name.

• dimension (str) – Pint dimension, e.g. ‘[time]’.

Returns:

str – “hydro” if variable is a liquid water flux, otherwise “none”

xclim.core.units.infer_sampling_units(da, deffreq='D', dim='time')

Infer a multiplier and the units corresponding to one sampling period.

Parameters:

• da (xr.DataArray) – A DataArray from which to take coordinate dim.

• deffreq (str, optional) – If no frequency is inferred from da[dim], take this one.

• dim (str) – Dimension from which to infer the frequency.

Raises:

ValueError – If the frequency has no exact corresponding units.

Return type:

tuple[int, str]

Returns:

• int – The magnitude (number of base periods per period)

• str – Units as a string, understandable by pint.

xclim.core.units.lwethickness2amount(thickness, out_units=None)

Convert a liquid water thickness (length) to its equivalent amount (mass over area).

This will simply multiply the thickness by the density of liquid water, 1000 kg/m³. This is equivalent to using the “hydro” context of xclim.core.units.units.

Parameters:

• thickness (xr.DataArray) – A DataArray storing a liquid water thickness quantity.

• out_units (str) – Specific output units if needed.

Returns:

amount – The standard_name of amount is modified if a conversion is found (see xclim.core.units.cf_conversion()), it is removed otherwise. Other attributes are left untouched.

See also

amount2lwethickness

xclim.core.units.pint2cfunits(value)

Return a CF-compliant unit string from a pint unit.

Parameters:

value (pint.Unit) – Input unit.

Return type:

str

Returns:

str – Units following CF-Convention, using symbols.

xclim.core.units.pint_multiply(da, q, out_units=None)

Multiply xarray.DataArray by pint.Quantity.

Parameters:

• da (xr.DataArray) – Input array.

• q (pint.Quantity) – Multiplicative factor.

• out_units (str, optional) – Units the output array should be converted into.

xclim.core.units.rate2amount(rate, dim='time', sampling_rate_from_coord=False, out_units=None)

Convert a rate variable to an amount by multiplying by the sampling period length.

If the sampling period length cannot be inferred, the rate values are multiplied by the duration between their time coordinate and the next one. The last period is estimated with the duration of the one just before.

This is the inverse operation of xclim.core.units.amount2rate().

Parameters:

• rate (xr.DataArray) – “Rate” variable, with units of “amount” per time. Ex: Precipitation in “mm / d”.

• dim (str) – The time dimension.

• sampling_rate_from_coord (boolean) – For data with irregular time coordinates. If True, the diff of the time coordinate will be used as the sampling rate, meaning each data point will be assumed to apply for the interval ending at the next point. See notes. Defaults to False, which raises an error if the time coordinate is irregular.

• out_units (str, optional) – Output units to convert to.

Raises:

ValueError – If the time coordinate is irregular and sampling_rate_from_coord is False (default).

Return type:

DataArray

Returns:

xr.DataArray

Examples

The following converts a daily array of precipitation in mm/h to the daily amounts in mm:

>>> time = xr.cftime_range("2001-01-01", freq="D", periods=365)
>>> pr = xr.DataArray(
...     [1] * 365, dims=("time",), coords={"time": time}, attrs={"units": "mm/h"}
... )
>>> pram = rate2amount(pr)
>>> pram.units
'mm'
>>> float(pram[0])
24.0

Also works if the time axis is irregular : the rates are assumed constant for the whole period starting on the values timestamp to the next timestamp. This option is activated with sampling_rate_from_coord=True.

>>> time = time[[0, 9, 30]]  # The time axis is Jan 1st, Jan 10th, Jan 31st
>>> pr = xr.DataArray(
...     [1] * 3, dims=("time",), coords={"time": time}, attrs={"units": "mm/h"}
... )
>>> pram = rate2amount(pr, sampling_rate_from_coord=True)
>>> pram.values
array([216., 504., 504.])

Finally, we can force output units:

>>> pram = rate2amount(pr, out_units="pc")  # Get rain amount in parsecs. Why not.
>>> pram.values
array([7.00008327e-18, 1.63335276e-17, 1.63335276e-17])

See also

amount2rate

xclim.core.units.str2pint(val)

Convert a string to a pint.Quantity, splitting the magnitude and the units.

Parameters:

val (str) – A quantity in the form “[{magnitude} ]{units}”, where magnitude can be cast to a float and units is understood by units2pint.

Return type:

Quantity

Returns:

pint.Quantity – Magnitude is 1 if no magnitude was present in the string.

xclim.core.units.to_agg_units(out, orig, op, dim='time')

Set and convert units of an array after an aggregation operation along the sampling dimension (time).

Parameters:

• out (xr.DataArray) – The output array of the aggregation operation, no units operation done yet.

• orig (xr.DataArray) – The original array before the aggregation operation, used to infer the sampling units and get the variable units.

• op ({‘count’, ‘prod’, ‘delta_prod’}) – The type of aggregation operation performed. The special “delta_*” ops are used with temperature units needing conversion to their “delta” counterparts (e.g. degree days)

• dim (str) – The time dimension along which the aggregation was performed.

Return type:

DataArray

Returns:

xr.DataArray

Examples

Take a daily array of temperature and count number of days above a threshold. to_agg_units will infer the units from the sampling rate along “time”, so we ensure the final units are correct:

>>> time = xr.cftime_range("2001-01-01", freq="D", periods=365)
>>> tas = xr.DataArray(
...     np.arange(365),
...     dims=("time",),
...     coords={"time": time},
...     attrs={"units": "degC"},
... )
>>> cond = tas > 100  # Which days are boiling
>>> Ndays = cond.sum("time")  # Number of boiling days
>>> Ndays.attrs.get("units")
None
>>> Ndays = to_agg_units(Ndays, tas, op="count")
>>> Ndays.units
'd'

Similarly, here we compute the total heating degree-days, but we have weekly data:

>>> time = xr.cftime_range("2001-01-01", freq="7D", periods=52)
>>> tas = xr.DataArray(
...     np.arange(52) + 10,
...     dims=("time",),
...     coords={"time": time},
...     attrs={"units": "degC"},
... )
>>> degdays = (
...     (tas - 16).clip(0).sum("time")
... )  # Integral of  temperature above a threshold
>>> degdays = to_agg_units(degdays, tas, op="delta_prod")
>>> degdays.units
'week delta_degC'

Which we can always convert to the more common “K days”:

>>> degdays = convert_units_to(degdays, "K days")
>>> degdays.units
'K d'

xclim.core.units.units2pint(value)

Return the pint Unit for the DataArray units.

Parameters:

value (xr.DataArray or str or pint.Quantity) – Input data array or string representing a unit (with no magnitude).

Return type:

Unit

Returns:

pint.Unit – Units of the data array.

SDBA Module

Adjustment Methods

class xclim.sdba.adjustment.DetrendedQuantileMapping(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Detrended Quantile Mapping bias-adjustment.

The algorithm follows these steps, 1-3 being the ‘train’ and 4-6, the ‘adjust’ steps.

1. A scaling factor that would make the mean of hist match the mean of ref is computed.

2. ref and hist are normalized by removing the “dayofyear” mean.

3. Adjustment factors are computed between the quantiles of the normalized ref and hist.

4. sim is corrected by the scaling factor, and either normalized by “dayofyear” and detrended group-wise or directly detrended per “dayofyear”, using a linear fit (modifiable).

5. Values of detrended sim are matched to the corresponding quantiles of normalized hist and corrected accordingly.

6. The trend is put back on the result.

\[F^{-1}_{ref}\left\{F_{hist}\left[\frac{\overline{hist}\cdot sim}{\overline{sim}}\right]\right\}\frac{\overline{sim}}{\overline{hist}}\]

where \(F\) is the cumulative distribution function (CDF) and \(\overline{xyz}\) is the linear trend of the data. This equation is valid for multiplicative adjustment. Based on the DQM method of [Cannon et al., 2015].

Parameters:

• Train step

• nquantiles (int or 1d array of floats) – The number of quantiles to use. See equally_spaced_nodes(). An array of quantiles [0, 1] can also be passed. Defaults to 20 quantiles.

• kind ({‘+’, ‘’}*) – The adjustment kind, either additive or multiplicative. Defaults to “+”.

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. Default is “time”, meaning a single adjustment group along dimension “time”.

• Adjust step

• interp ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method to use when interpolating the adjustment factors. Defaults to “nearest”.

• detrend (int or BaseDetrend instance) – The method to use when detrending. If an int is passed, it is understood as a PolyDetrend (polynomial detrending) degree. Defaults to 1 (linear detrending)

• extrapolation ({‘constant’, ‘nan’}) – The type of extrapolation to use. See xclim.sdba.utils.extrapolate_qm() for details. Defaults to “constant”.

References

Cannon, Sobie, and Murdock [2015]

class xclim.sdba.adjustment.EmpiricalQuantileMapping(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Empirical Quantile Mapping bias-adjustment.

Adjustment factors are computed between the quantiles of ref and sim. Values of sim are matched to the corresponding quantiles of hist and corrected accordingly.

\[F^{-1}_{ref} (F_{hist}(sim))\]

where \(F\) is the cumulative distribution function (CDF) and mod stands for model data.

Variables:

• step (Adjust) –

• nquantiles (int or 1d array of floats) – The number of quantiles to use. Two endpoints at 1e-6 and 1 - 1e-6 will be added. An array of quantiles [0, 1] can also be passed. Defaults to 20 quantiles.

• kind ({'+', '*'}) – The adjustment kind, either additive or multiplicative. Defaults to “+”.

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. Default is “time”, meaning an single adjustment group along dimension “time”.

• step –

• interp ({'nearest', 'linear', 'cubic'}) – The interpolation method to use when interpolating the adjustment factors. Defaults to “nearset”.

• extrapolation ({'constant', 'nan'}) – The type of extrapolation to use. See xclim.sdba.utils.extrapolate_qm() for details. Defaults to “constant”.

References

Déqué [2007]

class xclim.sdba.adjustment.ExtremeValues(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Adjustment correction for extreme values.

The tail of the distribution of adjusted data is corrected according to the bias between the parametric Generalized Pareto distributions of the simulated and reference data [Roy et al., 2021]. The distributions are composed of the maximal values of clusters of “large” values. With “large” values being those above cluster_thresh. Only extreme values, whose quantile within the pool of large values are above q_thresh, are re-adjusted. See Notes.

This adjustment method should be considered experimental and used with care.

Parameters:

• Train step

• cluster_thresh (Quantity (str with units)) – The threshold value for defining clusters.

• q_thresh (float) – The quantile of “extreme” values, [0, 1[. Defaults to 0.95.

• ref_params (xr.DataArray, optional) – Distribution parameters to use instead of fitting a GenPareto distribution on ref.

• Adjust step

• scen (DataArray) – This is a second-order adjustment, so the adjust method needs the first-order adjusted timeseries in addition to the raw “sim”.

• interp ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method to use when interpolating the adjustment factors. Defaults to “linear”.

• extrapolation ({‘constant’, ‘nan’}) – The type of extrapolation to use. See extrapolate_qm() for details. Defaults to “constant”.

• frac (float) – Fraction where the cutoff happens between the original scen and the corrected one. See Notes, ]0, 1]. Defaults to 0.25.

• power (float) – Shape of the correction strength, see Notes. Defaults to 1.0.

Notes

Extreme values are extracted from ref, hist and sim by finding all “clusters”, i.e. runs of consecutive values above cluster_thresh. The q_thresh`th percentile of these values is taken on `ref and hist and becomes thresh, the extreme value threshold. The maximal value of each cluster, if it exceeds that new threshold, is taken and Generalized Pareto distributions are fitted to them, for both ref and hist. The probabilities associated with each of these extremes in hist is used to find the corresponding value according to ref’s distribution. Adjustment factors are computed as the bias between those new extremes and the original ones.

In the adjust step, a Generalized Pareto distributions is fitted on the cluster-maximums of sim and it is used to associate a probability to each extreme, values over the thresh compute in the training, without the clustering. The adjustment factors are computed by interpolating the trained ones using these probabilities and the probabilities computed from hist.

Finally, the adjusted values (\(C_i\)) are mixed with the pre-adjusted ones (scen, \(D_i\)) using the following transition function:

\[V_i = C_i * \tau + D_i * (1 - \tau)\]

Where \(\tau\) is a function of sim’s extreme values (unadjusted, \(S_i\)) and of arguments frac (\(f\)) and power (\(p\)):

\[\tau = \left(\frac{1}{f}\frac{S - min(S)}{max(S) - min(S)}\right)^p\]

Code based on an internal Matlab source and partly ib the biascorrect_extremes function of the julia package “ClimateTools.jl” [Roy et al., 2021].

Because of limitations imposed by the lazy computing nature of the dask backend, it is not possible to know the number of cluster extremes in ref and hist at the moment the output data structure is created. This is why the code tries to estimate that number and usually overestimates it. In the training dataset, this translated into a quantile dimension that is too large and variables af and px_hist are assigned NaNs on extra elements. This has no incidence on the calculations themselves but requires more memory than is useful.

References

Roy, Smith, Kelman, Nolet-Gravel, Saba, Thomet, TagBot, and Forget [2021] Roy, Rondeau-Genesse, Jalbert, and Fournier [2021]

class xclim.sdba.adjustment.LOCI(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Local Intensity Scaling (LOCI) bias-adjustment.

This bias adjustment method is designed to correct daily precipitation time series by considering wet and dry days separately [Schmidli et al., 2006].

Multiplicative adjustment factors are computed such that the mean of hist matches the mean of ref for values above a threshold.

The threshold on the training target ref is first mapped to hist by finding the quantile in hist having the same exceedance probability as thresh in ref. The adjustment factor is then given by

\[s = \frac{\left \langle ref: ref \geq t_{ref} \right\rangle - t_{ref}}{\left \langle hist : hist \geq t_{hist} \right\rangle - t_{hist}}\]

In the case of precipitations, the adjustment factor is the ratio of wet-days intensity.

For an adjustment factor s, the bias-adjustment of sim is:

\[sim(t) = \max\left(t_{ref} + s \cdot (hist(t) - t_{hist}), 0\right)\]

Variables:

• step (Adjust) –

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. Default is “time”, meaning a single adjustment group along dimension “time”.

• thresh (str) – The threshold in ref above which the values are scaled.

• step –

• interp ({'nearest', 'linear', 'cubic'}) – The interpolation method to use then interpolating the adjustment factors. Defaults to “linear”.

References

Schmidli, Frei, and Vidale [2006]

class xclim.sdba.adjustment.NpdfTransform(*args, _trained=False, **kwargs)

Bases: Adjust

N-dimensional probability density function transform.

This adjustment object combines both training and adjust steps in the adjust class method.

A multivariate bias-adjustment algorithm described by Cannon [2018], as part of the MBCn algorithm, based on a color-correction algorithm described by Pitie et al. [2005].

This algorithm in itself, when used with QuantileDeltaMapping, is NOT trend-preserving. The full MBCn algorithm includes a reordering step provided here by xclim.sdba.processing.reordering().

See notes for an explanation of the algorithm.

Parameters:

• base (BaseAdjustment) – An univariate bias-adjustment class. This is untested for anything else than QuantileDeltaMapping.

• base_kws (dict, optional) – Arguments passed to the training of the univariate adjustment.

• n_escore (int) – The number of elements to send to the escore function. The default, 0, means all elements are included. Pass -1 to skip computing the escore completely. Small numbers result in less significant scores, but the execution time goes up quickly with large values.

• n_iter (int) – The number of iterations to perform. Defaults to 20.

• pts_dim (str) – The name of the “multivariate” dimension. Defaults to “multivar”, which is the normal case when using xclim.sdba.base.stack_variables().

• adj_kws (dict, optional) – Dictionary of arguments to pass to the adjust method of the univariate adjustment.

• rot_matrices (xr.DataArray, optional) – The rotation matrices as a 3D array (‘iterations’, <pts_dim>, <anything>), with shape (n_iter, <N>, <N>). If left empty, random rotation matrices will be automatically generated.

Notes

The historical reference (\(T\), for “target”), simulated historical (\(H\)) and simulated projected (\(S\)) datasets are constructed by stacking the timeseries of N variables together. The algorithm is broken into the following steps:

1. Rotate the datasets in the N-dimensional variable space with \(\mathbf{R}\), a random rotation NxN matrix.

\[\tilde{\mathbf{T}} = \mathbf{T}\mathbf{R} \ \tilde{\mathbf{H}} = \mathbf{H}\mathbf{R} \ \tilde{\mathbf{S}} = \mathbf{S}\mathbf{R}\]

2. An univariate bias-adjustment \(\mathcal{F}\) is used on the rotated datasets. The adjustments are made in additive mode, for each variable \(i\).

\[\hat{\mathbf{H}}_i, \hat{\mathbf{S}}_i = \mathcal{F}\left(\tilde{\mathbf{T}}_i, \tilde{\mathbf{H}}_i, \tilde{\mathbf{S}}_i\right)\]

3. The bias-adjusted datasets are rotated back.

\[\begin{split}\mathbf{H}' = \hat{\mathbf{H}}\mathbf{R} \\ \mathbf{S}' = \hat{\mathbf{S}}\mathbf{R}\end{split}\]

These three steps are repeated a certain number of times, prescribed by argument n_iter. At each iteration, a new random rotation matrix is generated.

The original algorithm [Pitie et al., 2005], stops the iteration when some distance score converges. Following cite:t:sdba-cannon_multivariate_2018 and the MBCn implementation in Cannon [2020], we instead fix the number of iterations.

As done by cite:t:sdba-cannon_multivariate_2018, the distance score chosen is the “Energy distance” from Szekely and Rizzo [2004]. (see: xclim.sdba.processing.escore()).

The random matrices are generated following a method laid out by Mezzadri [2007].

This is only part of the full MBCn algorithm, see Statistical Downscaling and Bias-Adjustment for an example on how to replicate the full method with xclim. This includes a standardization of the simulated data beforehand, an initial univariate adjustment and the reordering of those adjusted series according to the rank structure of the output of this algorithm.

References

Cannon [2018], Cannon [2020], Mezzadri [2007], Pitie, Kokaram, and Dahyot [2005], Szekely and Rizzo [2004]

class xclim.sdba.adjustment.PrincipalComponents(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Principal component adjustment.

This bias-correction method maps model simulation values to the observation space through principal components [Hnilica et al., 2017]. Values in the simulation space (multiple variables, or multiple sites) can be thought of as coordinate along axes, such as variable, temperature, etc. Principal components (PC) are a linear combinations of the original variables where the coefficients are the eigenvectors of the covariance matrix. Values can then be expressed as coordinates along the PC axes. The method makes the assumption that bias-corrected values have the same coordinates along the PC axes of the observations. By converting from the observation PC space to the original space, we get bias corrected values. See Notes for a mathematical explanation.

Warning

Be aware that principal components is meant here as the algebraic operation defining a coordinate system based on the eigenvectors, not statistical principal component analysis.

Variables:

• group (Union[str, Grouper]) – The main dimension and grouping information. See Notes. See xclim.sdba.base.Grouper for details. The adjustment will be performed on each group independently. Default is “time”, meaning a single adjustment group along dimension “time”.

• best_orientation ({'simple', 'full'}) – Which method to use when searching for the best principal component orientation. See best_pc_orientation_simple() and best_pc_orientation_full(). “full” is more precise, but it is much slower.

• crd_dim (str) – The data dimension along which the multiple simulation space dimensions are taken. For a multivariate adjustment, this usually is “multivar”, as returned by sdba.stack_variables. For a multisite adjustment, this should be the spatial dimension. The training algorithm currently doesn’t support any chunking along either crd_dim. group.dim and group.add_dims.

Notes

The input data is understood as a set of N points in a \(M\)-dimensional space.

• \(M\) is taken along crd_dim.

• \(N\) is taken along the dimensions given through group : (the main dim but also, if requested, the add_dims and window).

The principal components (PC) of hist and ref are used to defined new coordinate systems, centered on their respective means. The training step creates a matrix defining the transformation from hist to ref:

\[scen = e_{R} + \mathrm{\mathbf{T}}(sim - e_{H})\]

Where:

\[\mathrm{\mathbf{T}} = \mathrm{\mathbf{R}}\mathrm{\mathbf{H}}^{-1}\]

\(\mathrm{\mathbf{R}}\) is the matrix transforming from the PC coordinates computed on ref to the data coordinates. Similarly, \(\mathrm{\mathbf{H}}\) is transform from the hist PC to the data coordinates (\(\mathrm{\mathbf{H}}\) is the inverse transformation). \(e_R\) and \(e_H\) are the centroids of the ref and hist distributions respectively. Upon running the adjust step, one may decide to use \(e_S\), the centroid of the sim distribution, instead of \(e_H\).

References

Alavoine and Grenier [2022], Hnilica, Hanel, and Puš [2017]

class xclim.sdba.adjustment.QuantileDeltaMapping(*args, _trained=False, **kwargs)

Bases: EmpiricalQuantileMapping

Quantile Delta Mapping bias-adjustment.

Adjustment factors are computed between the quantiles of ref and hist. Quantiles of sim are matched to the corresponding quantiles of hist and corrected accordingly.

\[sim\frac{F^{-1}_{ref}\left[F_{sim}(sim)\right]}{F^{-1}_{hist}\left[F_{sim}(sim)\right]}\]

where \(F\) is the cumulative distribution function (CDF). This equation is valid for multiplicative adjustment. The algorithm is based on the “QDM” method of [Cannon et al., 2015].

Parameters:

• Train step

• nquantiles (int or 1d array of floats) – The number of quantiles to use. See equally_spaced_nodes(). An array of quantiles [0, 1] can also be passed. Defaults to 20 quantiles.

• kind ({‘+’, ‘’}*) – The adjustment kind, either additive or multiplicative. Defaults to “+”.

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. Default is “time”, meaning a single adjustment group along dimension “time”.

• Adjust step

• interp ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method to use when interpolating the adjustment factors. Defaults to “nearest”.

• extrapolation ({‘constant’, ‘nan’}) – The type of extrapolation to use. See xclim.sdba.utils.extrapolate_qm() for details. Defaults to “constant”.

• Extra diagnostics

• —————–

• In adjustment

• quantiles (The quantile of each value of sim. The adjustment factor is interpolated using this as the “quantile” axis on ds.af.)

References

Cannon, Sobie, and Murdock [2015]

class xclim.sdba.adjustment.Scaling(*args, _trained=False, **kwargs)

Bases: TrainAdjust

Scaling bias-adjustment.

Simple bias-adjustment method scaling variables by an additive or multiplicative factor so that the mean of hist matches the mean of ref.

Parameters:

• Train step

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. Default is “time”, meaning an single adjustment group along dimension “time”.

• kind ({‘+’, ‘’}*) – The adjustment kind, either additive or multiplicative. Defaults to “+”.

• Adjust step

• interp ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method to use then interpolating the adjustment factors. Defaults to “nearest”.

Pre- and Post-Processing Submodule

xclim.sdba.processing.adapt_freq(ref, sim, *, group, thresh='0 mm d-1')

Adapt frequency of values under thresh of sim, in order to match ref.

This is useful when the dry-day frequency in the simulations is higher than in the references. This function will create new non-null values for sim/hist, so that adjustment factors are less wet-biased. Based on Themeßl et al. [2012].

Parameters:

• ds (xr.Dataset) – With variables : “ref”, Target/reference data, usually observed data, and “sim”, Simulated data.

• dim (str) – Dimension name.

• group (str or Grouper) – Grouping information, see base.Grouper

• thresh (str) – Threshold below which values are considered zero, a quantity with units.

Return type:

tuple[DataArray, DataArray, DataArray]

Returns:

• sim_adj (xr.DataArray) – Simulated data with the same frequency of values under threshold than ref. Adjustment is made group-wise.

• pth (xr.DataArray) – For each group, the smallest value of sim that was not frequency-adjusted. All values smaller were either left as zero values or given a random value between thresh and pth. NaN where frequency adaptation wasn’t needed.

• dP0 (xr.DataArray) – For each group, the percentage of values that were corrected in sim.

Notes

With \(P_0^r\) the frequency of values under threshold \(T_0\) in the reference (ref) and \(P_0^s\) the same for the simulated values, \(\\Delta P_0 = \\frac{P_0^s - P_0^r}{P_0^s}\), when positive, represents the proportion of values under \(T_0\) that need to be corrected.

The correction replaces a proportion \(\\Delta P_0\) of the values under \(T_0\) in sim by a uniform random number between \(T_0\) and \(P_{th}\), where \(P_{th} = F_{ref}^{-1}( F_{sim}( T_0 ) )\) and F(x) is the empirical cumulative distribution function (CDF).

References

Themeßl, Gobiet, and Heinrich [2012]

xclim.sdba.processing.construct_moving_yearly_window(da, window=21, step=1, dim='movingwin')

Construct a moving window DataArray.

Stack windows of da in a new ‘movingwin’ dimension. Windows are always made of full years, so calendar with non-uniform year lengths are not supported.

Windows are constructed starting at the beginning of da, if number of given years is not a multiple of step, then the last year(s) will be missing as a supplementary window would be incomplete.

Parameters:

• da (xr.Dataset) – A DataArray with a time dimension.

• window (int) – The length of the moving window as a number of years.

• step (int) – The step between each window as a number of years.

• dim (str) – The new dimension name. If given, must also be given to unpack_moving_yearly_window.

Returns:

xr.DataArray – A DataArray with a new movingwin dimension and a time dimension with a length of 1 window. This assumes downstream algorithms do not make use of the _absolute_ year of the data. The correct timeseries can be reconstructed with unpack_moving_yearly_window(). The coordinates of movingwin are the first date of the windows.

xclim.sdba.processing.escore(tgt, sim, dims=('variables', 'time'), N=0, scale=False)

Energy score, or energy dissimilarity metric, based on Szekely and Rizzo [2004] and Cannon [2018].

Parameters:

• tgt (xr.DataArray) – Target observations.

• sim (xr.DataArray) – Candidate observations. Must have the same dimensions as tgt.

• dims (sequence of 2 strings) – The name of the dimensions along which the variables and observation points are listed. tgt and sim can have different length along the second one, but must be equal along the first one. The result will keep all other dimensions.

• N (int) – If larger than 0, the number of observations to use in the score computation. The points are taken evenly distributed along obs_dim.

• scale (bool) – Whether to scale the data before computing the score. If True, both arrays as scaled according to the mean and standard deviation of tgt along obs_dim. (std computed with ddof=1 and both statistics excluding NaN values).

Return type:

DataArray

Returns:

xr.DataArray – e-score with dimensions not in dims.

Notes

Explanation adapted from the “energy” R package documentation. The e-distance between two clusters \(C_i\), \(C_j\) (tgt and sim) of size \(n_i,n_j\) proposed by Szekely and Rizzo [2004] is defined by:

\[e(C_i,C_j) = \frac{1}{2}\frac{n_i n_j}{n_i + n_j} \left[2 M_{ij} − M_{ii} − M_{jj}\right]\]

where

\[M_{ij} = \frac{1}{n_i n_j} \sum_{p = 1}^{n_i} \sum_{q = 1}^{n_j} \left\Vert X_{ip} − X{jq} \right\Vert.\]

\(\Vert\cdot\Vert\) denotes Euclidean norm, \(X_{ip}\) denotes the p-th observation in the i-th cluster.

The input scaling and the factor \(\frac{1}{2}\) in the first equation are additions of Cannon [2018] to the metric. With that factor, the test becomes identical to the one defined by Baringhaus and Franz [2004]. This version is tested against values taken from Alex Cannon’s MBC R package [Cannon, 2020].

References

Baringhaus and Franz [2004], Cannon [2018], Cannon [2020], Szekely and Rizzo [2004]

xclim.sdba.processing.from_additive_space(data, lower_bound=None, upper_bound=None, trans=None, units=None)

Transform back to the physical space a variable that was transformed with to_additive_space.

Based on Alavoine and Grenier [2022]. If parameters are not present on the attributes of the data, they must be all given are arguments.

Parameters:

• data (xr.DataArray) – A variable that was transformed by to_additive_space().

• lower_bound (str, optional) – The smallest physical value of the variable, as a Quantity string. The final data will have no value smaller or equal to this bound. If None (default), the sdba_transform_lower attribute is looked up on data.

• upper_bound (str, optional) – The largest physical value of the variable, as a Quantity string. Only relevant for the logit transformation. The final data will have no value larger or equal to this bound. If None (default), the sdba_transform_upper attribute is looked up on data.

• trans ({‘log’, ‘logit’}, optional) – The transformation to use. See notes. If None (the default), the sdba_transform attribute is looked up on data.

• units (str, optional) – The units of the data before transformation to the additive space. If None (the default), the sdba_transform_units attribute is looked up on data.

Returns:

xr.DataArray – The physical variable. Attributes are conserved, even if some might be incorrect. Except units which are taken from sdba_transform_units if available. All sdba_transform* attributes are deleted.

Notes

Given a variable that is not usable in an additive adjustment, to_additive_space() applied a transformation to a space where additive methods are sensible. Given \(Y\) the transformed variable, \(b_-\) the lower physical bound of that variable and \(b_+\) the upper physical bound, two back-transformations are currently implemented to get \(X\), the physical variable.

• log

  \[X = e^{Y} + b_-\]

• logit

  \[X' = \frac{1}{1 + e^{-Y}} X = X * (b_+ - b_-) + b_-\]

See also

to_additive_space

for the original transformation.

References

Alavoine and Grenier [2022]

xclim.sdba.processing.jitter(x, lower=None, upper=None, minimum=None, maximum=None)

Replace values under a threshold and values above another by a uniform random noise.

Warning

Not to be confused with R’s jitter, which adds uniform noise instead of replacing values.

Parameters:

• x (xr.DataArray) – Values.

• lower (str, optional) – Threshold under which to add uniform random noise to values, a quantity with units. If None, no jittering is performed on the lower end.

• upper (str, optional) – Threshold over which to add uniform random noise to values, a quantity with units. If None, no jittering is performed on the upper end.

• minimum (str, optional) – Lower limit (excluded) for the lower end random noise, a quantity with units. If None but lower is not None, 0 is used.

• maximum (str, optional) – Upper limit (excluded) for the upper end random noise, a quantity with units. If upper is not None, it must be given.

Return type:

DataArray

Returns:

xr.DataArray – Same as x but values < lower are replaced by a uniform noise in range (minimum, lower) and values >= upper are replaced by a uniform noise in range [upper, maximum). The two noise distributions are independent.

xclim.sdba.processing.jitter_over_thresh(x, thresh, upper_bnd)

Replace values greater than threshold by a uniform random noise.

Warning

Not to be confused with R’s jitter, which adds uniform noise instead of replacing values.

Parameters:

• x (xr.DataArray) – Values.

• thresh (str) – Threshold over which to add uniform random noise to values, a quantity with units.

• upper_bnd (str) – Maximum possible value for the random noise, a quantity with units.

Return type:

DataArray

Returns:

xr.DataArray

Notes

If thresh is low, this will change the mean value of x.

xclim.sdba.processing.jitter_under_thresh(x, thresh)

Replace values smaller than threshold by a uniform random noise.

Warning

Not to be confused with R’s jitter, which adds uniform noise instead of replacing values.

Parameters:

• x (xr.DataArray) – Values.

• thresh (str) – Threshold under which to add uniform random noise to values, a quantity with units.

Return type:

DataArray

Returns:

xr.DataArray

Notes

If thresh is high, this will change the mean value of x.

xclim.sdba.processing.normalize(data, norm=None, *, group, kind='+')

Normalize an array by removing its mean.

Normalization if performed group-wise and according to kind.

Parameters:

• data (xr.DataArray) – The variable to normalize.

• norm (xr.DataArray, optional) – If present, it is used instead of computing the norm again.

• group (str or Grouper) – Grouping information. See xclim.sdba.base.Grouper for details..

• kind ({‘+’, ‘’}*) – If kind is “+”, the mean is subtracted from the mean and if it is ‘*’, it is divided from the data.

Return type:

tuple[DataArray, DataArray]

Returns:

• xr.DataArray – Groupwise anomaly.

• norm (xr.DataArray) – Mean over each group.

xclim.sdba.processing.reordering(ref, sim, group='time')

Reorders data in sim following the order of ref.

The rank structure of ref is used to reorder the elements of sim along dimension “time”, optionally doing the operation group-wise.

Parameters:

• sim (xr.DataArray) – Array to reorder.

• ref (xr.DataArray) – Array whose rank order sim should replicate.

• group (str) – Grouping information. See xclim.sdba.base.Grouper for details.

Return type:

Dataset

Returns:

xr.Dataset – sim reordered according to ref’s rank order.

References

Cannon [2018]

xclim.sdba.processing.stack_variables(ds, rechunk=True, dim='multivar')

Stack different variables of a dataset into a single DataArray with a new “variables” dimension.

Variable attributes are all added as lists of attributes to the new coordinate, prefixed with “_”. Variables are concatenated in the new dimension in alphabetical order, to ensure coherent behaviour with different datasets.

Parameters:

• ds (xr.Dataset) – Input dataset.

• rechunk (bool) – If True (default), dask arrays are rechunked with variables : -1.

• dim (str) – Name of dimension along which variables are indexed.

Returns:

xr.DataArray – The transformed variable. Attributes are conserved, even if some might be incorrect, except for units, which are replaced with “”. Old units are stored in sdba_transformation_units. A sdba_transform attribute is added, set to the transformation method. sdba_transform_lower and sdba_transform_upper are also set if the requested bounds are different from the defaults.

Array with variables stacked along dim dimension. Units are set to “”.

xclim.sdba.processing.standardize(da, mean=None, std=None, dim='time')

Standardize a DataArray by centering its mean and scaling it by its standard deviation.

Either of both of mean and std can be provided if need be.

Return type:

tuple[DataArray | Dataset, DataArray, DataArray]

Returns:

• out (xr.DataArray or xr.Dataset) – Standardized data.

• mean (xr.DataArray) – Mean.

• std (xr.DataArray) – Standard Deviation.

xclim.sdba.processing.to_additive_space(data, lower_bound, upper_bound=None, trans='log')

Transform a non-additive variable into an additive space by the means of a log or logit transformation.

Based on Alavoine and Grenier [2022].

Parameters:

• data (xr.DataArray) – A variable that can’t usually be bias-adjusted by additive methods.

• lower_bound (str) – The smallest physical value of the variable, excluded, as a Quantity string. The data should only have values strictly larger than this bound.

• upper_bound (str, optional) – The largest physical value of the variable, excluded, as a Quantity string. Only relevant for the logit transformation. The data should only have values strictly smaller than this bound.

• trans ({‘log’, ‘logit’}) – The transformation to use. See notes.

Notes

Given a variable that is not usable in an additive adjustment, this applies a transformation to a space where additive methods are sensible. Given \(X\) the variable, \(b_-\) the lower physical bound of that variable and \(b_+\) the upper physical bound, two transformations are currently implemented to get \(Y\), the additive-ready variable. \(\ln\) is the natural logarithm.

• log

  \[Y = \ln\left( X - b_- \right)\]

  Usually used for variables with only a lower bound, like precipitation (pr, prsn, etc) and daily temperature range (dtr). Both have a lower bound of 0.

• logit

  \[X' = (X - b_-) / (b_+ - b_-) Y = \ln\left(\frac{X'}{1 - X'} \right)\]

  Usually used for variables with both a lower and a upper bound, like relative and specific humidity, cloud cover fraction, etc.

This will thus produce Infinity and NaN values where \(X == b_-\) or \(X == b_+\). We recommend using jitter_under_thresh() and jitter_over_thresh() to remove those issues.

See also

from_additive_space

for the inverse transformation.

jitter_under_thresh

Remove values exactly equal to the lower bound.

jitter_over_thresh

Remove values exactly equal to the upper bound.

References

Alavoine and Grenier [2022]

xclim.sdba.processing.uniform_noise_like(da, low=1e-06, high=0.001)

Return a uniform noise array of the same shape as da.

Noise is uniformly distributed between low and high. Alternative method to jitter_under_thresh for avoiding zeroes.

Return type:

DataArray

xclim.sdba.processing.unpack_moving_yearly_window(da, dim='movingwin', append_ends=True)

Unpack a constructed moving window dataset to a normal timeseries, only keeping the central data.

Unpack DataArrays created with construct_moving_yearly_window() and recreate a timeseries data. If append_ends is False, only keeps the central non-overlapping years. The final timeseries will be (window - step) years shorter than the initial one. If append_ends is True, the time points from first and last windows will be included in the final timeseries.

The time points that are not in a window will never be included in the final timeseries. The window length and window step are inferred from the coordinates.

Parameters:

• da (xr.DataArray) – As constructed by construct_moving_yearly_window().

• dim (str) – The window dimension name as given to the construction function.

• append_ends (bool) – Whether to append the ends of the timeseries If False, the final timeseries will be (window - step) years shorter than the initial one, but all windows will contribute equally. If True, the year before the middle years of the first window and the years after the middle years of the last window are appended to the middle years. The final timeseries will be the same length as the initial timeseries if the windows span the whole timeseries. The time steps that are not in a window will be left out of the final timeseries.

xclim.sdba.processing.unstack_variables(da, dim=None)

Unstack a DataArray created by stack_variables to a dataset.

Parameters:

• da (xr.DataArray) – Array holding different variables along dim dimension.

• dim (str) – Name of dimension along which the variables are stacked. If not specified (default), dim is inferred from attributes of the coordinate.

Returns:

xr.Dataset – Dataset holding each variable in an individual DataArray.

xclim.sdba.processing.unstandardize(da, mean, std)

Rescale a standardized array by performing the inverse operation of standardize.

Detrending Objects Utilities

class xclim.sdba.detrending.LoessDetrend(group='time', kind='+', f=0.2, niter=1, d=0, weights='tricube', equal_spacing=None, skipna=True)

Bases: BaseDetrend

Detrend time series using a LOESS regression.

The fit is a piecewise linear regression. For each point, the contribution of all neighbors is weighted by a bell-shaped curve (gaussian) with parameters sigma (std). The x-coordinate of the DataArray is scaled to [0,1] before the regression is computed.

Parameters:

• group (str or Grouper) – The grouping information. See xclim.sdba.base.Grouper for details. The fit is performed along the group’s main dim.

• kind ({’’, ‘+’}*) – The way the trend is removed or added, either additive or multiplicative.

• d ([0, 1]) – Order of the local regression. Only 0 and 1 currently implemented.

• f (float) – Parameter controlling the span of the weights, between 0 and 1.

• niter (int) – Number of robustness iterations to execute.

• weights ([“tricube”, “gaussian”]) – Shape of the weighting function: “tricube” : a smooth top-hat like curve, f gives the span of non-zero values. “gaussian” : a gaussian curve, f gives the span for 95% of the values.

• skipna (bool) – If True (default), missing values are not included in the loess trend computation and thus are not propagated. The output will have the same missing values as the input.

Notes

LOESS smoothing is computationally expensive. As it relies on a loop on gridpoints, it can be useful to use smaller than usual chunks. Moreover, it suffers from heavy boundary effects. As a rule of thumb, the outermost N * f/2 points should be considered dubious. (N is the number of points along each group)

class xclim.sdba.detrending.MeanDetrend(*, group='time', kind='+', **kwargs)

Bases: BaseDetrend

Simple detrending removing only the mean from the data, quite similar to normalizing.

class xclim.sdba.detrending.NoDetrend(*, group='time', kind='+', **kwargs)

Bases: BaseDetrend

Convenience class for polymorphism. Does nothing.

class xclim.sdba.detrending.PolyDetrend(group='time', kind='+', degree=4, preserve_mean=False)

Bases: BaseDetrend

Detrend time series using a polynomial regression.

Parameters:

• group (Union[str, Grouper]) – The grouping information. See xclim.sdba.base.Grouper for details. The fit is performed along the group’s main dim.

• kind ({’’, ‘+’}*) – The way the trend is removed or added, either additive or multiplicative.

• degree (int) – The order of the polynomial to fit.

• preserve_mean (bool) – Whether to preserve the mean when de/re-trending. If True, the trend has its mean removed before it is used.

class xclim.sdba.detrending.RollingMeanDetrend(group='time', kind='+', win=30, weights=None, min_periods=None)

Bases: BaseDetrend

Detrend time series using a rolling mean.

Parameters:

• group (str or Grouper) – The grouping information. See xclim.sdba.base.Grouper for details. The fit is performed along the group’s main dim.

• kind ({’’, ‘+’}*) – The way the trend is removed or added, either additive or multiplicative.

• win (int) – The size of the rolling window. Units are the steps of the grouped data, which means this detrending is best use with either group=’time’ or group=’time.dayofyear’. Other grouping will have large jumps included within the windows and :py`:class:LoessDetrend might offer a better solution.

• weights (sequence of floats, optional) – Sequence of length win. Defaults to None, which means a flat window.

• min_periods (int, optional) – Minimum number of observations in window required to have a value, otherwise the result is NaN. See xarray.DataArray.rolling(). Defaults to None, which sets it equal to win. Setting both weights and this is not implemented yet.

Notes

As for the LoessDetrend detrending, important boundary effects are to be expected.

Statistical Downscaling and Bias Adjustment Utilities

xclim.sdba.utils.add_cyclic_bounds(da, att, cyclic_coords=True)

Reindex an array to include the last slice at the beginning and the first at the end.

This is done to allow interpolation near the end-points.

Parameters:

• da (xr.DataArray or xr.Dataset) – An array

• att (str) – The name of the coordinate to make cyclic

• cyclic_coords (bool) – If True, the coordinates are made cyclic as well, if False, the new values are guessed using the same step as their neighbour.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – da but with the last element along att prepended and the last one appended.

xclim.sdba.utils.apply_correction(x, factor, kind=None)

Apply the additive or multiplicative correction/adjustment factors.

If kind is not given, default to the one stored in the “kind” attribute of factor.

Return type:

DataArray

xclim.sdba.utils.best_pc_orientation_full(R, Hinv, Rmean, Hmean, hist)

Return best orientation vector for A according to the method of Alavoine and Grenier [2022].

Eigenvectors returned by pc_matrix do not have a defined orientation. Given an inverse transform Hinv, a transform R, the actual and target origins Hmean and Rmean and the matrix of training observations hist, this computes a scenario for all possible orientations and return the orientation that maximizes the Spearman correlation coefficient of all variables. The correlation is computed for each variable individually, then averaged.

This trick is explained in Alavoine and Grenier [2022]. See docstring of sdba.adjustment.PrincipalComponentAdjustment().

Parameters:

• R (np.ndarray) – MxM Matrix defining the final transformation.

• Hinv (np.ndarray) – MxM Matrix defining the (inverse) first transformation.

• Rmean (np.ndarray) – M vector defining the target distribution center point.

• Hmean (np.ndarray) – M vector defining the original distribution center point.

• hist (np.ndarray) – MxN matrix of all training observations of the M variables/sites.

Return type:

ndarray

Returns:

np.ndarray – M vector of orientation correction (1 or -1).

References

Alavoine and Grenier [2022]

xclim.sdba.utils.best_pc_orientation_simple(R, Hinv, val=1000)

Return best orientation vector according to a simple test.

Eigenvectors returned by pc_matrix do not have a defined orientation. Given an inverse transform Hinv and a transform R, this returns the orientation minimizing the projected distance for a test point far from the origin.

This trick is inspired by the one exposed in Hnilica et al. [2017]. For each possible orientation vector, the test point is reprojected and the distance from the original point is computed. The orientation minimizing that distance is chosen.

Parameters:

• R (np.ndarray) – MxM Matrix defining the final transformation.

• Hinv (np.ndarray) – MxM Matrix defining the (inverse) first transformation.

• val (float) – The coordinate of the test point (same for all axes). It should be much greater than the largest furthest point in the array used to define B.

Return type:

ndarray

Returns:

np.ndarray – Mx1 vector of orientation correction (1 or -1).

See also

sdba.adjustment.PrincipalComponentAdjustment

References

Hnilica, Hanel, and Puš [2017]

xclim.sdba.utils.broadcast(grouped, x, *, group='time', interp='nearest', sel=None)

Broadcast a grouped array back to the same shape as a given array.

Parameters:

• grouped (xr.DataArray) – The grouped array to broadcast like x.

• x (xr.DataArray) – The array to broadcast grouped to.

• group (str or Grouper) – Grouping information. See xclim.sdba.base.Grouper for details.

• interp ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method to use,

• sel (dict[str, xr.DataArray]) – Mapping of grouped coordinates to x coordinates (other than the grouping one).

Return type:

DataArray

Returns:

xr.DataArray

xclim.sdba.utils.copy_all_attrs(ds, ref)

Copy all attributes of ds to ref, including attributes of shared coordinates, and variables in the case of Datasets.

xclim.sdba.utils.ecdf(x, value, dim='time')

Return the empirical CDF of a sample at a given value.

Parameters:

• x (array) – Sample.

• value (float) – The value within the support of x for which to compute the CDF value.

• dim (str) – Dimension name.

Return type:

DataArray

Returns:

xr.DataArray – Empirical CDF.

xclim.sdba.utils.ensure_longest_doy(func)

Ensure that selected day is the longest day of year for x and y dims.

Return type:

Callable

xclim.sdba.utils.equally_spaced_nodes(n, eps=None)

Return nodes with n equally spaced points within [0, 1], optionally adding two end-points.

Parameters:

• n (int) – Number of equally spaced nodes.

• eps (float, optional) – Distance from 0 and 1 of added end nodes. If None (default), do not add endpoints.

Return type:

array

Returns:

np.array – Nodes between 0 and 1. Nodes can be seen as the middle points of n equal bins.

Warning

Passing a small eps will effectively clip the scenario to the bounds of the reference on the historical period in most cases. With normal quantile mapping algorithms, this can give strange result when the reference does not show as many extremes as the simulation does.

Notes

For n=4, eps=0 : 0—x——x——x——x—1

xclim.sdba.utils.get_clusters(data, u1, u2, dim='time')

Get cluster count, maximum and position along a given dim.

See get_clusters_1d. Used by adjustment.ExtremeValues.

Parameters:

• data (1D ndarray) – Values to get clusters from.

• u1 (float) – Extreme value threshold, at least one value in the cluster must exceed this.

• u2 (float) – Cluster threshold, values above this can be part of a cluster.

• dim (str) – Dimension name.

Return type:

Dataset

Returns:

xr.Dataset –

With variables,

• nclusters : Number of clusters for each point (with dim reduced), int

• start : First index in the cluster (dim reduced, new cluster), int

• end : Last index in the cluster, inclusive (dim reduced, new cluster), int

• maxpos : Index of the maximal value within the cluster (dim reduced, new cluster), int

• maximum : Maximal value within the cluster (dim reduced, new cluster), same dtype as data.

For start, end and maxpos, -1 means NaN and should always correspond to a NaN in maximum. The length along cluster is half the size of “dim”, the maximal theoretical number of clusters.

xclim.sdba.utils.get_clusters_1d(data, u1, u2)

Get clusters of a 1D array.

A cluster is defined as a sequence of values larger than u2 with at least one value larger than u1.

Parameters:

• data (1D ndarray) – Values to get clusters from.

• u1 (float) – Extreme value threshold, at least one value in the cluster must exceed this.

• u2 (float) – Cluster threshold, values above this can be part of a cluster.

Return type:

tuple[array, array, array, array]

Returns:

(np.array, np.array, np.array, np.array)

References

getcluster of Extremes.jl (Jalbert [2022]).

xclim.sdba.utils.get_correction(x, y, kind)

Return the additive or multiplicative correction/adjustment factors.

Return type:

DataArray

xclim.sdba.utils.interp_on_quantiles(newx, xq, yq, *, group='time', method='linear', extrapolation='constant')

Interpolate values of yq on new values of x.

Interpolate in 2D with scipy.interpolate.griddata() if grouping is used, in 1D otherwise, with scipy.interpolate.interp1d. Any NaNs in xq or yq are removed from the input map. Similarly, NaNs in newx are left NaNs.

Parameters:

• newx (xr.DataArray) – The values at which to evaluate yq. If group has group information, new should have a coordinate with the same name as the group name In that case, 2D interpolation is used.

• xq, yq (xr.DataArray) – Coordinates and values on which to interpolate. The interpolation is done along the “quantiles” dimension if group has no group information. If it does, interpolation is done in 2D on “quantiles” and on the group dimension.

• group (str or Grouper) – The dimension and grouping information. (ex: “time” or “time.month”). Defaults to “time”.

• method ({‘nearest’, ‘linear’, ‘cubic’}) – The interpolation method.

• extrapolation ({‘constant’, ‘nan’}) – The extrapolation method used for values of newx outside the range of xq. See notes.

Notes

Extrapolation methods:

• ‘nan’ : Any value of newx outside the range of xq is set to NaN.

• ‘constant’ : Values of newx smaller than the minimum of xq are set to the first value of yq and those larger than the maximum, set to the last one (first and last non-nan values along the “quantiles” dimension). When the grouping is “time.month”, these limits are linearly interpolated along the month dimension.

xclim.sdba.utils.invert(x, kind=None)

Invert a DataArray either by addition (-x) or by multiplication (1/x).

If kind is not given, default to the one stored in the “kind” attribute of x.

Return type:

DataArray

xclim.sdba.utils.map_cdf(ds, *, y_value, dim)

Return the value in x with the same CDF as y_value in y.

This function is meant to be wrapped in a Grouper.apply.

Parameters:

• ds (xr.Dataset) – Variables: x, Values from which to pick, y, Reference values giving the ranking

• y_value (float, array) – Value within the support of y.

• dim (str) – Dimension along which to compute quantile.

Returns:

array – Quantile of x with the same CDF as y_value in y.

xclim.sdba.utils.map_cdf_1d(x, y, y_value)

Return the value in x with the same CDF as y_value in y.

xclim.sdba.utils.pc_matrix(arr)

Construct a Principal Component matrix.

This matrix can be used to transform points in arr to principal components coordinates. Note that this function does not manage NaNs; if a single observation is null, all elements of the transformation matrix involving that variable will be NaN.

Parameters:

arr (numpy.ndarray or dask.array.Array) – 2D array (M, N) of the M coordinates of N points.

Return type:

ndarray | Array

Returns:

numpy.ndarray or dask.array.Array – MxM Array of the same type as arr.

xclim.sdba.utils.rand_rot_matrix(crd, num=1, new_dim=None)

Generate random rotation matrices.

Rotation matrices are members of the SO(n) group, where n is the matrix size (crd.size). They can be characterized as orthogonal matrices with determinant 1. A square matrix \(R\) is a rotation matrix if and only if \(R^t = R^{−1}\) and \(\mathrm{det} R = 1\).

Parameters:

• crd (xr.DataArray) – 1D coordinate DataArray along which the rotation occurs. The output will be square with the same coordinate replicated, the second renamed to new_dim.

• num (int) – If larger than 1 (default), the number of matrices to generate, stacked along a “matrices” dimension.

• new_dim (str) – Name of the new “prime” dimension, defaults to the same name as crd + “_prime”.

Return type:

DataArray

Returns:

xr.DataArray – float, NxN if num = 1, numxNxN otherwise, where N is the length of crd.

References

Mezzadri [2007]

xclim.sdba.utils.rank(da, dim='time', pct=False)

Ranks data along a dimension.

Replicates xr.DataArray.rank but as a function usable in a Grouper.apply(). Xarray’s docstring is below:

Equal values are assigned a rank that is the average of the ranks that would have been otherwise assigned to all the values within that set. Ranks begin at 1, not 0. If pct, computes percentage ranks, ranging from 0 to 1.

Parameters:

• da (xr.DataArray) – Source array.

• dim (str, hashable) – Dimension over which to compute rank.

• pct (bool, optional) – If True, compute percentage ranks, otherwise compute integer ranks. Percentage ranks range from 0 to 1, in opposition to xarray’s implementation, where they range from 1/N to 1.

Return type:

DataArray

Returns:

DataArray – DataArray with the same coordinates and dtype ‘float64’.

Notes

The bottleneck library is required. NaNs in the input array are returned as NaNs.

See also

xarray.DataArray.rank

class xclim.sdba.base.Grouper(group, window=1, add_dims=None)

Create the Grouper object.

Parameters:

• group (str) – The usual grouping name as xarray understands it. Ex: “time.month” or “time”. The dimension name before the dot is the “main dimension” stored in Grouper.dim and the property name after is stored in Grouper.prop.

• window (int) – If larger than 1, a centered rolling window along the main dimension is created when grouping data. Units are the sampling frequency of the data along the main dimension.

• add_dims (Optional[Union[Sequence[str], str]]) – Additional dimensions that should be reduced in grouping operations. This behaviour is also controlled by the main_only parameter of the apply method. If any of these dimensions are absent from the DataArrays, they will be omitted.

apply(func, da, main_only=False, **kwargs)

Apply a function group-wise on DataArrays.

Parameters:

• func (Callable or str) – The function to apply to the groups, either a callable or a xr.core.groupby.GroupBy method name as a string. The function will be called as func(group, dim=dims, **kwargs). See main_only for the behaviour of dims.

• da (xr.DataArray or dict[str, xr.DataArray] or xr.Dataset) – The DataArray on which to apply the function. Multiple arrays can be passed through a dictionary. A dataset will be created before grouping.

• main_only (bool) – Whether to call the function with the main dimension only (if True) or with all grouping dims (if False, default) (including the window and dimensions given through add_dims). The dimensions used are also written in the “group_compute_dims” attribute. If all the input arrays are missing one of the ‘add_dims’, it is silently omitted.

• **kwargs – Other keyword arguments to pass to the function.

Returns:

DataArray or Dataset – Attributes “group”, “group_window” and “group_compute_dims” are added.

If the function did not reduce the array:

• The output is sorted along the main dimension.

• The output is rechunked to match the chunks on the input If multiple inputs with differing chunking were given as inputs, the chunking with the smallest number of chunks is used.

If the function reduces the array:

• If there is only one group, the singleton dimension is squeezed out of the output

• The output is rechunked as to have only 1 chunk along the new dimension.

Notes

For the special case where a Dataset is returned, but only some of its variable where reduced by the grouping, xarray’s GroupBy.map will broadcast everything back to the ungrouped dimensions. To overcome this issue, function may add a “_group_apply_reshape” attribute set to True on the variables that should be reduced and these will be re-grouped by calling da.groupby(self.name).first().

property freq

Format a frequency string corresponding to the group.

For use with xarray’s resampling functions.

classmethod from_kwargs(**kwargs)

Parameterize groups using kwargs.

get_coordinate(ds=None)

Return the coordinate as in the output of group.apply.

Currently, only implemented for groupings with prop == month or dayofyear. For prop == dayfofyear, a ds (Dataset or DataArray) can be passed to infer the max day of year from the available years and calendar.

get_index(da, interp=None)

Return the group index of each element along the main dimension.

Parameters:

• da (xr.DataArray or xr.Dataset) – The input array/dataset for which the group index is returned. It must have Grouper.dim as a coordinate.

• interp (bool, optional) – If True, the returned index can be used for interpolation. Only value for month grouping, where integer values represent the middle of the month, all other days are linearly interpolated in between.

Returns:

xr.DataArray – The index of each element along Grouper.dim. If Grouper.dim is time and Grouper.prop is None, a uniform array of True is returned. If Grouper.prop is a time accessor (month, dayofyear, etc), an numerical array is returned, with a special case of month and interp=True. If Grouper.dim is not time, the dim is simply returned.

group(da=None, main_only=False, **das)

Return a xr.core.groupby.GroupBy object.

More than one array can be combined to a dataset before grouping using the das kwargs. A new window dimension is added if self.window is larger than 1. If Grouper.dim is ‘time’, but ‘prop’ is None, the whole array is grouped together.

When multiple arrays are passed, some of them can be grouped along the same group as self. They are broadcast, merged to the grouping dataset and regrouped in the output.

property prop_name

Create a significant name for the grouping.

Numba-accelerated Utilities

xclim.sdba.nbutils.quantile(da, q, dim)

Compute the quantiles from a fixed list q.

xclim.sdba.nbutils.remove_NaNs(x)

Remove NaN values from series.

xclim.sdba.nbutils.vecquantiles(da, rnk, dim)

For when the quantile (rnk) is different for each point.

da and rnk must share all dimensions but dim.

LOESS Smoothing Submodule

xclim.sdba.loess.loess_smoothing(da, dim='time', d=1, f=0.5, niter=2, weights='tricube', equal_spacing=None, skipna=True)

Locally weighted regression in 1D: fits a nonparametric regression curve to a scatter plot.

Returns a smoothed curve along given dimension. The regression is computed for each point using a subset of neighbouring points as given from evaluating the weighting function locally. Follows the procedure of Cleveland [1979].

Parameters:

• da (xr.DataArray) – The data to smooth using the loess approach.

• dim (str) – Name of the dimension along which to perform the loess.

• d ([0, 1]) – Degree of the local regression.

• f (float) – Parameter controlling the shape of the weight curve. Behavior depends on the weighting function, but it usually represents the span of the weighting function in reference to x-coordinates normalized from 0 to 1.

• niter (int) – Number of robustness iterations to execute.

• weights ([“tricube”, “gaussian”] or callable) – Shape of the weighting function, see notes. The user can provide a function or a string: “tricube” : a smooth top-hat like curve. “gaussian” : a gaussian curve, f gives the span for 95% of the values.

• equal_spacing (bool, optional) – Whether to use the equal spacing optimization. If None (the default), it is activated only if the x-axis is equally-spaced. When activated, dx = x[1] - x[0].

• skipna (bool) – If True (default), skip missing values (as marked by NaN). The output will have the same missing values as the input.

Notes

As stated in Cleveland [1979], the weighting function \(W(x)\) should respect the following conditions:

• \(W(x) > 0\) for \(|x| < 1\)

• \(W(-x) = W(x)\)

• \(W(x)\) is non-increasing for \(x \ge 0\)

• \(W(x) = 0\) for \(|x| \ge 0\)

If a Callable is provided, it should only accept the 1D np.ndarray \(x\) which is an absolute value function going from 1 to 0 to 1 around \(x_i\), for all values where \(x - x_i < h_i\) with \(h_i\) the distance of the rth nearest neighbor of \(x_i\), \(r = f * size(x)\).

References

Cleveland [1979]

Code adapted from: Gramfort [2015]

Properties Submodule

SDBA diagnostic tests are made up of statistical properties and measures. Properties are calculated on both simulation and reference datasets. They collapse the time dimension to one value.

This framework for the diagnostic tests was inspired by the VALUE project. Statistical Properties is the xclim term for ‘indices’ in the VALUE project.

xclim.sdba.properties.acf(da='da', *, lag=1, group='time.season', ds=None)

Autocorrelation. (realm: generic)

Autocorrelation with a lag over a time resolution and averaged over all years.

Based on indice _acf().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• lag (number) – Lag. Default : 1.

• group ({‘time.season’, ‘time.month’}) – Grouping of the output. E.g. If ‘time.month’, the autocorrelation is calculated over each month separately for all years. Then, the autocorrelation for all Jan/Feb/… is averaged over all years, giving 12 outputs for each grid point. Default : time.season.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

acf (DataArray) – Lag-{lag} autocorrelation of the variable over a {group.prop} and averaged over all years.

References

Alavoine and Grenier [2022]

xclim.sdba.properties.annual_cycle_amplitude(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=absamp.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_amplitude (DataArray) – {stat} of the annual cycle., with additional attributes: cell_methods: time: mean time: range

xclim.sdba.properties.annual_cycle_asymmetry(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=asymmetry.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_asymmetry (DataArray) – {stat} of the annual cycle. [yr]

xclim.sdba.properties.annual_cycle_maximum(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=max.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_maximum (DataArray) – {stat} of the annual cycle., with additional attributes: cell_methods: time: mean time: max

xclim.sdba.properties.annual_cycle_minimum(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=min.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_minimum (DataArray) – {stat} of the annual cycle., with additional attributes: cell_methods: time: mean time: min

xclim.sdba.properties.annual_cycle_phase(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=phase.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_phase (DataArray) – {stat} of the annual cycle., with additional attributes: cell_methods: time: range

xclim.sdba.properties.corr_btw_var(da1='da1', da2='da2', *, corr_type='Spearman', output='correlation', group='time', ds=None)

Correlation between two variables. (realm: generic)

Spearman or Pearson correlation coefficient between two variables at the time resolution.

Based on indice _corr_btw_var().

Parameters:

• da1 (str or DataArray) – First variable on which to calculate the diagnostic. Default : ds.da1.

• da2 (str or DataArray) – Second variable on which to calculate the diagnostic. Default : ds.da2.

• corr_type ({‘Spearman’, ‘Pearson’}) – Type of correlation to calculate. Default : Spearman.

• output ({‘pvalue’, ‘correlation’}) – Wheter to return the correlation coefficient or the p-value. Default : correlation.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. Eg. For ‘time.month’, the correlation would be calculated on each month separately, but with all the years together. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

corr_btw_var (DataArray) – {corr_type} correlation coefficient

xclim.sdba.properties.decorrelation_length(da='da', *, radius=300, thresh=0.5, dims=None, bins=100, group='time', ds=None)

Decorrelation length. (realm: generic)

Distance from a grid cell where the correlation with its neighbours goes below the threshold. A correlogram is calculated for each grid cell following the method from xclim.sdba.properties.spatial_correlogram. Then, we find the first bin closest to the correlation threshold.

Based on indice _decorrelation_length().

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• radius (Any) – Radius (in km) defining the region where correlations will be calculated between a point and its neighbours. Default : 300.

• thresh (Any) – Threshold correlation defining decorrelation. The decorrelation length is defined as the center of the distance bin that has a correlation closest to this threshold. Default : 0.5.

• dims (Any) – Name of the spatial dimensions. Once these are stacked, the longitude and latitude coordinates must be 1D. Default : None.

• bins (Any) – Same as argument bins from scipy.stats.binned_statistic(). If given as a scalar, the equal-width bin limits from 0 to radius are generated here (instead of letting scipy do it) to improve performance. Default : 100.

• group (Any) – Useless for now. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

decorrelation_length (DataArray) – Decorrelation length.

Notes

Calculating this property requires a lot of memory. It will not work with large datasets.

xclim.sdba.properties.first_eof(da='da', *, dims=None, kind='+', thresh='1 mm/d', group='time', ds=None)

First Empirical Orthogonal Function. (realm: generic)

Through principal component analysis (PCA), compute the predominant empirical orthogonal function. The temporal dimension is reduced. The Eof is multiplied by the sign of its mean to ensure coherent signs as much as possible. Needs the eofs package to run. Based on an idea from [Vrac, 2018], using an implementation from [Dawson, 2016].

Based on indice _first_eof().

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• dims (Any) – Name of the spatial dimensions. If None (default), all dimensions except “time” are used. Default : None.

• kind ({‘+’, ‘’}*) – Variable “kind”. If multiplicative, the zero values are set to very small values and the PCA is performed over the logarithm of the data. Default : +.

• thresh (Any) – If kind is multiplicative, this is the “zero” threshold passed to xclim.sdba.processing.jitter_under_thresh(). Default : 1 mm/d.

• group (Any) – Useless for now. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

first_eof (DataArray) – First empirical orthogonal function

xclim.sdba.properties.mean(da='da', *, group='time', ds=None)

Mean. (realm: generic)

Mean over all years at the time resolution.

Based on indice _mean().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. E.g. If ‘time.month’, the temporal average is performed separately for each month. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mean (DataArray) – Mean of the variable., with additional attributes: cell_methods: time: mean

xclim.sdba.properties.mean_annual_phase(da='da', *, window=31, group='time', ds=None)

Annual range statistics. (realm: generic)

Compute a statistic on each year of data and return the interannual average. This is similar to the annual cycle, but with the statistic and average operations inverted.

Based on indice _annual_statistic(). With injected parameters: stat=phase.

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mean_annual_phase (DataArray) – Average annual {stat}.

xclim.sdba.properties.mean_annual_range(da='da', *, window=31, group='time', ds=None)

Annual range statistics. (realm: generic)

Compute a statistic on each year of data and return the interannual average. This is similar to the annual cycle, but with the statistic and average operations inverted.

Based on indice _annual_statistic(). With injected parameters: stat=absamp.

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mean_annual_range (DataArray) – Average annual {stat}.

xclim.sdba.properties.mean_annual_relative_range(da='da', *, window=31, group='time', ds=None)

Annual range statistics. (realm: generic)

Compute a statistic on each year of data and return the interannual average. This is similar to the annual cycle, but with the statistic and average operations inverted.

Based on indice _annual_statistic(). With injected parameters: stat=relamp.

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mean_annual_relative_range (DataArray) – Average annual {stat}. [%]

xclim.sdba.properties.quantile(da='da', *, q=0.98, group='time', ds=None)

Quantile. (realm: generic)

Returns the quantile q of the distribution of the variable over all years at the time resolution.

Based on indice _quantile().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• q (number) – Quantile to be calculated. Should be between 0 and 1. Default : 0.98.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. E.g. If ‘time.month’, the quantile is computed separately for each month. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

quantile (DataArray) – Quantile {q} of the variable.

xclim.sdba.properties.relative_annual_cycle_amplitude(da='da', *, window=31, group='time', ds=None)

Annual cycle statistics. (realm: generic)

A daily climatology is calculated and optionnaly smoothed with a (circular) moving average. The requested statistic is returned.

Based on indice _annual_cycle(). With injected parameters: stat=relamp.

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• window (number) – Size of the window for the moving average filtering. Deactivate this feature by passing window = 1. Default : 31.

• group (Any) – Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

relative_annual_cycle_amplitude (DataArray) – {stat} of the annual cycle. [%], with additional attributes: cell_methods: time: mean time: range

xclim.sdba.properties.relative_frequency(da='da', *, op='>=', thresh='1 mm d-1', group='time', ds=None)

Relative Frequency. (realm: generic)

Relative Frequency of days with variable respecting a condition (defined by an operation and a threshold) at the time resolution. The relative frequency is the number of days that satisfy the condition divided by the total number of days.

Based on indice _relative_frequency().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• op ({‘>’, ‘<=’, ‘<’, ‘>=’}) – Operation to verify the condition. The condition is variable {op} threshold. Default : >=.

• thresh (str) – Threshold on which to evaluate the condition. Default : 1 mm d-1.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping on the output. Eg. For ‘time.month’, the relative frequency would be calculated on each month, with all years included. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

relative_frequency (DataArray) – Relative frequency of values {op} {thresh}.

xclim.sdba.properties.return_value(da='da', *, period=20, op='max', method='ML', group='time', ds=None)

Return value. (realm: generic)

Return the value corresponding to a return period. On average, the return value will be exceeded (or not exceed for op=’min’) every return period (e.g. 20 years). The return value is computed by first extracting the variable annual maxima/minima, fitting a statistical distribution to the maxima/minima, then estimating the percentile associated with the return period (eg. 95th percentile (1/20) for 20 years)

Based on indice _return_value().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• period (number) – Return period. Number of years over which to check if the value is exceeded (or not for op=’min’). Default : 20.

• op ({‘max’, ‘min’}) – Whether we are looking for a probability of exceedance (‘max’, right side of the distribution) or a probability of non-exceedance (min, left side of the distribution). Default : max.

• method ({‘ML’, ‘PWM’}) – Fitting method, either maximum likelihood (ML) or probability weighted moments (PWM), also called L-Moments. The PWM method is usually more robust to outliers. Default : ML.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. A distribution of the extremes is done for each group. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

return_value (DataArray) – {period}-{group.prop_name} {op} return level of the variable.

xclim.sdba.properties.skewness(da='da', *, group='time', ds=None)

Skewness. (realm: generic)

Skewness of the distribution of the variable over all years at the time resolution.

Based on indice _skewness().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. E.g. If ‘time.month’, the skewness is performed separately for each month. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

skewness (DataArray) – Skewness of the variable.

xclim.sdba.properties.spatial_correlogram(da='da', *, dims=None, bins=100, group='time', method=1, ds=None)

Spatial correlogram. (realm: generic)

Compute the pairwise spatial correlations (Spearman) and averages them based on the pairwise distances. This collapses the spatial and temporal dimensions and returns a distance bins dimension. Needs coordinates for longitude and latitude. This property is heavy to compute and it will need to create a NxN array in memory (outside of dask), where N is the number of spatial points. There are shortcuts for all-nan time-slices or spatial points, but scipy’s nan-omitting algorithm is extremely slow, so the presence of any lone NaN will increase the computation time. Based on an idea from [François et al., 2020].

Based on indice _spatial_correlogram().

Parameters:

• da (str or DataArray) – Data. Default : ds.da.

• dims (Any) – Name of the spatial dimensions. Once these are stacked, the longitude and latitude coordinates must be 1D. Default : None.

• bins (Any) – Same as argument bins from xarray.DataArray.groupby_bins(). If given as a scalar, the equal-width bin limits are generated here (instead of letting xarray do it) to improve performance. Default : 100.

• group (Any) – Useless for now. Default : time.

• method (Any) – Default : 1.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

spatial_correlogram (DataArray) – Inter-site correlogram as a function of distance.

xclim.sdba.properties.spell_length_distribution(da='da', *, method='amount', op='>=', thresh='1 mm d-1', stat='mean', group='time', resample_before_rl=True, ds=None)

Spell length distribution. (realm: generic)

Statistic of spell length distribution when the variable respects a condition (defined by an operation, a method and a threshold).

Based on indice _spell_length_distribution().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• method ({‘amount’, ‘quantile’}) – Method to choose the threshold. ‘amount’: The threshold is directly the quantity in {thresh}. It needs to have the same units as {da}. ‘quantile’: The threshold is calculated as the quantile {thresh} of the distribution. Default : amount.

• op ({‘>’, ‘<=’, ‘<’, ‘>=’}) – Operation to verify the condition for a spell. The condition for a spell is variable {op} threshold. Default : >=.

• thresh (str) – Threshold on which to evaluate the condition to have a spell. Str with units if the method is “amount”. Float of the quantile if the method is “quantile”. Default : 1 mm d-1.

• stat ({‘max’, ‘min’, ‘mean’}) – Statistics to apply to the resampled input at the {group} (e.g. 1-31 Jan 1980) and then over all years (e.g. Jan 1980-2010) Default : mean.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. E.g. If ‘time.month’, the spell lengths are coputed separately for each month. Default : time.

• resample_before_rl (boolean) – Determines if the resampling should take place before or after the run length encoding (or a similar algorithm) is applied to runs. Default : True.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

spell_length_distribution (DataArray) – {stat} of spell length distribution when the variable is {op} the {method} {thresh}.

xclim.sdba.properties.transition_probability(da='da', *, initial_op='>=', final_op='>=', thresh='1 mm d-1', group='time', ds=None)

Transition probability. (realm: generic)

Probability of transition from the initial state to the final state. The states are booleans comparing the value of the day to the threshold with the operator.

Based on indice _transition_probability().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• initial_op ({‘<’, ‘==’, ‘eq’, ‘gt’, ‘ge’, ‘ne’, ‘le’, ‘!=’, ‘>’, ‘>=’, ‘<=’, ‘lt’}) – Operation to verify the condition for the initial state. The condition is variable {op} threshold. Default : >=.

• final_op ({‘<’, ‘==’, ‘eq’, ‘gt’, ‘ge’, ‘ne’, ‘le’, ‘!=’, ‘>’, ‘>=’, ‘<=’, ‘lt’}) – Operation to verify the condition for the final state. The condition is variable {op} threshold. Default : >=.

• thresh (str) – Threshold on which to evaluate the condition. Default : 1 mm d-1.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping on the output. e.g. For “time.month”, the transition probability would be calculated on each month, with all years included. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

transition_probability (DataArray) – Transition probability of values {initial_op} {thresh} to values {final_op} {thresh}.

xclim.sdba.properties.trend(da='da', *, output='slope', group='time', ds=None)

Linear Trend. (realm: generic)

The data is averaged over each time resolution and the inter-annual trend is returned. This function will rechunk along the grouping dimension.

Based on indice _trend().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• output ({‘slope’, ‘pvalue’}) – Attributes of the linear regression to return. ‘slope’ is the slope of the regression line. ‘pvalue’ is for a hypothesis test whose null hypothesis is that the slope is zero, using Wald Test with t-distribution of the test statistic. Default : slope.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping on the output. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

trend (DataArray) – {output} of the interannual linear trend.

xclim.sdba.properties.var(da='da', *, group='time', ds=None)

Variance. (realm: generic)

Variance of the variable over all years at the time resolution.

Based on indice _var().

Parameters:

• da (str or DataArray) – Variable on which to calculate the diagnostic. Default : ds.da.

• group ({‘time’, ‘time.month’, ‘time.season’}) – Grouping of the output. E.g. If ‘time.month’, the variance is performed separately for each month. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

var (DataArray) – Variance of the variable., with additional attributes: cell_methods: time: var

Measures Submodule

SDBA diagnostic tests are made up of properties and measures. Measures compare adjusted simulations to a reference, through statistical properties or directly. This framework for the diagnostic tests was inspired by the VALUE project.

class xclim.sdba.measures.StatisticalPropertyMeasure(**kwds)

Base indicator class for statistical properties that include the comparison measure, used when validating bias-adjusted outputs.

StatisticalPropertyMeasure objects combine the functionalities of xclim.sdba.properties.StatisticalProperty and xclim.sdba.properties.StatisticalMeasure.

Statistical properties usually reduce the time dimension and sometimes more dimensions (for example in spatial properties), sometimes adding a grouping dimension according to the passed value of group (e.g.: group=’time.month’ means the loss of the time dimension and the addition of a month one).

Statistical measures usually take two arrays as input: “sim” and “ref”, “sim” being measured against “ref”.

Statistical property-measures are generally unit-generic. If the inputs have different units, “sim” is converted to match “ref”.

allowed_groups = None

A list of allowed groupings. A subset of dayofyear, week, month, season or group. The latter stands for no temporal grouping.

aspect = None

marginal, temporal, multivariate or spatial.

Type:

The aspect the statistical property studies

xclim.sdba.measures.annual_cycle_correlation(sim='sim', ref='ref', *, window=15, group='time', ds=None)

Annual cycle correlation. (realm: generic)

Pearson correlation coefficient between the smooth day-of-year averaged annual cycles of the simulation and the reference. In the smooth day-of-year averaged annual cycles, each day-of-year is averaged over all years and over a window of days around that day.

Based on indice _annual_cycle_correlation().

Parameters:

• sim (str or DataArray) – data from the simulation (a time-series for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (a time-series for each grid-point) Default : ds.ref.

• window (number) – Size of window around each day of year around which to take the mean. E.g. If window=31, Jan 1st is averaged over from December 17th to January 16th. Default : 15.

• group (Any) – Compute the property and measure for each temporal groups individually. Currently not implemented. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

annual_cycle_correlation (DataArray) – Annual cycle correlation

xclim.sdba.measures.bias(sim='sim', ref='ref', *, ds=None)

Bias. (realm: generic)

The bias is the simulation minus the reference.

Based on indice _bias().

Parameters:

• sim (str or DataArray) – data from the simulation (one value for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (one value for each grid-point) Default : ds.ref.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

bias (DataArray) – Absolute bias

xclim.sdba.measures.circular_bias(sim='sim', ref='ref', *, ds=None)

Circular bias. (realm: generic)

Bias considering circular time series. E.g. The bias between doy 365 and doy 1 is 364, but the circular bias is -1.

Based on indice _circular_bias().

Parameters:

• sim (str or DataArray) – data from the simulation (one value for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (one value for each grid-point) Default : ds.ref.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

circular_bias (DataArray) – Circular bias [days]

xclim.sdba.measures.mae(sim='sim', ref='ref', *, group='time', ds=None)

Mean absolute error. (realm: generic)

The mean absolute error on the time dimension between the simulation and the reference.

Based on indice _mae().

Parameters:

• sim (str or DataArray) – data from the simulation (a time-series for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (a time-series for each grid-point) Default : ds.ref.

• group (Any) – Compute the property and measure for each temporal groups individually. Currently not implemented. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mae (DataArray) – Mean absolute error, with additional attributes: cell_methods: time: mean

xclim.sdba.measures.ratio(sim='sim', ref='ref', *, ds=None)

Ratio. (realm: generic)

The ratio is the quotient of the simulation over the reference.

Based on indice _ratio().

Parameters:

• sim (str or DataArray) – data from the simulation (one value for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (one value for each grid-point) Default : ds.ref.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

ratio (DataArray) – Ratio

xclim.sdba.measures.relative_bias(sim='sim', ref='ref', *, ds=None)

Relative Bias. (realm: generic)

The relative bias is the simulation minus reference, divided by the reference.

Based on indice _relative_bias().

Parameters:

• sim (str or DataArray) – data from the simulation (one value for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (one value for each grid-point) Default : ds.ref.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

relative_bias (DataArray) – Relative bias

xclim.sdba.measures.rmse(sim='sim', ref='ref', *, group='time', ds=None)

Root mean square error. (realm: generic)

The root mean square error on the time dimension between the simulation and the reference.

Based on indice _rmse().

Parameters:

• sim (str or DataArray) – Data from the simulation (a time-series for each grid-point) Default : ds.sim.

• ref (str or DataArray) – Data from the reference (observations) (a time-series for each grid-point) Default : ds.ref.

• group (Any) – Compute the property and measure for each temporal groups individually. Currently not implemented. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

rmse (DataArray) – Root mean square error, with additional attributes: cell_methods: time: mean

xclim.sdba.measures.scorr(sim='sim', ref='ref', *, dims=None, group='time', ds=None)

Spatial correllogram. (realm: generic)

Compute the inter-site correlations of each array, compute the difference in correlations and sum. Taken from Vrac (2018). The spatial and temporal dimensions are reduced.

Based on indice _scorr().

Parameters:

• sim (str or DataArray) – data from the simulation (a time-series for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (a time-series for each grid-point) Default : ds.ref.

• dims (Any) – Name of the spatial dimensions. If None (default), all dimensions except ‘time’ are used. Default : None.

• group (Any) – Compute the property and measure for each temporal groups individually. Currently not implemented. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

Scorr (DataArray) – Sum of the inter-site correlation differences.

xclim.sdba.measures.taylordiagram(sim='sim', ref='ref', *, dim='time', group='time', ds=None)

Taylor diagram. (realm: generic)

Compute the respective standard deviations of a simulation and a reference array, as well as the Pearson correlation coefficient between both, all necessary parameters to plot points on a Taylor diagram.

Based on indice _taylordiagram().

Parameters:

• sim (str or DataArray) – data from the simulation (a time-series for each grid-point) Default : ds.sim.

• ref (str or DataArray) – data from the reference (observations) (a time-series for each grid-point) Default : ds.ref.

• dim (str) – Dimension across which the correlation and standard deviation should be computed. Default : time.

• group (Any) – Compute the property and measure for each temporal groups individually. Currently not implemented. Default : time.

• ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

taylordiagram (DataArray) – Standard deviations of sim, ref and correlation coefficient between both.

Spatial Analogues Module

class xclim.analog.spatial_analogs(target, candidates, dist_dim='time', method='kldiv', **kwargs)

Compute dissimilarity statistics between target points and candidate points.

Spatial analogues based on the comparison of climate indices. The algorithm compares the distribution of the reference indices with the distribution of spatially distributed candidate indices and returns a value measuring the dissimilarity between both distributions over the candidate grid.

Parameters:

• target (xr.Dataset) – Dataset of the target indices. Only indice variables should be included in the dataset’s data_vars. They should have only the dimension(s) dist_dim `in common with `candidates.

• candidates (xr.Dataset) – Dataset of the candidate indices. Only indice variables should be included in the dataset’s data_vars.

• dist_dim (str) – The dimension over which the distributions are constructed. This can be a multi-index dimension.

• method ({‘seuclidean’, ‘nearest_neighbor’, ‘zech_aslan’, ‘kolmogorov_smirnov’, ‘friedman_rafsky’, ‘kldiv’}) – Which method to use when computing the dissimilarity statistic.

• **kwargs – Any other parameter passed directly to the dissimilarity method.

Returns:

xr.DataArray – The dissimilarity statistic over the union of candidates’ and target’s dimensions. The range depends on the method.

xclim.analog.friedman_rafsky(x, y)

Compute a dissimilarity metric based on the Friedman-Rafsky runs statistics.

The algorithm builds a minimal spanning tree (the subset of edges connecting all points that minimizes the total edge length) then counts the edges linking points from the same distribution. This method is scale-dependent.

Parameters:

• x (np.ndarray (n,d)) – Reference sample.

• y (np.ndarray (m,d)) – Candidate sample.

Return type:

float

Returns:

float – Friedman-Rafsky dissimilarity metric ranging from 0 to (m+n-1)/(m+n).

References

Friedman and Rafsky [1979]

xclim.analog.kldiv(x, y, *, k=1)

Compute the Kullback-Leibler divergence between two multivariate samples.

where \(r_k(x_i)\) and \(s_k(x_i)\) are, respectively, the euclidean distance to the kth neighbour of \(x_i\) in the x array (excepting \(x_i\)) and in the y array. This method is scale-dependent.

Parameters:

• x (np.ndarray (n,d)) – Samples from distribution P, which typically represents the true distribution (reference).

• y (np.ndarray (m,d)) – Samples from distribution Q, which typically represents the approximate distribution (candidate)

• k (int or sequence) – The kth neighbours to look for when estimating the density of the distributions. Defaults to 1, which can be noisy.

Return type:

Union[float, Sequence[float]]

Returns:

float or sequence – The estimated Kullback-Leibler divergence D(P||Q) computed from the distances to the kth neighbour.

Notes

In information theory, the Kullback–Leibler divergence [Perez-Cruz, 2008] is a non-symmetric measure of the difference between two probability distributions P and Q, where P is the “true” distribution and Q an approximation. This nuance is important because \(D(P||Q)\) is not equal to \(D(Q||P)\).

For probability distributions P and Q of a continuous random variable, the K–L divergence is defined as:

\[D_{KL}(P||Q) = \int p(x) \log\left(\frac{p(x)}{q(x)}\right) dx\]

This formula assumes we have a representation of the probability densities \(p(x)\) and \(q(x)\). In many cases, we only have samples from the distribution, and most methods first estimate the densities from the samples and then proceed to compute the K-L divergence. In Perez-Cruz [2008], the author proposes an algorithm to estimate the K-L divergence directly from the sample using an empirical CDF. Even though the CDFs do not converge to their true values, the paper proves that the K-L divergence almost surely does converge to its true value.

References

Perez-Cruz [2008]

xclim.analog.kolmogorov_smirnov(x, y)

Compute the Kolmogorov-Smirnov statistic applied to two multivariate samples as described by Fasano and Franceschini.

This method is scale-dependent.

Parameters:

• x (np.ndarray (n,d)) – Reference sample.

• y (np.ndarray (m,d)) – Candidate sample.

Return type:

float

Returns:

float – Kolmogorov-Smirnov dissimilarity metric ranging from 0 to 1.

References

Fasano and Franceschini [1987]

xclim.analog.nearest_neighbor(x, y)

Compute a dissimilarity metric based on the number of points in the pooled sample whose nearest neighbor belongs to the same distribution.

This method is scale-invariant.

Parameters:

• x (np.ndarray (n,d)) – Reference sample.

• y (np.ndarray (m,d)) – Candidate sample.

Return type:

ndarray

Returns:

float – Nearest-Neighbor dissimilarity metric ranging from 0 to 1.

References

Henze [1988]

xclim.analog.seuclidean(x, y)

Compute the Euclidean distance between the mean of a multivariate candidate sample with respect to the mean of a reference sample.

This method is scale-invariant.

Parameters:

• x (np.ndarray (n,d)) – Reference sample.

• y (np.ndarray (m,d)) – Candidate sample.

Return type:

float

Returns:

float – Standardized Euclidean Distance between the mean of the samples ranging from 0 to infinity.

Notes

This metric considers neither the information from individual points nor the standard deviation of the candidate distribution.

References

Veloz, Williams, Lorenz, Notaro, Vavrus, and Vimont [2012]

xclim.analog.szekely_rizzo(x, y, *, standardize=True)

Compute the Székely-Rizzo energy distance dissimilarity metric based on an analogy with Newton’s gravitational potential energy.

This method is scale-invariant when standardize=True (default), scale-dependent otherwise.

Parameters:

• x (ndarray (n,d)) – Reference sample.

• y (ndarray (m,d)) – Candidate sample.

• standardize (bool) – If True (default), the standardized euclidean norm is used, instead of the conventional one.

Return type:

float

Returns:

float – Székely-Rizzo’s energy distance dissimilarity metric ranging from 0 to infinity.

Notes

The e-distance between two variables \(X\), \(Y\) (target and candidates) of sizes \(n,d\) and \(m,d\) proposed by Szekely and Rizzo [2004] is defined by:

\[e(X, Y) = \frac{n m}{n + m} \left[2\phi_{xy} − \phi_{xx} − \phi_{yy} \right]\]

where

\[\begin{split}\phi_{xy} &= \frac{1}{n m} \sum_{i = 1}^n \sum_{j = 1}^m \left\Vert X_i − Y_j \right\Vert \\ \phi_{xx} &= \frac{1}{n^2} \sum_{i = 1}^n \sum_{j = 1}^n \left\Vert X_i − X_j \right\Vert \\ \phi_{yy} &= \frac{1}{m^2} \sum_{i = 1}^m \sum_{j = 1}^m \left\Vert X_i − Y_j \right\Vert \\\end{split}\]

and where \(\Vert\cdot\Vert\) denotes the Euclidean norm, \(X_i\) denotes the i-th observation of \(X\). When standardized=False, this corresponds to the \(T\) test of Rizzo and Székely [2016] (p. 28) and to the eqdist.e function of the energy R package (with two samples) and gives results twice as big as xclim.sdba.processing.escore(). The standardization was added following the logic of [Grenier et al., 2013] to make the metric scale-invariant.

References

Grenier, Parent, Huard, Anctil, and Chaumont [2013], Rizzo and Székely [2016], Szekely and Rizzo [2004]

xclim.analog.zech_aslan(x, y, *, dmin=1e-12)

Compute a modified Zech-Aslan energy distance dissimilarity metric based on an analogy with the energy of a cloud of electrical charges.

This method is scale-invariant.

Parameters:

• x (np.ndarray (n,d)) – Reference sample.

• y (np.ndarray (m,d)) – Candidate sample.

• dmin (float) – The cut-off for low distances to avoid singularities on identical points.

Return type:

float

Returns:

float – Zech-Aslan dissimilarity metric ranging from -infinity to infinity.

Notes

The energy measure between two variables \(X\), \(Y\) (target and candidates) of sizes \(n,d\) and \(m,d\) proposed by Aslan and Zech [2003] is defined by:

\[\begin{split}e(X, Y) &= \left[\phi_{xx} + \phi_{yy} - \phi_{xy}\right] \\ \phi_{xy} &= \frac{1}{n m} \sum_{i = 1}^n \sum_{j = 1}^m R\left[SED(X_i, Y_j)\right] \\ \phi_{xx} &= \frac{1}{n^2} \sum_{i = 1}^n \sum_{j = i + 1}^n R\left[SED(X_i, X_j)\right] \\ \phi_{yy} &= \frac{1}{m^2} \sum_{i = 1}^m \sum_{j = i + 1}^m R\left[SED(X_i, Y_j)\right] \\\end{split}\]

where \(X_i\) denotes the i-th observation of \(X\). \(R\) is a weight function and \(SED(A, B)\) denotes the standardized Euclidean distance.

\[\begin{split}R(r) &= \left\{\begin{array}{r l} -\ln r & \text{for } r > d_{min} \\ -\ln d_{min} & \text{for } r \leq d_{min} \end{array}\right. \\ SED(X_i, Y_j) &= \sqrt{\sum_{k=1}^d \frac{\left(X_i(k) - Y_i(k)\right)^2}{\sigma_x(k)\sigma_y(k)}}\end{split}\]

where \(k\) is a counter over dimensions (indices in the case of spatial analogs) and \(\sigma_x(k)\) is the standard deviation of \(X\) in dimension \(k\). Finally, \(d_{min}\) is a cut-off to avoid poles when \(r \to 0\), it is controllable through the dmin parameter.

This version corresponds the \(D_{ZAE}\) test of Grenier et al. [2013] (eq. 7), which is a version of \(\phi_{NM}\) from Aslan and Zech [2003], modified by using the standardized euclidean distance, the log weight function and choosing \(d_{min} = 10^{-12}\).

References

Aslan and Zech [2003], Grenier, Parent, Huard, Anctil, and Chaumont [2013], Zech and Aslan [2003]

Subset Module

Warning

The xclim.subset module was removed in xclim==0.40. Subsetting is now offered via clisops.core.subset. The subsetting functions offered by clisops are available at the following link: CLISOPS core subsetting API

Note

For more information about clisops refer to their documentation here: CLISOPS documentation

Other Utilities

Calendar Handling Utilities

Helper function to handle dates, times and different calendars with xarray.

xclim.core.calendar.adjust_doy_calendar(source, target)

Interpolate from one set of dayofyear range to another calendar.

Interpolate an array defined over a dayofyear range (say 1 to 360) to another dayofyear range (say 1 to 365).

Parameters:

• source (xr.DataArray) – Array with dayofyear coordinate.

• target (xr.DataArray or xr.Dataset) – Array with time coordinate.

Return type:

DataArray

Returns:

xr.DataArray – Interpolated source array over coordinates spanning the target dayofyear range.

xclim.core.calendar.build_climatology_bounds(da)

Build the climatology_bounds property with the start and end dates of input data.

Parameters:

da (xr.DataArray) – The input data. Must have a time dimension.

Return type:

list[str]

xclim.core.calendar.climatological_mean_doy(arr, window=5)

Calculate the climatological mean and standard deviation for each day of the year.

Parameters:

• arr (xarray.DataArray) – Input array.

• window (int) – Window size in days.

Return type:

tuple[DataArray, DataArray]

Returns:

xarray.DataArray, xarray.DataArray – Mean and standard deviation.

xclim.core.calendar.common_calendar(calendars, join='outer')

Return a calendar common to all calendars from a list.

Uses the hierarchy: 360_day < noleap < standard < all_leap. Returns “default” only if all calendars are “default.”

Parameters:

• calendars (Sequence of string) – List of calendar names.

• join ({‘inner’, ‘outer’}) – The criterion for the common calendar.

  • ‘outer’: the common calendar is the smallest calendar (in number of days by year)

    that will include all the dates of the other calendars. When converting the data to this calendar, no timeseries will lose elements, but some might be missing (gaps or NaNs in the series).

  • ‘inner’: the common calender is the smallest calendar of the list. When converting

    the data to this calendar, no timeseries will have missing elements (no gaps or NaNs), but some might be dropped.

Return type:

str

Examples

>>> common_calendar(["360_day", "noleap", "default"], join="outer")
'standard'
>>> common_calendar(["360_day", "noleap", "default"], join="inner")
'360_day'

xclim.core.calendar.compare_offsets(freqA, op, freqB)

Compare offsets string based on their approximate length, according to a given operator.

Offset are compared based on their length approximated for a period starting after 1970-01-01 00:00:00. If the offsets are from the same category (same first letter), only the multiplier prefix is compared (QS-DEC == QS-JAN, MS < 2MS). “Business” offsets are not implemented.

Parameters:

• freqA (str) – RHS Date offset string (‘YS’, ‘1D’, ‘QS-DEC’, …)

• op ({‘<’, ‘<=’, ‘==’, ‘>’, ‘>=’, ‘!=’}) – Operator to use.

• freqB (str) – LHS Date offset string (‘YS’, ‘1D’, ‘QS-DEC’, …)

Return type:

bool

Returns:

bool – freqA op freqB

xclim.core.calendar.convert_calendar(source, target, align_on=None, missing=None, dim='time')

Convert a DataArray/Dataset to another calendar using the specified method.

Only converts the individual timestamps, does not modify any data except in dropping invalid/surplus dates or inserting missing dates.

If the source and target calendars are either no_leap, all_leap or a standard type, only the type of the time array is modified. When converting to a leap year from a non-leap year, the 29th of February is removed from the array. In the other direction and if target is a string, the 29th of February will be missing in the output, unless missing is specified, in which case that value is inserted.

For conversions involving 360_day calendars, see Notes.

This method is safe to use with sub-daily data as it doesn’t touch the time part of the timestamps.

Parameters:

• source (xr.DataArray or xr.Dataset) – Input array/dataset with a time coordinate of a valid dtype (datetime64 or a cftime.datetime).

• target (xr.DataArray or str) – Either a calendar name or the 1D time coordinate to convert to. If an array is provided, the output will be reindexed using it and in that case, days in target that are missing in the converted source are filled by missing (which defaults to NaN).

• align_on ({None, ‘date’, ‘year’, ‘random’}) – Must be specified when either source or target is a 360_day calendar, ignored otherwise. See Notes.

• missing (Any, optional) – A value to use for filling in dates in the target that were missing in the source. If target is a string, default (None) is not to fill values. If it is an array, default is to fill with NaN.

• dim (str) – Name of the time coordinate.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – Copy of source with the time coordinate converted to the target calendar. If target is given as an array, the output is reindexed to it, with fill value missing. If target was a string and missing was None (default), invalid dates in the new calendar are dropped, but missing dates are not inserted. If target was a string and missing was given, then start, end and frequency of the new time axis are inferred and the output is reindexed to that a new array.

Notes

If one of the source or target calendars is 360_day, align_on must be specified and two options are offered.

“year”

The dates are translated according to their rank in the year (dayofyear), ignoring their original month and day information, meaning that the missing/surplus days are added/removed at regular intervals.

From a 360_day to a standard calendar, the output will be missing the following dates (day of year in parentheses):

To a leap year:

January 31st (31), March 31st (91), June 1st (153), July 31st (213), September 31st (275) and November 30th (335).

To a non-leap year:

February 6th (36), April 19th (109), July 2nd (183), September 12th (255), November 25th (329).

From standard calendar to a ‘360_day’, the following dates in the source array will be dropped:

From a leap year:

January 31st (31), April 1st (92), June 1st (153), August 1st (214), September 31st (275), December 1st (336)

From a non-leap year:

February 6th (37), April 20th (110), July 2nd (183), September 13th (256), November 25th (329)

This option is best used on daily and subdaily data.

“date”

The month/day information is conserved and invalid dates are dropped from the output. This means that when converting from a 360_day to a standard calendar, all 31st (Jan, March, May, July, August, October and December) will be missing as there is no equivalent dates in the 360_day and the 29th (on non-leap years) and 30th of February will be dropped as there are no equivalent dates in a standard calendar.

This option is best used with data on a frequency coarser than daily.

“random”

Similar to “year”, each day of year of the source is mapped to another day of year of the target. However, instead of having always the same missing days according the source and target years, here 5 days are chosen randomly, one for each fifth of the year. However, February 29th is always missing when converting to a leap year, or its value is dropped when converting from a leap year. This is similar to method used in the Pierce et al. [2014] dataset.

This option best used on daily data.

References

Pierce, Cayan, and Thrasher [2014]

Examples

This method does not try to fill the missing dates other than with a constant value, passed with missing. In order to fill the missing dates with interpolation, one can simply use xarray’s method:

>>> tas_nl = convert_calendar(tas, "noleap")  # For the example
>>> with_missing = convert_calendar(tas_nl, "standard", missing=np.NaN)
>>> out = with_missing.interpolate_na("time", method="linear")

Here, if Nans existed in the source data, they will be interpolated too. If that is, for some reason, not wanted, the workaround is to do:

>>> mask = convert_calendar(tas_nl, "standard").notnull()
>>> out2 = out.where(mask)

xclim.core.calendar.date_range(*args, calendar='default', **kwargs)

Wrap a Pandas date_range object.

Uses pd.date_range (if calendar == ‘default’) or xr.cftime_range (otherwise).

Return type:

DatetimeIndex | CFTimeIndex

xclim.core.calendar.date_range_like(source, calendar)

Generate a datetime array with the same frequency, start and end as another one, but in a different calendar.

Parameters:

• source (xr.DataArray) – 1D datetime coordinate DataArray

• calendar (str) – New calendar name.

Raises:

ValueError – If the source’s frequency was not found.

Return type:

DataArray

Returns:

xr.DataArray –

1D datetime coordinate with the same start, end and frequency as the source, but in the new calendar.

The start date is assumed to exist in the target calendar. If the end date doesn’t exist, the code tries 1 and 2 calendar days before. Exception when the source is in 360_day and the end of the range is the 30th of a 31-days month, then the 31st is appended to the range.

xclim.core.calendar.datetime_to_decimal_year(times, calendar='')

Convert a datetime xr.DataArray to decimal years according to its calendar or the given one.

Decimal years are the number of years since 0001-01-01 00:00:00 AD. Ex: ‘2000-03-01 12:00’ is 2000.1653 in a standard calendar, 2000.16301 in a “noleap” or 2000.16806 in a “360_day”.

Parameters:

• times (xr.DataArray)

• calendar (str)

Return type:

DataArray

Returns:

xr.DataArray

xclim.core.calendar.days_in_year(year, calendar='default')

Return the number of days in the input year according to the input calendar.

Return type:

int

xclim.core.calendar.days_since_to_doy(da, start=None, calendar=None)

Reverse the conversion made by doy_to_days_since().

Converts data given in days since a specific date to day-of-year.

Parameters:

• da (xr.DataArray) – The result of doy_to_days_since().

• start (DateOfYearStr, optional) – da is considered as days since that start date (in the year of the time index). If None (default), it is read from the attributes.

• calendar (str, optional) – Calendar the “days since” were computed in. If None (default), it is read from the attributes.

Return type:

DataArray

Returns:

xr.DataArray – Same shape as da, values as day of year.

Examples

>>> from xarray import DataArray
>>> time = date_range("2020-07-01", "2021-07-01", freq="AS-JUL")
>>> da = DataArray(
...     [-86, 92],
...     dims=("time",),
...     coords={"time": time},
...     attrs={"units": "days since 10-02"},
... )
>>> days_since_to_doy(da).values
array([190, 2])

xclim.core.calendar.doy_to_days_since(da, start=None, calendar=None)

Convert day-of-year data to days since a given date.

This is useful for computing meaningful statistics on doy data.

Parameters:

• da (xr.DataArray) – Array of “day-of-year”, usually int dtype, must have a time dimension. Sampling frequency should be finer or similar to yearly and coarser then daily.

• start (date of year str, optional) – A date in “MM-DD” format, the base day of the new array. If None (default), the time axis is used. Passing start only makes sense if da has a yearly sampling frequency.

• calendar (str, optional) – The calendar to use when computing the new interval. If None (default), the calendar attribute of the data or of its time axis is used. All time coordinates of da must exist in this calendar. No check is done to ensure doy values exist in this calendar.

Return type:

DataArray

Returns:

xr.DataArray – Same shape as da, int dtype, day-of-year data translated to a number of days since a given date. If start is not None, there might be negative values.

Notes

The time coordinates of da are considered as the START of the period. For example, a doy value of 350 with a timestamp of ‘2020-12-31’ is understood as ‘2021-12-16’ (the 350th day of 2021). Passing start=None, will use the time coordinate as the base, so in this case the converted value will be 350 “days since time coordinate”.

Examples

>>> from xarray import DataArray
>>> time = date_range("2020-07-01", "2021-07-01", freq="AS-JUL")
>>> # July 8th 2020 and Jan 2nd 2022
>>> da = DataArray([190, 2], dims=("time",), coords={"time": time})
>>> # Convert to days since Oct. 2nd, of the data's year.
>>> doy_to_days_since(da, start="10-02").values
array([-86, 92])

xclim.core.calendar.ensure_cftime_array(time)

Convert an input 1D array to a numpy array of cftime objects.

Python’s datetime are converted to cftime.DatetimeGregorian (“standard” calendar).

Parameters:

time (sequence) – A 1D array of datetime-like objects.

Return type:

ndarray

Returns:

np.ndarray

Raises:

ValueError – When unable to cast the input.:

xclim.core.calendar.get_calendar(obj, dim='time')

Return the calendar of an object.

Parameters:

• obj (Any) – An object defining some date. If obj is an array/dataset with a datetime coordinate, use dim to specify its name. Values must have either a datetime64 dtype or a cftime dtype. obj can also be a python datetime.datetime, a cftime object or a pandas Timestamp or an iterable of those, in which case the calendar is inferred from the first value.

• dim (str) – Name of the coordinate to check (if obj is a DataArray or Dataset).

Raises:

ValueError – If no calendar could be inferred.

Return type:

str

Returns:

str – The cftime calendar name or “default” when the data is using numpy’s or python’s datetime types. Will always return “standard” instead of “gregorian”, following CF conventions 1.9.

xclim.core.calendar.interp_calendar(source, target, dim='time')

Interpolates a DataArray/Dataset to another calendar based on decimal year measure.

Each timestamp in source and target are first converted to their decimal year equivalent then source is interpolated on the target coordinate. The decimal year is the number of years since 0001-01-01 AD. Ex: ‘2000-03-01 12:00’ is 2000.1653 in a standard calendar or 2000.16301 in a ‘noleap’ calendar.

This method should be used with daily data or coarser. Sub-daily result will have a modified day cycle.

Parameters:

• source (xr.DataArray or xr.Dataset) – The source data to interpolate, must have a time coordinate of a valid dtype (np.datetime64 or cftime objects)

• target (xr.DataArray) – The target time coordinate of a valid dtype (np.datetime64 or cftime objects)

• dim (str) – The time coordinate name.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – The source interpolated on the decimal years of target,

xclim.core.calendar.parse_offset(freq)

Parse an offset string.

Parse a frequency offset and, if needed, convert to cftime-compatible components.

Parameters:

freq (str) – Frequency offset.

Return type:

Sequence[str]

Returns:

• multiplier (int) – Multiplier of the base frequency. “[n]W” is always replaced with “[7n]D”, as xarray doesn’t support “W” for cftime indexes.

• offset_base (str) – Base frequency. “Y” is always replaced with “A”.

• is_start_anchored (bool) – Whether coordinates of this frequency should correspond to the beginning of the period (True) or its end (False). Can only be False when base is A, Q or M; in other words, xclim assumes frequencies finer than monthly are all start-anchored.

• anchor (str or None) – Anchor date for bases A or Q. As xarray doesn’t support “W”, neither does xclim (anchor information is lost when given).

xclim.core.calendar.percentile_doy(arr, window=5, per=10.0, alpha=0.3333333333333333, beta=0.3333333333333333, copy=True)

Percentile value for each day of the year.

Return the climatological percentile over a moving window around each day of the year. Different quantile estimators can be used by specifying alpha and beta according to specifications given by Hyndman and Fan [1996]. The default definition corresponds to method 8, which meets multiple desirable statistical properties for sample quantiles. Note that numpy.percentile corresponds to method 7, with alpha and beta set to 1.

Parameters:

• arr (xr.DataArray) – Input data, a daily frequency (or coarser) is required.

• window (int) – Number of time-steps around each day of the year to include in the calculation.

• per (float or sequence of floats) – Percentile(s) between [0, 100]

• alpha (float) – Plotting position parameter.

• beta (float) – Plotting position parameter.

• copy (bool) – If True (default) the input array will be deep-copied. It’s a necessary step to keep the data integrity, but it can be costly. If False, no copy is made of the input array. It will be mutated and rendered unusable but performances may significantly improve. Put this flag to False only if you understand the consequences.

Return type:

DataArray

Returns:

xr.DataArray – The percentiles indexed by the day of the year. For calendars with 366 days, percentiles of doys 1-365 are interpolated to the 1-366 range.

References

Hyndman and Fan [1996]

xclim.core.calendar.resample_doy(doy, arr)

Create a temporal DataArray where each day takes the value defined by the day-of-year.

Parameters:

• doy (xr.DataArray) – Array with dayofyear coordinate.

• arr (xr.DataArray or xr.Dataset) – Array with time coordinate.

Return type:

DataArray

Returns:

xr.DataArray – An array with the same dimensions as doy, except for dayofyear, which is replaced by the time dimension of arr. Values are filled according to the day of year value in doy.

xclim.core.calendar.select_time(da, drop=False, season=None, month=None, doy_bounds=None, date_bounds=None)

Select entries according to a time period.

This conveniently improves xarray’s xarray.DataArray.where() and xarray.DataArray.sel() with fancier ways of indexing over time elements. In addition to the data da and argument drop, only one of season, month, doy_bounds or date_bounds may be passed.

Parameters:

• da (xr.DataArray or xr.Dataset) – Input data.

• drop (boolean) – Whether to drop elements outside the period of interest or to simply mask them (default).

• season (string or sequence of strings) – One or more of ‘DJF’, ‘MAM’, ‘JJA’ and ‘SON’.

• month (integer or sequence of integers) – Sequence of month numbers (January = 1 … December = 12)

• doy_bounds (2-tuple of integers) – The bounds as (start, end) of the period of interest expressed in day-of-year, integers going from 1 (January 1st) to 365 or 366 (December 31st). If calendar awareness is needed, consider using date_bounds instead. Bounds are inclusive.

• date_bounds (2-tuple of strings) – The bounds as (start, end) of the period of interest expressed as dates in the month-day (%m-%d) format. Bounds are inclusive.

Return type:

DataArray | Dataset

Returns:

xr.DataArray or xr.Dataset – Selected input values. If drop=False, this has the same length as da (along dimension ‘time’), but with masked (NaN) values outside the period of interest.

Examples

Keep only the values of fall and spring.

>>> ds = open_dataset("ERA5/daily_surface_cancities_1990-1993.nc")
>>> ds.time.size
1461
>>> out = select_time(ds, drop=True, season=["MAM", "SON"])
>>> out.time.size
732

Or all values between two dates (included).

>>> out = select_time(ds, drop=True, date_bounds=("02-29", "03-02"))
>>> out.time.values
array(['1990-03-01T00:00:00.000000000', '1990-03-02T00:00:00.000000000',
       '1991-03-01T00:00:00.000000000', '1991-03-02T00:00:00.000000000',
       '1992-02-29T00:00:00.000000000', '1992-03-01T00:00:00.000000000',
       '1992-03-02T00:00:00.000000000', '1993-03-01T00:00:00.000000000',
       '1993-03-02T00:00:00.000000000'], dtype='datetime64[ns]')

xclim.core.calendar.time_bnds(time, freq=None, precision=None)

Find the time bounds for a datetime index.

As we are using datetime indices to stand in for period indices, assumptions regarding the period are made based on the given freq.

Parameters:

• time (DataArray, Dataset, CFTimeIndex, DatetimeIndex, DataArrayResample or DatasetResample) – Object which contains a time index as a proxy representation for a period index.

• freq (str, optional) – String specifying the frequency/offset such as ‘MS’, ‘2D’, or ‘3T’ If not given, it is inferred from the time index, which means that index must have at least three elements.

• precision (str, optional) – A timedelta representation that pandas.Timedelta understands. The time bounds will be correct up to that precision. If not given, 1 ms (“1U”) is used for CFtime indexes and 1 ns (“1N”) for numpy datetime64 indexes.

Returns:

DataArray – The time bounds: start and end times of the periods inferred from the time index and a frequency. It has the original time index along it’s time coordinate and a new bnds coordinate. The dtype and calendar of the array are the same as the index.

Notes

xclim assumes that indexes for greater-than-day frequencies are “floored” down to a daily resolution. For example, the coordinate “2000-01-31 00:00:00” with a “M” frequency is assumed to mean a period going from “2000-01-01 00:00:00” to “2000-01-31 23:59:59.999999”.

Similarly, it assumes that daily and finer frequencies yield indexes pointing to the period’s start. So “2000-01-31 00:00:00” with a “3H” frequency, means a period going from “2000-01-31 00:00:00” to “2000-01-31 02:59:59.999999”.

xclim.core.calendar.within_bnds_doy(arr, *, low, high)

Return whether array values are within bounds for each day of the year.

Parameters:

• arr (xarray.DataArray) – Input array.

• low (xarray.DataArray) – Low bound with dayofyear coordinate.

• high (xarray.DataArray) – High bound with dayofyear coordinate.

Return type:

DataArray

Returns:

xarray.DataArray

xclim.core.calendar.yearly_interpolated_doy(time, source_calendar, target_calendar)

Return the nearest day in the target calendar of the corresponding “decimal year” in the source calendar.

xclim.core.calendar.yearly_random_doy(time, rng, source_calendar, target_calendar)

Return a day of year in the new calendar.

Removes Feb 29th and five other days chosen randomly within five sections of 72 days.

Formatting Utilities for Indicators

class xclim.core.formatting.AttrFormatter(mapping, modifiers)

Bases: Formatter

A formatter for frequently used attribute values.

See the doc of format_field() for more details.

format(format_string, /, *args, **kwargs)

Format a string.

Parameters:

• format_string (str)

• *args (Any)

• **kwargs

Return type:

str

Returns:

str

format_field(value, format_spec)

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.

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(
...     {"AS-*": ["annuel", "annuelle"], "MS": ["mensuel", "mensuelle"]},
...     ["m", "f"],
... )
>>> fmt.format(
...     "La moyenne {freq:f} est faite sur un échantillon {src_timestep:m}",
...     freq="AS-JUL",
...     src_timestep="MS",
... )
'La moyenne annuelle est faite sur un échantillon mensuel'

xclim.core.formatting.gen_call_string(funcname, *args, **kwargs)

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, kwargs – Arguments given to the function.

Example

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

xclim.core.formatting.generate_indicator_docstring(ind)

Generate an indicator’s docstring from keywords.

Parameters:

ind (Indicator instance)

Return type:

str

Returns:

str

xclim.core.formatting.get_percentile_metadata(data, prefix)

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)

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.

Returns:

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

xclim.core.formatting.parse_doc(doc)

Crude regex parsing reading an indice docstring and extracting information needed in indicator construction.

The appropriate docstring syntax is detailed in Defining new indices.

Parameters:

doc (str) – The docstring of an indice function.

Return type:

dict[str, str]

Returns:

dict – A dictionary with all parsed sections.

xclim.core.formatting.prefix_attrs(source, keys, prefix)

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.

Returns:

dict – Dictionary of attributes with some keys prefixed.

xclim.core.formatting.unprefix_attrs(source, keys, prefix)

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.

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)

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.

• new_name (Optional[str]) – The name of the newly created variable or dataset to prefix hist_msg.

• inputs_list (Sequence[Union[xr.DataArray, 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.

• inputs_kws (dict[str, Union[xr.DataArray, 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.

Returns:

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

See also

merge_attributes

xclim.core.formatting.update_xclim_history(func)

Decorator that auto-generates and fills the history attribute.

The history is generated from the signature of the function and added to the first output. Because of a limitation of the boltons wrapper, all arguments passed to the wrapped function will be printed as keyword arguments.

Options Submodule

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

class xclim.core.options.set_options(**kwargs)

Set options for xclim in a controlled context.

Variables:

• metadata_locales (list[Any]) – List of IETF language tags or tuples of language tags and a translation dict, or tuples of language tags and a path to a json file defining translation of attributes. Default: [].

• data_validation ({"log", "raise", "error"}) – Whether to “log”, “raise” an error or ‘warn’ the user on inputs that fail the data checks in xclim.core.datachecks(). Default: "raise".

• cf_compliance ({"log", "raise", "error"}) – Whether to “log”, “raise” an error or “warn” the user on inputs that fail the CF compliance checks in xclim.core.cfchecks(). Default: "warn".

• check_missing ({"any", "wmo", "pct", "at_least_n", "skip"}) – How to check for missing data and flag computed indicators. Available methods are “any”, “wmo”, “pct”, “at_least_n” and “skip”. Missing method can be registered through the xclim.core.options.register_missing_method decorator. Default: "any"

• missing_options (dict) – Dictionary of options to pass to the missing method. Keys must the name of missing method and values must be mappings from option names to values.

• run_length_ufunc (str) – Whether to use the 1D ufunc version of run length algorithms or the dask-ready broadcasting version. Default is "auto", which means the latter is used for dask-backed and large arrays.

• sdba_extra_output (bool) – Whether to add diagnostic variables to outputs of sdba’s train, adjust and processing operations. Details about these additional variables are given in the object’s docstring. When activated, adjust will return a Dataset with scen and those extra diagnostics For processing functions, see the doc, the output type might change, or not depending on the algorithm. Default: False.

• sdba_encode_cf (bool) – Whether to encode cf coordinates in the map_blocks optimization that most adjustment methods are based on. This should have no impact on the results, but should run much faster in the graph creation phase.

• keep_attrs (bool or str) – Controls attributes handling in indicators. If True, attributes from all inputs are merged using the drop_conflicts strategy and then updated with xclim-provided attributes. If False, attributes from the inputs are ignored. If “xarray”, xclim will use xarray’s keep_attrs option. Note that xarray’s “default” is equivalent to False. Default: "xarray".

Examples

You can use set_options either as a context manager:

>>> import xclim
>>> ds = xr.open_dataset(path_to_tas_file).tas
>>> with xclim.set_options(metadata_locales=["fr"]):
...     out = xclim.atmos.tg_mean(ds)
...

Or to set global options:

import xclim

xclim.set_options(missing_options={"pct": {"tolerance": 0.04}})

Miscellaneous Indices Utilities

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

class xclim.core.utils.DateStr

Type annotation for strings representing full dates (YYYY-MM-DD), may include time.

alias of str

class xclim.core.utils.DayOfYearStr

Type annotation for strings representing dates without a year (MM-DD).

alias of str

class xclim.core.utils.Quantified

Type annotation for thresholds and other not-exactly-a-variable quantities

alias of TypeVar(‘Quantified’, ~xarray.DataArray, str, ~pint.util.Quantity)

xclim.core.utils.wrapped_partial(func, suggested=None, **fixed)

Wrap a function, updating its signature but keeping its docstring.

Parameters:

• func (Callable) – The function to be wrapped

• suggested (dict, optional) – Keyword arguments that should have new default values but still appear in the signature.

• **fixed – Keyword arguments that should be fixed by the wrapped and removed from the signature.

Return type:

Callable

Returns:

Callable

Examples

>>> from inspect import signature
>>> def func(a, b=1, c=1):
...     print(a, b, c)
...
>>> newf = wrapped_partial(func, b=2)
>>> signature(newf)
<Signature (a, *, c=1)>
>>> newf(1)
1 2 1
>>> newf = wrapped_partial(func, suggested=dict(c=2), b=2)
>>> signature(newf)
<Signature (a, *, c=2)>
>>> newf(1)
1 2 2

xclim.core.utils.walk_map(d, func)

Apply a function recursively to values of dictionary.

Parameters:

• d (dict) – Input dictionary, possibly nested.

• func (Callable) – Function to apply to dictionary values.

Return type:

dict

Returns:

dict – Dictionary whose values are the output of the given function.

xclim.core.utils.load_module(path, name=None)

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

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  # noqa

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

exception xclim.core.utils.ValidationError

Bases: ValueError

Error raised when input data to an indicator fails the validation tests.

property msg

exception xclim.core.utils.MissingVariableError

Bases: ValueError

Error raised when a dataset is passed to an indicator but one of the needed variable is missing.

xclim.core.utils.ensure_chunk_size(da, **minchunks)

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

xclim.core.utils.uses_dask(da)

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

Parameters:

da (xr.DataArray)

Return type:

bool

Returns:

bool

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

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

Return type:

ndarray

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

Convert the percentiles to quantiles and compute them using _nan_quantile.

Return type:

ndarray

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

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

class xclim.core.utils.InputKind(value)

Bases: IntEnum

Constants for input parameter kinds.

For use by external parses 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 an indice function should use in order to be picked up by the indicator constructor. Notice that we are using the annotation format as described in PEP604/py3.10, i.e. with | indicating an union and without import objects from typing.

VARIABLE = 0

A data variable (DataArray or variable name).

Annotation : xr.DataArray.

OPTIONAL_VARIABLE = 1

An optional data variable (DataArray or variable name).

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

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.

FREQ_STR = 3

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

See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases . Annotation : str + freq as the parameter name.

NUMBER = 4

A number.

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

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

DAY_OF_YEAR = 6

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

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

DATE = 7

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

Annotation : xclim.core.utils.DateStr (may be 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.

BOOL = 9

A boolean flag.

Annotation : bool, may be optional.

KWARGS = 50

A mapping from argument name to value.

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

DATASET = 70

An xarray dataset.

Developers : as indices only accept DataArrays, this should only be added on the indicator’s constructor.

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.

xclim.core.utils.infer_kind_from_parameter(param, has_units=False)

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

The correspondence between parameters and kinds is documented in xclim.core.utils.InputKind. The only information not inferable through the inspect object is whether the parameter has been assigned units through the xclim.core.units.declare_units() decorator. That can be given with the has_units flag.

Return type:

InputKind

xclim.core.utils.adapt_clix_meta_yaml(raw, adapted)

Read in a clix-meta yaml representation and refactor it to fit xclim’s yaml specifications.

xclim.core.utils.is_percentile_dataarray(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.

Return type:

bool

Modules for xclim Developers

Indicator Tools

Indicator Utilities

The Indicator class wraps indices computations with pre- and post-processing functionality. Prior to computations, the class runs data and metadata health checks. After computations, the class masks values that should be considered missing and adds metadata attributes to the object.

There are many ways to construct indicators. A good place to start is this notebook.

Dictionary and YAML parser

To construct indicators dynamically, xclim can also use dictionaries and parse them from YAML files. This is especially useful for generating whole indicator “submodules” from files. This functionality is inspired by the work of clix-meta.

YAML file structure

Indicator-defining yaml files are structured in the following way. Most entries of the indicators section are mirroring attributes of the Indicator, please refer to its documentation for more details on each.

module: <module name>  # Defaults to the file name
realm: <realm>  # If given here, applies to all indicators that do not already provide it.
keywords: <keywords> # Merged with indicator-specific keywords (joined with a space)
references: <references> # Merged with indicator-specific references (joined with a new line)
base: <base indicator class>  # Defaults to "Daily" and applies to all indicators that do not give it.
doc: <module docstring>  # Defaults to a minimal header, only valid if the module doesn't already exist.
variables:  # Optional section if indicators declared below rely on variables unknown to xclim (no in `xclim.core.utils.VARIABLES`)
            # The variables are not module-dependent and will overwrite any already existing with the same name.
  <varname>:
    canonical_units: <units> # required
    description: <description> # required
    standard_name: <expected standard_name> # optional
    cell_methods: <exptected cell_methods> # optional
indicators:
  <identifier>:
    # From which Indicator to inherit
    base: <base indicator class>  # Defaults to module-wide base class
                                  # If the name startswith a '.', the base class is taken from the current module (thus an indicator declared _above_)
                                  # Available classes are listed in `xclim.core.indicator.registry` and `xclim.core.indicator.base_registry`.

    # General metadata, usually parsed from the `compute`'s docstring when possible.
    realm: <realm>  # defaults to module-wide realm. One of "atmos", "land", "seaIce", "ocean".
    title: <title>
    abstract: <abstract>
    keywords: <keywords>  # Space-separated, merged to module-wide keywords.
    references: <references>  # newline-seperated, merged to module-wide references.
    notes: <notes>

    # Other options
    missing: <missing method name>
    missing_options:
        # missing options mapping
    allowed_periods: [<list>, <of>, <allowed>, <periods>]

    # Compute function
    compute: <function name>  # Referring to a function in the supplied `Indices` module, xclim.indices.generic or xclim.indices
    input:  # When "compute" is a generic function, this is a mapping from argument name to the expected variable.
            # This will allow the input units and CF metadata checks to run on the inputs.
            # Can also be used to modify the expected variable, as long as it has the same dimensionality
            # Ex: tas instead of tasmin.
            # Can refer to a variable declared in the `variables` section above.
      <var name in compute> : <variable official name>
      ...
    parameters:
     <param name>: <param data>  # Simplest case, to inject parameters in the compute function.
     <param name>:  # To change parameters metadata or to declare units when "compute" is a generic function.
        units: <param units>  # Only valid if "compute" points to a generic function
        default : <param default>
        description: <param description>
    ...
  ...  # and so on.

All fields are optional. Other fields found in the yaml file will trigger errors in xclim. In the following, the section under <identifier> is referred to as data. When creating indicators from a dictionary, with Indicator.from_dict(), the input dict must follow the same structure of data.

The resulting yaml file can be validated using the provided schema (in xclim/data/schema.yml) and the YAMALE tool [Lopker, 2022]. See the “Extending xclim” notebook for more info.

Inputs

As xclim has strict definitions of possible input variables (see xclim.core.utils.variables), the mapping of data.input simply links an argument name from the function given in “compute” to one of those official variables.

class xclim.core.indicator.Parameter(kind, default, description='', units=<class 'xclim.core.indicator._empty'>, choices=<class 'xclim.core.indicator._empty'>, value=<class 'xclim.core.indicator._empty'>)

Bases: object

Class for storing an indicator’s controllable parameter.

For retrocompatibility, this class implements a “getitem” and a special “contains”.

Example

>>> p = Parameter(InputKind.NUMBER, default=2, description="A simple number")
>>> p.units is Parameter._empty  # has not been set
True
>>> "units" in p  # Easier/retrocompatible way to test if units are set
False
>>> p.description
'A simple number'
>>> p["description"]  # Same as above, for convenience.
'A simple number'

default

alias of _empty

update(other)

Update a parameter’s values from a dict.

Return type:

None

classmethod is_parameter_dict(other)

Return whether indicator has a parameter dictionary.

Return type:

bool

asdict()

Format indicators as a dictionary.

Return type:

dict

property injected: bool

Indicate whether values are injected.

class xclim.core.indicator.IndicatorRegistrar

Bases: object

Climate Indicator registering object.

classmethod get_instance()

Return first found instance.

Raises ValueError if no instance exists.

class xclim.core.indicator.Indicator(**kwds)

Bases: IndicatorRegistrar

Climate indicator base class.

Climate indicator object that, when called, computes an indicator and assigns its output a number of CF-compliant attributes. Some of these attributes can be templated, allowing metadata to reflect the value of call arguments.

Instantiating a new indicator returns an instance but also creates and registers a custom subclass in xclim.core.indicator.registry.

Attributes in Indicator.cf_attrs will be formatted and added to the output variable(s). This attribute is a list of dictionaries. For convenience and retro-compatibility, standard CF attributes (names listed in xclim.core.indicator.Indicator._cf_names) can be passed as strings or list of strings directly to the indicator constructor.

A lot of the Indicator’s metadata is parsed from the underlying compute function’s docstring and signature. Input variables and parameters are listed in xclim.core.indicator.Indicator.parameters, while parameters that will be injected in the compute function are in xclim.core.indicator.Indicator.injected_parameters. Both are simply views of xclim.core.indicator.Indicator._all_parameters.

Compared to their base compute function, indicators add the possibility of using dataset as input, with the injected argument ds in the call signature. All arguments that were indicated by the compute function to be variables (DataArrays) through annotations will be promoted to also accept strings that correspond to variable names in the ds dataset.

Parameters:

• identifier (str) – Unique ID for class registry, should be a valid slug.

• realm ({‘atmos’, ‘seaIce’, ‘land’, ‘ocean’}) – General domain of validity of the indicator. Indicators created outside xclim.indicators must set this attribute.

• compute (func) – The function computing the indicators. It should return one or more DataArray.

• cf_attrs (list of dicts) – Attributes to be formatted and added to the computation’s output. See xclim.core.indicator.Indicator.cf_attrs.

• title (str) – A succinct description of what is in the computed outputs. Parsed from compute docstring if None (first paragraph).

• abstract (str) – A long description of what is in the computed outputs. Parsed from compute docstring if None (second paragraph).

• keywords (str) – Comma separated list of keywords. Parsed from compute docstring if None (from a “Keywords” section).

• references (str) – Published or web-based references that describe the data or methods used to produce it. Parsed from compute docstring if None (from the “References” section).

• notes (str) – Notes regarding computing function, for example the mathematical formulation. Parsed from compute docstring if None (form the “Notes” section).

• src_freq (str, sequence of strings, optional) – The expected frequency of the input data. Can be a list for multiple frequencies, or None if irrelevant.

• context (str) – The pint unit context, for example use ‘hydro’ to allow conversion from kg m-2 s-1 to mm/day.

Notes

All subclasses created are available in the registry attribute and can be used to define custom subclasses or parse all available instances.

cf_attrs: list[dict[str, Any]] = None

A list of metadata information for each output of the indicator.

It minimally contains a “var_name” entry, and may contain : “standard_name”, “long_name”, “units”, “cell_methods”, “description” and “comment” on official xclim indicators. Other fields could also be present if the indicator was created from outside xclim.

var_name:

Output variable(s) name(s). For derived single-output indicators, this field is not inherited from the parent indicator and defaults to the identifier.

standard_name:

Variable name, must be in the CF standard names table (this is not checked).

long_name:

Descriptive variable name. Parsed from compute docstring if not given. (first line after the output dtype, only works on single output function).

units:

Representative units of the physical quantity.

cell_methods:

List of blank-separated words of the form “name: method”. Must respect the CF-conventions and vocabulary (not checked).

description:

Sentence(s) meant to clarify the qualifiers of the fundamental quantities, such as which surface a quantity is defined on or what the flux sign conventions are.

comment:

Miscellaneous information about the data or methods used to produce it.

classmethod from_dict(data, identifier, module=None)

Create an indicator subclass and instance from a dictionary of parameters.

Most parameters are passed directly as keyword arguments to the class constructor, except:

• “base” : A subclass of Indicator or a name of one listed in xclim.core.indicator.registry or xclim.core.indicator.base_registry. When passed, it acts as if from_dict was called on that class instead.

• “compute” : A string function name translates to a xclim.indices.generic or xclim.indices function.

Parameters:

• data (dict) – The exact structure of this dictionary is detailed in the submodule documentation.

• identifier (str) – The name of the subclass and internal indicator name.

• module (str) – The module name of the indicator. This is meant to be used only if the indicator is part of a dynamically generated submodule, to override the module of the base class.

classmethod translate_attrs(locale, fill_missing=True)

Return a dictionary of unformatted translated translatable attributes.

Translatable attributes are defined in xclim.core.locales.TRANSLATABLE_ATTRS.

Parameters:

• locale (str or sequence of str) – The POSIX name of the locale or a tuple of a locale name and a path to a json file defining the translations. See xclim.locale for details.

• fill_missing (bool) – If True (default) fill the missing attributes by their english values.

json(args=None)

Return a serializable dictionary representation of the class.

Parameters:

args (mapping, optional) – Arguments as passed to the call method of the indicator. If not given, the default arguments will be used when formatting the attributes.

Notes

This is meant to be used by a third-party library wanting to wrap this class into another interface.

static compute(*args, **kwds)

Compute the indicator.

This would typically be a function from xclim.indices.

cfcheck(**das)

Compare metadata attributes to CF-Convention standards.

Default cfchecks use the specifications in xclim.core.utils.VARIABLES, assuming the indicator’s inputs are using the CMIP6/xclim variable names correctly. Variables absent from these default specs are silently ignored.

When subclassing this method, use functions decorated using xclim.core.options.cfcheck.

datacheck(**das)

Verify that input data is valid.

When subclassing this method, use functions decorated using xclim.core.options.datacheck.

For example, checks could include:

• assert no precipitation is negative

• assert no temperature has the same value 5 days in a row

This base datacheck checks that the input data has a valid sampling frequency, as given in self.src_freq. If there are multiple inputs, it also checks if they all have the same frequency and the same anchor.

property n_outs

Return the length of all cf_attrs.

property parameters

Create a dictionary of controllable parameters.

Similar to Indicator._all_parameters, but doesn’t include injected parameters.

property injected_parameters

Return a dictionary of all injected parameters.

Opposite of Indicator.parameters().

class xclim.core.indicator.ResamplingIndicator(**kwds)

Bases: Indicator

Indicator that performs a resampling computation.

Compared to the base Indicator, this adds the handling of missing data, and the check of allowed periods.

Parameters:

• missing ({any, wmo, pct, at_least_n, skip, from_context}) – The name of the missing value method. See xclim.core.missing.MissingBase to create new custom methods. If None, this will be determined by the global configuration (see xclim.set_options). Defaults to “from_context”.

• missing_options (dict, optional) – Arguments to pass to the missing function. If None, this will be determined by the global configuration.

• allowed_periods (Sequence[str], optional) – A list of allowed periods, i.e. base parts of the freq parameter. For example, indicators meant to be computed annually only will have allowed_periods=[“A”]. None means “any period” or that the indicator doesn’t take a freq argument.

class xclim.core.indicator.ResamplingIndicatorWithIndexing(**kwds)

Bases: ResamplingIndicator

Resampling indicator that also injects “indexer” kwargs to subset the inputs before computation.

class xclim.core.indicator.Daily(**kwds)

Bases: ResamplingIndicator

Class for daily inputs and resampling computes.

class xclim.core.indicator.Hourly(**kwds)

Bases: ResamplingIndicator

Class for hourly inputs and resampling computes.

xclim.core.indicator.add_iter_indicators(module)

Create an iterable of loaded indicators.

xclim.core.indicator.build_indicator_module(name, objs, doc=None, reload=False)

Create or update a module from imported objects.

The module is inserted as a submodule of xclim.indicators.

Parameters:

• name (str) – New module name. If it already exists, the module is extended with the passed objects, overwriting those with same names.

• objs (dict[str, Indicator]) – Mapping of the indicators to put in the new module. Keyed by the name they will take in that module.

• doc (str) – Docstring of the new module. Defaults to a simple header. Invalid if the module already exists.

• reload (bool) – If reload is True and the module already exists, it is first removed before being rebuilt. If False (default), indicators are added or updated, but not removed.

Return type:

ModuleType

Returns:

ModuleType – A indicator module built from a mapping of Indicators.

xclim.core.indicator.build_indicator_module_from_yaml(filename, name=None, indices=None, translations=None, mode='raise', encoding='UTF8', reload=False)

Build or extend an indicator module from a YAML file.

The module is inserted as a submodule of xclim.indicators. When given only a base filename (no ‘yml’ extension), this tries to find custom indices in a module of the same name (.py) and translations in json files (.<lang>.json), see Notes.

Parameters:

• filename (PathLike) – Path to a YAML file or to the stem of all module files. See Notes for behaviour when passing a basename only.

• name (str, optional) – The name of the new or existing module, defaults to the basename of the file. (e.g: atmos.yml -> atmos)

• indices (Mapping of callables or module or path, optional) – A mapping or module of indice functions or a python file declaring such a file. When creating the indicator, the name in the index_function field is first sought here, then the indicator class will search in xclim.indices.generic and finally in xclim.indices.

• translations (Mapping of dicts or path, optional) – Translated metadata for the new indicators. Keys of the mapping must be 2-char language tags. Values can be translations dictionaries as defined in Internationalization. They can also be a path to a json file defining the translations.

• mode ({‘raise’, ‘warn’, ‘ignore’}) – How to deal with broken indice definitions.

• encoding (str) – The encoding used to open the .yaml and .json files. It defaults to UTF-8, overriding python’s mechanism which is machine dependent.

• reload (bool) – If reload is True and the module already exists, it is first removed before being rebuilt. If False (default), indicators are added or updated, but not removed.

Return type:

ModuleType

Returns:

ModuleType – A submodule of pym:mod:`xclim.indicators.

Notes

When the given filename has no suffix (usually ‘.yaml’ or ‘.yml’), the function will try to load custom indice definitions from a file with the same name but with a .py extension. Similarly, it will try to load translations in *.<lang>.json files, where <lang> is the IETF language tag.

For example. a set of custom indicators could be fully described by the following files:

• example.yml : defining the indicator’s metadata.

• example.py : defining a few indice functions.

• example.fr.json : French translations

• example.tlh.json : Klingon translations.

See also

xclim.core.indicator, build_module

Bootstrapping Algorithms for Indicators Submodule

Module comprising the bootstrapping algorithm for indicators.

xclim.core.bootstrapping.bootstrap_func(compute_index_func, **kwargs)

Bootstrap the computation of percentile-based indices.

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

Theses altered reference periods are themselves built iteratively: When computing the index for year x, the bootstrapping create as many altered reference period 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 – Arguments to func.

Return type:

DataArray

Returns:

xr.DataArray – The result of func with bootstrapping.

References

Zhang, Hegerl, Zwiers, and Kenyon [2005]

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

xclim.core.bootstrapping.build_bootstrap_year_da(da, groups, label, dim='time')

Return an array where a group in the original is replaced by every other groups along a new dimension.

Parameters:

• da (DataArray) – Original input array over reference period.

• groups (dict) – Output of grouping functions, such as DataArrayResample.groups.

• label (Any) – Key identifying the group item to replace.

• dim (str) – Dimension recognized 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)

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

This feature is experimental.

Bootstraping 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: str = "YS",
    bootstrap: bool = False,
) -> xarray.DataArray:
    pass

Examples

>>> from xclim.core.calendar import percentile_doy
>>> from xclim.indices 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)
>>> tg90p(tas=tas, tas_per=t90.sel(percentiles=90), freq="YS", bootstrap=True)

SDBA Utilities

Base Classes and Developer Tools

class xclim.sdba.base.Parametrizable

Bases: dict

Helper base class resembling a dictionary.

This object is _completely_ defined by the content of its internal dictionary, accessible through item access (self[‘attr’]) or in self.parameters. When serializing and restoring this object, only members of that internal dict are preserved. All other attributes set directly with self.attr = value will not be preserved upon serialization and restoration of the object with [json]pickle dictionary. Other variables set with self.var = data will be lost in the serialization process. This class is best serialized and restored with jsonpickle.

property parameters

All parameters as a dictionary. Read-only.

class xclim.sdba.base.ParametrizableWithDataset

Bases: Parametrizable

Parametrizeable class that also has a ds attribute storing a dataset.

classmethod from_dataset(ds)

Create an instance from a dataset.

The dataset must have a global attribute with a name corresponding to cls._attribute, and that attribute must be the result of jsonpickle.encode(object) where object is of the same type as this object.

set_dataset(ds)

Store an xarray dataset in the ds attribute.

Useful with custom object initialization or if some external processing was performed.

xclim.sdba.base.duck_empty(dims, sizes, dtype='float64', chunks=None)

Return an empty DataArray based on a numpy or dask backend, depending on the chunks argument.

xclim.sdba.base.map_blocks(reduces=None, **outvars)

Decorator for declaring functions and wrapping them into a map_blocks.

Takes care of constructing the template dataset. Dimension order is not preserved. The decorated function must always have the signature: func(ds, **kwargs), where ds is a DataArray or a Dataset. It must always output a dataset matching the mapping passed to the decorator.

Parameters:

• reduces (sequence of strings) – Name of the dimensions that are removed by the function.

• **outvars – Mapping from variable names in the output to their new dimensions. The placeholders Grouper.PROP, Grouper.DIM and Grouper.ADD_DIMS can be used to signify group.prop,``group.dim`` and group.add_dims respectively. If an output keeps a dimension that another loses, that dimension name must be given in reduces and in the list of new dimensions of the first output.

xclim.sdba.base.map_groups(reduces=None, main_only=False, **out_vars)

Decorator for declaring functions acting only on groups and wrapping them into a map_blocks.

This is the same as map_blocks but adds a call to group.apply() in the mapped func and the default value of reduces is changed.

The decorated function must have the signature: func(ds, dim, **kwargs). Where ds is a DataAray or Dataset, dim is the group.dim (and add_dims). The group argument is stripped from the kwargs, but must evidently be provided in the call.

Parameters:

• reduces (sequence of str) – Dimensions that are removed from the inputs by the function. Defaults to [Grouper.DIM, Grouper.ADD_DIMS] if main_only is False, and [Grouper.DIM] if main_only is True. See map_blocks().

• main_only (bool) – Same as for Grouper.apply().

• **out_vars – Mapping from variable names in the output to their new dimensions. The placeholders Grouper.PROP, Grouper.DIM and Grouper.ADD_DIMS can be used to signify group.prop,``group.dim`` and group.add_dims, respectively. If an output keeps a dimension that another loses, that dimension name must be given in reduces and in the list of new dimensions of the first output.

See also

map_blocks

xclim.sdba.base.parse_group(func, kwargs=None, allow_only=None)

Parse the kwargs given to a function to set the group arg with a Grouper object.

This function can be used as a decorator, in which case the parsing and updating of the kwargs is done at call time. It can also be called with a function from which extract the default group and kwargs to update, in which case it returns the updated kwargs.

If allow_only is given, an exception is raised when the parsed group is not within that list.

Return type:

Callable

class xclim.sdba.detrending.BaseDetrend(*, group='time', kind='+', **kwargs)

Base class for detrending objects.

Defines three methods:

fit(da) : Compute trend from da and return a new _fitted_ Detrend object. detrend(da) : Return detrended array. retrend(da) : Puts trend back on da.

A fitted Detrend object is unique to the trend coordinate of the object used in fit, (usually ‘time’). The computed trend is stored in Detrend.ds.trend.

Subclasses should implement _get_trend_group() or _get_trend(). The first will be called in a group.apply(..., main_only=True), and should return a single DataArray. The second allows the use of functions wrapped in map_groups() and should also return a single DataArray.

The subclasses may reimplement _detrend and _retrend.

detrend(da)

Remove the previously fitted trend from a DataArray.

fit(da)

Extract the trend of a DataArray along a specific dimension.

Returns a new object that can be used for detrending and retrending. Fitted objects are unique to the fitted coordinate used.

property fitted

Return whether instance is fitted.

retrend(da)

Put the previously fitted trend back on a DataArray.

class xclim.sdba.adjustment.TrainAdjust(*args, _trained=False, **kwargs)

Base class for adjustment objects obeying the train-adjust scheme.

Children classes should implement these methods:

• _train(ref, hist, **kwargs), classmethod receiving the training target and data, returning a training dataset and parameters to store in the object.

• _adjust(sim, **kwargs), receiving the projected data and some arguments, returning the scen DataArray.

adjust(sim, *args, **kwargs)

Return bias-adjusted data. Refer to the class documentation for the algorithm details.

Parameters:

• sim (DataArray) – Time series to be bias-adjusted, usually a model output.

• args (xr.DataArray) – Other DataArrays needed for the adjustment (usually none).

• kwargs – Algorithm-specific keyword arguments, see class doc.

set_dataset(ds)

Store an xarray dataset in the ds attribute.

Useful with custom object initialization or if some external processing was performed.

classmethod train(ref, hist, **kwargs)

Train the adjustment object. Refer to the class documentation for the algorithm details.

Parameters:

• ref (DataArray) – Training target, usually a reference time series drawn from observations.

• hist (DataArray) – Training data, usually a model output whose biases are to be adjusted.

class xclim.sdba.adjustment.Adjust(*args, _trained=False, **kwargs)

Adjustment with no intermediate trained object.

Children classes should implement a _adjust classmethod taking as input the three DataArrays and returning the scen dataset/array.

classmethod adjust(ref, hist, sim, **kwargs)

Return bias-adjusted data. Refer to the class documentation for the algorithm details.

Parameters:

• ref (DataArray) – Training target, usually a reference time series drawn from observations.

• hist (DataArray) – Training data, usually a model output whose biases are to be adjusted.

• sim (DataArray) – Time series to be bias-adjusted, usually a model output.

• **kwargs – Algorithm-specific keyword arguments, see class doc.

xclim.sdba.properties.StatisticalProperty(**kwds)

Base indicator class for statistical properties used for validating bias-adjusted outputs.

Statistical properties reduce the time dimension, sometimes adding a grouping dimension according to the passed value of group (e.g.: group=’time.month’ means the loss of the time dimension and the addition of a month one).

Statistical properties are generally unit-generic. To use those indicator in a workflow, it is recommended to wrap them with a virtual submodule, creating one specific indicator for each variable input (or at least for each possible dimensionality).

Statistical properties may restrict the sampling frequency of the input, they usually take in a single variable (named “da” in unit-generic instances).

xclim.sdba.measures.StatisticalMeasure(**kwds)

Base indicator class for statistical measures used when validating bias-adjusted outputs.

Statistical measures use input data where the time dimension was reduced, usually by the computation of a xclim.sdba.properties.StatisticalProperty instance. They usually take two arrays as input: “sim” and “ref”, “sim” being measured against “ref”. The two arrays must have identical coordinates on their common dimensions.

Statistical measures are generally unit-generic. If the inputs have different units, “sim” is converted to match “ref”.

Spatial Analogues Helpers

xclim.analog.metric(func)

Register a metric function in the metrics mapping and add some preparation/checking code.

All metric functions accept 2D inputs. This reshapes 1D inputs to (n, 1) and (m, 1). All metric functions are invalid when any non-finite values are present in the inputs.

xclim.analog.standardize(x, y)

Standardize x and y by the square root of the product of their standard deviation.

Parameters:

• x (np.ndarray) – Array to be compared.

• y (np.ndarray) – Array to be compared.

Return type:

tuple[ndarray, ndarray]

Returns:

(ndarray, ndarray) – Standardized arrays.

Testing Module

Testing and Tutorial Utilities’ Module

xclim.testing.utils.get_file(name, github_url='https://github.com/Ouranosinc/xclim-testdata', branch='master', cache_dir=PosixPath('/home/docs/.xclim_testing_data'))

Return a file from an online GitHub-like repository.

If a local copy is found then always use that to avoid network traffic.

Parameters:

• name (str | os.PathLike | Sequence[str | os.PathLike]) – Name of the file or list/tuple of names of files containing the dataset(s) including suffixes.

• github_url (str) – URL to GitHub repository where the data is stored.

• branch (str, optional) – For GitHub-hosted files, the branch to download from.

• cache_dir (Path) – The directory in which to search for and write cached data.

Return type:

Path | list[Path]

Returns:

Path | list[Path]

xclim.testing.utils.get_local_testdata(patterns, temp_folder, branch='master', _local_cache=PosixPath('/home/docs/.xclim_testing_data'))

Copy specific testdata from a default cache to a temporary folder.

Return files matching pattern in the default cache dir and move to a local temp folder.

Parameters:

• patterns (str | Sequence[str]) – Glob patterns, which must include the folder.

• temp_folder (str | os.PathLike) – Target folder to copy files and filetree to.

• branch (str) – For GitHub-hosted files, the branch to download from.

• _local_cache (str | os.PathLike) – Local cache of testing data.

Return type:

Path | list[Path]

Returns:

Path | list[Path]

xclim.testing.utils.list_datasets(github_repo='Ouranosinc/xclim-testdata', branch='main')

Return a DataFrame listing all xclim test datasets available on the GitHub repo for the given branch.

The result includes the filepath, as passed to open_dataset, the file size (in KB) and the html url to the file. This uses an unauthenticated call to GitHub’s REST API, so it is limited to 60 requests per hour (per IP). A single call of this function triggers one request per subdirectory, so use with parsimony.

xclim.testing.utils.list_input_variables(submodules=None, realms=None)

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:

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

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

Return type:

dict

Returns:

dict – A mapping from variable name to indicator class.

xclim.testing.utils.open_dataset(name, suffix=None, dap_url=None, github_url='https://github.com/Ouranosinc/xclim-testdata', branch='main', cache=True, cache_dir=PosixPath('/home/docs/.xclim_testing_data'), **kwargs)

Open a dataset from the online GitHub-like repository.

If a local copy is found then always use that to avoid network traffic.

Parameters:

• name (str or os.PathLike) – Name of the file containing the dataset.

• suffix (str, optional) – If no suffix is given, assumed to be netCDF (‘.nc’ is appended). For no suffix, set “”.

• dap_url (str, optional) – URL to OPeNDAP folder where the data is stored. If supplied, supersedes github_url.

• github_url (str) – URL to GitHub repository where the data is stored.

• branch (str, optional) – For GitHub-hosted files, the branch to download from.

• cache_dir (Path) – The directory in which to search for and write cached data.

• cache (bool) – If True, then cache data locally for use on subsequent calls.

• **kwargs – For NetCDF files, keywords passed to xarray.open_dataset().

Return type:

Dataset

Returns:

Union[Dataset, Path]

See also

xarray.open_dataset

xclim.testing.utils.publish_release_notes(style='md', file=None, changes=None)

Format release notes in Markdown or ReStructuredText.

Parameters:

• style ({“rst”, “md”}) – Use ReStructuredText formatting or Markdown. Default: Markdown.

• file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

• changes ({str, os.PathLike}, optional) – If provided, manually points to the file where the changelog can be found. Assumes a relative path otherwise.

Return type:

Optional[str]

Returns:

str, optional

Notes

This function is used solely for development and packaging purposes.

xclim.testing.utils.show_versions(file=None, deps=None)

Print the versions of xclim and its dependencies.

Parameters:

• file ({os.PathLike, StringIO, TextIO}, optional) – If provided, prints to the given file-like object. Otherwise, returns a string.

• deps (list, optional) – A list of dependencies to gather and print version information from. Otherwise, prints xclim dependencies.

Return type:

Optional[str]

Returns:

str or None

Module for loading testing data.

xclim.testing.helpers.PREFETCH_TESTING_DATA = False

Indicates whether the testing data should be downloaded when running tests.

Notes

When running tests multiple times, this flag allows developers to significantly speed up the pytest suite by preventing sha256sum checks for all downloaded files. Proceed with caution.

This can be set for both pytest and tox by exporting the variable:

$ export XCLIM_PREFETCH_TESTING_DATA=1

or setting the variable at runtime:

$ env XCLIM_PREFETCH_TESTING_DATA=1 pytest

xclim.testing.helpers.TESTDATA_BRANCH = 'main'

Sets the branch of Ouranosinc/xclim-testdata to use when fetching testing 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.helpers.add_example_file_paths(cache_dir)

Create a dictionary of relevant datasets to be patched into the xdoctest namespace.

Return type:

dict[str]

xclim.testing.helpers.generate_atmos(cache_dir)

Create the atmosds synthetic testing dataset.

xclim.testing.helpers.populate_testing_data(temp_folder=None, branch='main', _local_cache=PosixPath('/home/docs/.xclim_testing_data'))

Perform _get_file or get_local_dataset calls to GitHub to download or copy relevant testing data.

xclim.testing.helpers.test_timeseries(values, variable, start='7/1/2000', units=None, freq='D', as_dataset=False)

Create a generic timeseries object based on pre-defined dictionaries of existing variables.