xclim.indicators.convert package¶

Conversion Indicators¶

This submodule contains indicators that converts CF-compliant variables from one to another. For example, converting wind speed in cardinal directions to a vector magnitude and direction, or converting snow depth to snow water equivalent. It also includes indicators that approximate variables from multiple variables, such as calculating the mean temperature from daily maximum and minimum temperatures.

Submodules¶

xclim.indicators.convert._conversion module¶

Atmospheric conversion definitions.

xclim.indicators.convert._conversion.clearness_index(rsds='rsds', *, ds=None)

Clearness index (realm: convert)

The clearness index is the ratio between the shortwave downwelling radiation and the total extraterrestrial radiation on a given day.

Based on indice clearness_index().

Parameters:

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:

ci (DataArray) – Clear index, with additional attributes: description: The ratio of shortwave downwelling radiation to extraterrestrial radiation.

Return type:

xarray.DataArray

Notes

Clearness Index (ci) is defined as:

References

Lauret, Alonso-Suárez, Le Gal La Salle, and David [2022]

xclim.indicators.convert._conversion.dewpoint_from_specific_humidity(huss='huss', ps='ps', *, method='buck81', variant='water', ds=None)

Dewpoint temperature computed from specific humidity and pressure. (realm: convert)

The temperature at which the current vapour pressure would be the saturation vapour pressure. Only a subset of the saturation_vapor_pressure() methods are supported.

Based on indice dewpoint_from_specific_humidity().

Parameters:

huss (str or DataArray) – Specific humidity [kg/kg]. Default : ds.huss. [Required units : []]
ps (str or DataArray) – Pressure. Default : ds.ps. [Required units : [pressure]]
method ({‘buck81’, ‘tetens30’, ‘aerk96’, ‘wmo08’}) – The formula to use for saturation vapour pressure. Only the formulas using the easily invertible August-Roche-Magnus form are available. Default : buck81.
variant ({‘ice’, ‘water’}) – Which variant of the saturation vapour pressure formula to take. Default : water.
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

tdps (DataArray) – Dewpoint temperature. [K], with additional attributes: description: Temperature at which the current water vapour reaches saturation. Equation from {method} is used for saturation vapour pressure.

Return type:

xarray.DataArray

Notes

The calculation is based on the following, using the August-Roche-Magnus form for the saturation vapour pressure formula :

\[ \begin{align}\begin{aligned}e(q, p) = e_{sat}(T_d) = A \mathrm{e}^{B * \frac{T_d - T_0}{T_d + C}}}\\T_d = \frac{-T_0 - C\frac{1}{B}\mathrm{ln}\frac{e}{A}}{\frac{1}{B}\mathrm{ln}\frac{e}{A} - 1}\end{aligned}\end{align} \]

Where $e$ is the vapor_pressure(), $q$ is the specific humidiy, $p$ is the pressure, $e_{sat}$ is the saturation_vapor_pressure(), $T_0$ is the freezing temperature 273.16 K and $T_d$ is the dewpoint temperature. $A$, $B$ and $C$ are method-specific and variant-specific coefficients.

To imitate the calculations of ECMWF’s IFS (ERA5, ERA5-Land), use method='buck81' and reference='water' (the defaults).

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

Heat index (realm: convert)

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) – Mean 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.

Return type:

xarray.DataArray

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.convert._conversion.humidex(tas='tas', tdps=None, hurs=None, *, ds=None)

Humidex (realm: convert)

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(). Keywords : heatwave.

Parameters:

tas (str or DataArray) – Mean Temperature. Default : ds.tas. [Required units : [temperature]]
tdps (str or DataArray, optional) – Dewpoint Temperature, used to compute the vapour pressure. [Required units : [temperature]]
hurs (str or DataArray, optional) – Relative Humidity, used as an alternative way to compute the vapour pressure if the dewpoint temperature is not available. [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.

Return type:

xarray.DataArray

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.convert._conversion.longwave_upwelling_radiation_from_net_downwelling(rls='rls', rlds='rlds', *, ds=None)

Upwelling longwave radiation (realm: convert)

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.

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.mean_radiant_temperature(rsds='rsds', rsus='rsus', rlds='rlds', rlus='rlus', *, stat='sunlit', ds=None)

Mean radiant temperature (realm: convert)

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 ({‘sunlit’, ‘instant’}) – Which statistic to apply. 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. Default : sunlit.
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.

Return type:

xarray.DataArray

Notes

This code was inspired by the thermofeel package [Brimicombe et al., 2021].

References

Di Napoli, Hogan, and Pappenberger [2020]

xclim.indicators.convert._conversion.mean_temperature_from_max_and_min(tasmin='tasmin', tasmax='tasmax', *, ds=None)

Mean temperature (realm: convert)

The average daily temperature assuming a symmetrical temperature distribution (Tg = (Tx + Tn) / 2).

Based on indice tas_from_tasmin_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]]
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

mean_temperature_from_max_and_min (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.

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.potential_evapotranspiration(tasmin=None, tasmax=None, tas=None, lat=None, hurs=None, rsds=None, rsus=None, rlds=None, rlus=None, sfcWind=None, pr=None, *, method='BR65', peta=0.00516409319477, petb=0.0874972822289, ds=None)

Potential evapotranspiration (realm: convert)

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 provided, 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]]
pr (str or DataArray, optional) – Mean daily Precipitation Flux. [Required units : [precipitation]]
method ({‘allen98’, ‘BR65’, ‘hargreaves85’, ‘FAO_PM98’, ‘droogersallen02’, ‘thornthwaite48’, ‘baierrobertson65’, ‘MB05’, ‘HG85’, ‘DA02’, ‘mcguinnessbordne05’, ‘TW48’}) – 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.

Return type:

xarray.DataArray

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).
“droogersallen02” or “DA02”, based on Droogers and Allen [2002]. Requires tasmin, tasmax and precipitation, monthly [MS] or daily [D] freq. (optional: tas can be given in addition of tasmin and tasmax).

The McGuinness-Bordne [McGuinness and Borone, 1972] equation is:

\[PET[mm day^{-1}] = a * \frac{S_0}{\lambda}T_a + b * \frac{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”, “MB05” and “DA02” use an approximation of the extraterrestrial radiation. See extraterrestrial_solar_radiation().

References

Allen, Pereira, Raes, and Smith [1998], Baier and Robertson [1965], Droogers and Allen [2002], McGuinness and Borone [1972], Tanguy, Prudhomme, Smith, and Hannaford [2018], Thornthwaite [1948], George H. Hargreaves and Zohrab A. Samani [1985]

xclim.indicators.convert._conversion.rain_approximation(pr='pr', tas='tas', *, thresh='0 degC', method='binary', clip_temp=None, landmask=True, ds=None)

Rainfall approximation (realm: convert)

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’. Ignored for the 'dai_*' methods. Default : 0 degC. [Required units : [temperature]]
method ({‘dai_seasonal’, ‘dai_annual’, ‘brown’, ‘binary’, ‘auer’}) – Which method to use when approximating snowfall from total precipitation. See notes. Default : binary.
clip_temp (quantity (string or DataArray, with units)) – For methods “dai_annual” and “dai_seasonal”, this is an optional temperature delta at which the snowfall fraction function rescaled to 0 or 1. See notes. Default : None. [Required units : [temperature]]
landmask (DataArray or scalar) – For methods “dai_annual” and “dai_seasonal”, this is the land mask, a DataArray without a time dimension that is True on land grid points and False on ocean grid points. Can also be True or False to use one or the other coefficients set for all points. Default is to consider all points as land. Default : True.
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}.

Return type:

xarray.DataArray

Notes

For methods “binary”, “brown” and “auer”, this method computes the snowfall approximation and subtracts it from the total precipitation to estimate the liquid rain precipitation. See snowfall_approximation`().

For the “dai_*”, methods, the rain fraction evolves according to an hyperbolic tangent function that has different parameters for precipitation over land or ocean. The snow and rain fraction do not add to 1. Rather, the remainder can be associated to a “sleet” fraction.

If clip_temp is given, its value $$T_c$$ (in °C) is used to rescale (and then clip) the rain fraction function $$f(T)$$ as $$(f(T) - f(-T_c))/(f(T_c) - f(-T_c))$$, so that it is 0 when $$T < -T_c$$ and 1 when $$T > T_c$$.

The “dai_seasonal” method has different parameters for each season. The “annual” coefficients are taken over ocean in summer. These methods are implemented from [Dai, 2008] (clip_temp is an addition from the xclim team).

References

Dai [2008], Melton [2019], Verseghy [2009]

xclim.indicators.convert._conversion.relative_humidity(tas='tas', huss='huss', ps='ps', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', invalid_values='mask', ds=None)

Relative humidity from temperature, specific humidity, and pressure (realm: convert)

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.

Parameters:

tas (str or DataArray) – Mean Temperature. 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’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘bohren98’, ‘tetens30’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.
interp_power (number) – Optional interpolation for mixing saturation vapour pressures computed over water and ice. See saturation_vapor_pressure(). Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
invalid_values ({None, ‘clip’, ‘mask’}) – What to do with values outside the 0-100 range. If “clip” (default), clips everything to 0 - 100, if “mask”, replaces values outside the range by np.nan, and if None, does nothing. Default : mask.
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>

Return type:

xarray.DataArray

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 the ratio of actual vapor pressure to saturation vapor pressure:

\[RH = 100\frac{P_w}{P_{wsat}} P_w = \frac{pq}{\epsilon\left(1 + q\left(\frac{1}{\epsilon} - 1\right)\right)} \epsilon = 0.62198\]

The methods differ by how $P_{wsat}$ is computed. See the doc of saturation_vapor_pressure() and vapor_pressure(). This equation for RH is the same as eq. 4.A.15 of [World Meteorological Organization, 2008] and differs very slightly from MetPy which uses 4.A.16 by computing the mixing ratios first.

References

Bohren and Albrecht [1998], Lawrence [2005]

xclim.indicators.convert._conversion.relative_humidity_from_dewpoint(tas='tas', tdps='tdps', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', invalid_values='mask', ds=None)

Relative humidity from temperature and dewpoint temperature (realm: convert)

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.

Parameters:

tas (str or DataArray) – Mean Temperature. 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’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘bohren98’, ‘tetens30’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.
interp_power (number) – Optional interpolation for mixing saturation vapour pressures computed over water and ice. See saturation_vapor_pressure(). Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
invalid_values ({None, ‘clip’, ‘mask’}) – What to do with values outside the 0-100 range. If “clip” (default), clips everything to 0 - 100, if “mask”, replaces values outside the range by np.nan, and if None, does nothing. Default : mask.
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>

Return type:

xarray.DataArray

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.

\[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.

\[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 the ratio of actual vapor pressure to saturation vapor pressure:

\[RH = 100\frac{P_w}{P_{wsat}} P_w = \frac{pq}{\epsilon\left(1 + q\left(\frac{1}{\epsilon} - 1\right)\right)} \epsilon = 0.62198\]

References

Bohren and Albrecht [1998], Lawrence [2005]

xclim.indicators.convert._conversion.saturation_vapor_pressure(tas='tas', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', ds=None)

Saturation vapour pressure (e_sat) (realm: convert)

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) – Mean Temperature. 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. If given, see interp_power for more options. Default : None. [Required units : [temperature]]
method ({‘its90’, ‘wmo08’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘aerk96’, ‘buck81’, ‘tetens30’}) – Which saturation vapour pressure formula to use, see notes. Default : sonntag90.
interp_power (number) – Interpolation options for mixing saturation over water and over ice. See notes. Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
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>

Return type:

xarray.DataArray

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”, based on Goff and Gratch [1946], values and equation taken from Vömel [2016].
“sonntag90””, taken from SONNTAG [1990].
“tetens30”, based on Tetens [1930], values and equation taken from Vömel [2016].
“wmo08”, taken from World Meteorological Organization [2008].
“its90”, taken from Hardy [1998].
“buck81”, taken from Buck [1981].
“aerk96”, corresponds to formulas AERK and AERKi of Alduchov and Eskridge [1996]
“ecmwf”, taken from ECMWF [2016]. This uses “buck91” for saturation over water and “aerk96” for saturation over ice.

Water vs ice

This function implements 3 cases:

All water. When interp_power is None (default) and ice_thresh is None (default). Formulas use water as a reference. This might lead to relative humidities above 100 % for cold temperatures. This is usually what observational products use (World Meteorological Organization [2008]), and also how the dew point of ERA5 is computed.
Binary water-ice transition. When interp_power is None (default) and ``ice_thresh is given. The formulas with reference to water are used for temperatures above ice_thresh and the ones with reference to ice are used for temperatures equal to or under ice_thresh. Often used in models, this is what MetPy does.
Interpolation between water and ice. When interp_power, ice_thresh and water_thresh are all given, formulas with reference to water are used for temperatures above water_thresh, the formulas with reference to ice are used for temperatures below ice_thresh and an interpolation is used in between.

\[ \begin{align}\begin{aligned}e_{sat} = \alpha e_{sat(water)}(T) + (1 - \alpha) e_{sat(ice)}(T)\\\alpha = \left(\frac{T - T_i}{T_w - T_i}\right)^{\beta}\end{aligned}\end{align} \]

Where $T_{ice}$ is ice_thresh, $T_{w}$ is water_thresh and $\beta$ is interp_power.

As a note, a computation resembling what ECMWF’s IFS does to compute relative humidity would use: method = 'ecmwf', ice_thresh = 250.16 K, water_thresh = 273.16 K (default) and interp_power = 2 (ECMWF [2016]). Take note, however, that the 2m dew point temperature given by the IFS (ERA5, ERA5-Land) is computed with reference to water only.

References

Alduchov and Eskridge [1996], Buck [1981], ECMWF [2016], Goff and Gratch [1946], Hardy [1998], SONNTAG [1990], Tetens [1930], Vömel [2016], World Meteorological Organization [2008]

xclim.indicators.convert._conversion.shortwave_upwelling_radiation_from_net_downwelling(rss='rss', rsds='rsds', *, ds=None)

Upwelling shortwave radiation (realm: convert)

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.

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.snd_to_snw(snd='snd', *, snr=None, const='312 kg m-3', out_units=None, ds=None)

Surface snow amount (realm: convert)

Based on indice snd_to_snw().

Parameters:

snd (str or DataArray) – Snow Depth. Default : ds.snd. [Required units : [length]]
snr (quantity (string or DataArray, with units)) – Snow Density. Default : None. [Required units : [mass]/[volume]]
const (quantity (string or DataArray, with units)) – Constant snow density. const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]
out_units (str) – Desired units of the snow amount output. If None, output units simply follow from snd * snr. Default : None.
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.

Return type:

xarray.DataArray

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.convert._conversion.snowfall_approximation(pr='pr', tas='tas', *, thresh='0 degC', method='binary', clip_temp=None, landmask=True, ds=None)

Snowfall approximation (realm: convert)

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”. Ignored for the 'dai_*' methods. Default : 0 degC. [Required units : [temperature]]
method ({‘dai_seasonal’, ‘dai_annual’, ‘brown’, ‘binary’, ‘auer’}) – Which method to use when approximating snowfall from total precipitation. See notes. Default : binary.
clip_temp (quantity (string or DataArray, with units)) – For methods “dai_annual” and “dai_seasonal”, this is an optional temperature delta at which the snowfall fraction is rescaled to 0 or 1. See notes. Default : None. [Required units : [temperature]]
landmask (DataArray or scalar) – For methods “dai_annual” and “dai_seasonal”, this is the land mask, a DataArray without a time dimension that is True on land grid points and False on ocean grid points. Can also be True or False to use one or the other coefficients set for all points. Default is to consider all points as land. Default : True.
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}.

Return type:

xarray.DataArray

Notes

The following methods are available to approximate snowfall. 'brown' and 'auer' are drawn from the Canadian Land Surface Scheme [Melton, 2019, Verseghy, 2009]. The two 'dai_*' methods are implemented from [Dai, 2008] (clip_temp is an addition from the xclim team).

'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.
'dai_annual' : The snow fraction evolves according to an hyperbolic tangent function that has different parameters for precipitation over land or ocean. The snow and rain fractions do not add to 1, rather the remainder is denoted as a “sleet” fraction. If clip_temp is given, its value $$T_c$$ (in °C) is used to rescale (and then clip) the snowfall fraction function $$f(T)$$ as $$(f(T) - f(T_c))/(f(-T_c) - f(T_c))$$, so that it is 0 when $$T > T_c$$ and 1 when $$T < -T_c$$.
'dai_seasonal' : Same as 'dai_annual', but parameters are different for each season. The “annual” coefficients are taken over ocean in summer (JJA).

References

Dai [2008], Melton [2019], Verseghy [2009]

xclim.indicators.convert._conversion.snw_to_snd(snw='snw', *, snr=None, const='312 kg m-3', out_units=None, ds=None)

Surface snow depth (realm: convert)

Based on indice snw_to_snd().

Parameters:

snw (str or DataArray) – Snow amount. Default : ds.snw. [Required units : [mass]/[area]]
snr (quantity (string or DataArray, with units)) – Snow density. Default : None. [Required units : [mass]/[volume]]
const (quantity (string or DataArray, with units)) – Constant snow density. const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]
out_units (str) – Desired units of the snow depth output. If None, output units simply follow from snw / snr. Default : None.
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.

Return type:

xarray.DataArray

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.convert._conversion.specific_humidity(tas='tas', hurs='hurs', ps='ps', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', ds=None)

Specific humidity from temperature, relative humidity, and pressure (realm: convert)

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) – Mean Temperature. 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 ({‘wmo08’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘tetens30’}) – Which method to use, see notes of this function and of saturation_vapor_pressure(). Default : sonntag90.
interp_power (number) – Optional interpolation for mixing saturation vapour pressures computed over water and ice. See saturation_vapor_pressure(). Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
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>

Return type:

xarray.DataArray

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.convert._conversion.specific_humidity_from_dewpoint(tdps='tdps', ps='ps', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', ds=None)

Specific humidity from dew point temperature and pressure (realm: convert)

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. Default : ds.tdps. [Required units : [temperature]]
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 saturated vapour pressure equations in reference to ice instead of water. See saturation_vapor_pressure(). Default : None. [Required units : [temperature]]
method ({‘wmo08’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘aerk96’, ‘buck81’, ‘tetens30’}) – Method to compute the saturation vapour pressure. Default : sonntag90.
interp_power (number) – Optional interpolation for mixing saturation vapour pressures computed over water and ice. See saturation_vapor_pressure(). Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

huss (DataArray) – Specific humidity (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.

Return type:

xarray.DataArray

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.convert._conversion.tg(*args, **kwargs)[source]

xclim.indicators.convert._conversion.universal_thermal_climate_index(tas='tas', hurs='hurs', sfcWind='sfcWind', mrt=None, rsds=None, rsus=None, rlds=None, rlus=None, *, stat='sunlit', mask_invalid=True, wind_cap_min=False, ds=None)

Universal Thermal Climate Index (UTCI) (realm: convert)

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 ({‘sunlit’, ‘instant’}) – Which statistic to apply. 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. This is necessary if mrt is not None. Default : sunlit.
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. - 0.5 m/s < sfcWind < 17.0 m/s. Default : True.
wind_cap_min (boolean) – If True, wind velocities are capped to a minimum of 0.5 m/s following Bröde et al. [2012] usage guidelines. This ensures UTCI calculation for low winds. Default value False. Default : False.
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.

Return type:

xarray.DataArray

Notes

The calculation uses water vapour partial pressure, which is derived from relative humidity and saturation vapour pressure computed according to the ITS-90 equation.

This code was inspired by the pythermalcomfort and thermofeel packages.

For more information: https://www.utci.org/

References

Błażejczyk, Jendritzky, Bröde, Fiala, Havenith, Epstein, Psikuta, and Kampmann [2013], Bröde [2009], Bröde, Fiala, Błażejczyk, Holmér, Jendritzky, Kampmann, Tinz, and Havenith [2012]

xclim.indicators.convert._conversion.vapor_pressure(huss='huss', ps='ps', *, ds=None)

Vapour pressure. (realm: convert)

Computes the water vapour partial pressure in Pa from the specific humidity and the total pressure.

Based on indice vapor_pressure().

Parameters:

huss (str or DataArray) – Specific humidity [kg/kg]. Default : ds.huss. [Required units : []]
ps (str or DataArray) – Pressure. Default : ds.ps. [Required units : [pressure]]
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

vapor_pressure (DataArray) – Water vapour partial pressure. (water_vapor_partial_pressure_in_air) [Pa], with additional attributes: description: Water vapour partial pressure computed from specific humidity and total pressure.

Return type:

xarray.DataArray

Notes

The vapour pressure $\epsilon$ is computed with:

\[\]

e = frac{pq}{epsilon + (1 - epsilon)q}

Where $p$ is the pressure, $q$ is the specific humidity and $\epsilon$ us the ratio of the dry air gas constant to the water vapor gas constant : $\frac{R_{dry}}{R_{vapor}} = 0.62198$.

xclim.indicators.convert._conversion.vapor_pressure_deficit(tas='tas', hurs='hurs', *, ice_thresh=None, method='sonntag90', interp_power=None, water_thresh='0 °C', ds=None)

Water vapour pressure deficit (realm: convert)

Difference between the saturation vapour pressure and the actual vapour pressure.

Based on indice vapor_pressure_deficit().

Parameters:

tas (str or DataArray) – Mean daily temperature. Default : ds.tas. [Required units : [temperature]]
hurs (str or DataArray) – Relative humidity. Default : ds.hurs. [Required units : []]
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 ({‘its90’, ‘wmo08’, ‘ecmwf’, ‘goffgratch46’, ‘sonntag90’, ‘tetens30’}) – Method used to calculate saturation vapour pressure, see notes of saturation_vapor_pressure(). Default is “sonntag90”. Default : sonntag90.
interp_power (number) – Optional interpolation for mixing saturation vapour pressures computed over water and ice. See saturation_vapor_pressure(). Default : None.
water_thresh (quantity (string or DataArray, with units)) – When interp_power is given, this is the threshold temperature above which the formulas with reference to water are used. Default : 0 °C. [Required units : [temperature]]
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

vapor_pressure_deficit (DataArray) – Vapour pressure deficit (“{method}” method) (water_vapor_saturation_deficit_in_air) [Pa], with additional attributes: description: <Dynamically generated string>

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.water_budget(pr='pr', evspsblpot='evspsblpot', *, ds=None)

Water budget (realm: convert)

Precipitation minus potential evapotranspiration as a measure of an approximated surface water budget.

Based on indice water_budget(). With injected parameters: tasmin=None, tasmax=None, tas=None, lat=None, hurs=None, rsds=None, rsus=None, rlds=None, rlus=None, sfcWind=None, method=None.

Parameters:

pr (str or DataArray) – Daily precipitation. Default : ds.pr. [Required units : [precipitation]]
evspsblpot (str or DataArray) – Potential evapotranspiration. Default : ds.evspsblpot. [Required units : [precipitation]]
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.

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.water_budget_from_tas(pr='pr', 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: convert)

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(). With injected parameters: evspsblpot=None.

Parameters:

pr (str or DataArray) – Daily precipitation. Default : ds.pr. [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.

Return type:

xarray.DataArray

xclim.indicators.convert._conversion.wind_chill_index(tas='tas', sfcWind='sfcWind', *, method='CAN', ds=None)

Wind chill (realm: convert)

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 ({‘CAN’, ‘US’}) – 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>

Return type:

xarray.DataArray

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.convert._conversion.wind_power_potential(wind_speed='wind_speed', air_density=None, *, cut_in='3.5 m/s', rated='13 m/s', cut_out='25 m/s', ds=None)

Wind power potential (realm: convert)

Calculation of the wind power potential using a semi-idealized turbine power curve.

Based on indice wind_power_potential().

Parameters:

wind_speed (str or DataArray) – Wind Speed at the hub height. Use the wind_profile function to estimate from the surface wind speed. Default : ds.wind_speed. [Required units : [speed]]
air_density (str or DataArray, optional) – Air Density at the hub height. Defaults to 1.225 kg/m³. This is worth changing if applying in cold or mountainous regions with non-standard air density. [Required units : [air_density]]
cut_in (quantity (string or DataArray, with units)) – Cut-in wind speed. Default is 3.5 m/s. Default : 3.5 m/s. [Required units : [speed]]
rated (quantity (string or DataArray, with units)) – Rated wind speed. Default is 13 m/s. Default : 13 m/s. [Required units : [speed]]
cut_out (quantity (string or DataArray, with units)) – Cut-out wind speed. Default is 25 m/s. Default : 25 m/s. [Required units : [speed]]
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

wind_power_potential (DataArray) – Wind power potential, with additional attributes: description: Wind power potential using a semi-idealized turbine power curve using a cut_in speed of {cut_in}, a rated speed of {rated}, and a cut_out speed of {cut_out}.

Return type:

xarray.DataArray

Notes

This estimate of wind power production is based on an idealized power curve with four wind regimes specified by the cut-in wind speed ($u_i$), the rated speed ($u_r$) and the cut-out speed ($u_o$). Power production is zero for wind speeds below the cut-in speed, increases cubically between the cut-in and rated speed, is constant between the rated and cut-out speed, and is zero for wind speeds above the cut-out speed to avoid damage to the turbine [Tobin et al., 2018]:

\[\begin{split}\begin{cases} 0, & v < u_i \\ (v^3 - u_i^3) / (u_r^3 - u_i^3), & u_i ≤ v < u_r \\ 1, & u_r ≤ v < u_o \\ 0, & v ≥ u_o \end{cases}\end{split}\]

For non-standard air density ($\rho$), the wind speed is scaled using $v_n = v \left( \frac{\rho}{\rho_0} \right)^{1/3}$.

The temporal resolution of wind time series has a significant influence on the results: mean daily wind speeds yield lower values than hourly wind speeds. Note however that percent changes in the wind power potential climate projections are similar across resolutions [Chen, 2020].

To compute the power production, multiply the power production factor by the nominal turbine capacity (e.g. 100), set the units attribute (e.g. “MW”), resample and sum with xclim.indices.generic.select_resample_op(power, op=”sum”, freq=”D”), then convert to the desired units (e.g. “MWh”) using xclim.core.units.convert_units_to.

References

Chen [2020], Tobin, Greuell, Jerez, Ludwig, Vautard, van Vliet, and Bréon [2018].

xclim.indicators.convert._conversion.wind_profile(wind_speed='wind_speed', *, h, h_r, method='power_law', ds=None, **kwds)

Wind profile (realm: convert)

Calculation of the wind speed at a given height from the wind speed at a reference height.

Based on indice wind_profile().

Parameters:

wind_speed (str or DataArray) – Wind Speed at the reference height. Default : ds.wind_speed. [Required units : [speed]]
h (quantity (string or DataArray, with units)) – Height at which to compute the Wind Speed. Required. [Required units : [length]]
h_r (quantity (string or DataArray, with units)) – Reference height. Required. [Required units : [length]]
method ({‘power_law’}) – Method to use. Currently only “power_law” is implemented. Default : power_law.
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.
kwds – Additional keyword arguments to pass to the method.For power_law, this is alpha, which takes a default value of 1/7, but is highly variable based on topography, surface cover and atmospheric stability. Required.

Returns:

wind_speed (DataArray) – Wind speed at height {h} (wind_speed) [m s-1], with additional attributes: description: Wind speed at a height of {h} computed from the wind speed at {h_r} using a power law profile.

Return type:

xarray.DataArray

Notes

The power law profile is given by:

\[v = v_r \left( \frac{h}{h_r} \right)^{\alpha},\]

where $v_r$ is the wind speed at the reference height, $h$ is the height at which the wind speed is desired, and $h_r$ is the reference height.

xclim.indicators.convert._conversion.wind_speed_from_vector(uas='uas', vas='vas', *, calm_wind_thresh='0.5 m/s', ds=None)

Wind speed and direction from vector (realm: convert)

Calculation of the magnitude and direction of the wind speed from the two components west-east and south-north.

Based on indice uas_vas_to_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}.

Return type:

tuple[xarray.DataArray, xarray.DataArray]

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.convert._conversion.wind_vector_from_speed(sfcWind='sfcWind', sfcWindfromdir='sfcWindfromdir', *, ds=None)

Wind vector from speed and direction (realm: convert)

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_to_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” denotes “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.

Return type:

tuple[xarray.DataArray, xarray.DataArray]