xclim.indicators.land package

Land indicators

Submodules

xclim.indicators.land._snow module

xclim.indicators.land._snow.blowing_snow(snd: Union[DataArray, str] = 'snd', sfcWind: Union[DataArray, str] = 'sfcWind', *, snd_thresh: Quantified = '5 cm', sfcWind_thresh: Quantified = '15 km/h', window: int = 3, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

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._snow.continuous_snow_cover_end(snd: Union[DataArray, str] = 'snd', *, thresh: Quantified = '2 cm', window: int = 14, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

End date of continuous snow 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 continuous_snow_cover_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

continuous_snow_cover_end (DataArray) – End date of continuous snow 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._snow.continuous_snow_cover_start(snd: Union[DataArray, str] = 'snd', *, thresh: Quantified = '2 cm', window: int = 14, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

Start date of continuous snow 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 continuous_snow_cover_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

continuous_snow_cover_start (DataArray) – Start date of continuous snow 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._snow.snd_max_doy(snd: Union[DataArray, str] = 'snd', *, freq: str = 'AS-JUL', ds: Dataset = None, **indexer) → DataArray

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._snow.snow_cover_duration(snd: Union[DataArray, str] = 'snd', *, thresh: Quantified = '2 cm', freq: str = 'AS-JUL', ds: Dataset = None, **indexer) → DataArray

Snow cover duration (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 snow_cover_duration().

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.
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_cover_duration (DataArray) – Number of days with snow depth at or above threshold [days], with additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

xclim.indicators.land._snow.snow_depth(snd: Union[DataArray, str] = 'snd', *, freq: str = 'YS', ds: Dataset = None, **indexer) → DataArray

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.snow_melt_we_max(snw: Union[DataArray, str] = 'snw', *, window: int = 3, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

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._snow.snw_max(snw: Union[DataArray, str] = 'snw', *, freq: str = 'AS-JUL', ds: Dataset = None, **indexer) → DataArray

Maximum snow amount (realm: land)

The maximum snow water equivalent amount 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 water equivalent amount (surface_snow_amount) [kg m-2], with additional attributes: description: The {freq} maximum snow water equivalent amount on the surface.

xclim.indicators.land._snow.snw_max_doy(snw: Union[DataArray, str] = 'snw', *, freq: str = 'AS-JUL', ds: Dataset = None, **indexer) → DataArray

Day of year of maximum snow amount (realm: land)

The day of year when snow water equivalent amount 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 water equivalent amount (day_of_year), with additional attributes: description: The {freq} day of year when snow water equivalent amount on the surface reaches its maximum.

xclim.indicators.land._snow.winter_storm(snd: Union[DataArray, str] = 'snd', *, thresh: Quantified = '25 cm', freq: str = 'AS-JUL', ds: Dataset = None, **indexer) → DataArray

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.

xclim.indicators.land._streamflow module

Streamflow indicator definitions.

xclim.indicators.land._streamflow.base_flow_index(q: Union[DataArray, str] = 'q', *, freq: str = 'YS', ds: Dataset = None) → DataArray

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._streamflow.doy_qmax(da: Union[DataArray, str] = 'da', *, freq: str = 'YS', ds: Dataset = None, **indexer) → DataArray

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 0x7fbe732e3520>.

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._streamflow.doy_qmin(da: Union[DataArray, str] = 'da', *, freq: str = 'YS', ds: Dataset = None, **indexer) → DataArray

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 0x7fbe732e35b0>.

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._streamflow.fit(discharge: Union[DataArray, str] = 'discharge', *, dist: str = 'norm', method: str = 'ML', dim: str = 'time', ds: Dataset = None, **fitkwargs) → DataArray

Distribution parameters fitted over the time dimension. (realm: land)

Based on indice fit().

Parameters

discharge (str or DataArray) – The amount of water, in all phases, flowing in the river channel and flood plain. Default : ds.discharge. [Required units : m3 s-1]
dist (str) – Name of the univariate distribution, such as beta, expon, genextreme, gamma, gumbel_r, lognorm, norm (see :py:mod:scipy.stats for full list). If the PWM method is used, only the following distributions are currently supported: ‘expon’, ‘gamma’, ‘genextreme’, ‘genpareto’, ‘gumbel_r’, ‘pearson3’, ‘weibull_min’. Default : norm.
method ({‘APP’, ‘ML’, ‘PWM’}) – Fitting method, either maximum likelihood (ML), probability weighted moments (PWM), also called L-Moments, or approximate method (APP). The PWM method is usually more robust to outliers. Default : ML.
dim (str) – The dimension upon which to perform the indexing (default: “time”). Other arguments passed directly to _fitstart() and to the distribution’s fit. Default : time.
ds (Dataset, optional) – A dataset with the variables given by name. Default : None.
fitkwargs – Default : None.

Returns

params (DataArray) – {dist} distribution parameters ({dist} parameters), with additional attributes: cell_methods: time: fit; description: Parameters of the {dist} distribution.

Notes

Coordinates for which all values are NaNs will be dropped before fitting the distribution. If the array still contains NaNs, the distribution parameters will be returned as NaNs.

xclim.indicators.land._streamflow.freq_analysis(discharge: Union[DataArray, str] = 'discharge', *, mode: str, t: int | Sequence[int], dist: str, window: int = 1, freq: str | None = None, ds: Dataset = None, **indexer) → DataArray

Return level (realm: land)

Streamflow frequency analysis on the basis of a given mode and distribution.

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

Parameters

discharge (str or DataArray) – The amount of water, in all phases, flowing in the river channel and flood plain. Default : ds.discharge. [Required units : m3 s-1]
mode ({‘max’, ‘min’}) – Whether we are looking for a probability of exceedance (high) or a probability of non-exceedance (low). Default : ds.discharge.
t (number or sequence of numbers) – Return period. The period depends on the resolution of the input data. If the input array’s resolution is yearly, then the return period is in years. Default : ds.discharge.
dist (str) – Name of the univariate distribution, e.g. beta, expon, genextreme, gamma, gumbel_r, lognorm, norm. Default : ds.discharge.
window (number) – Averaging window length (days). Default : 1.
freq (offset alias (string)) – Resampling frequency. If None, the frequency is assumed to be ‘YS’ unless the indexer is season=’DJF’, in which case freq would be set to AS-DEC. Default : None.
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{window}{mode (r}{indexer} : DataArray) – N-year return level discharge [m^3 s-1], with additional attributes: description: Streamflow frequency analysis for the {mode} {indexer} {window}-day flow estimated using the {dist} distribution.

xclim.indicators.land._streamflow.rb_flashiness_index(q: Union[DataArray, str] = 'q', *, freq: str = 'YS', ds: Dataset = None) → DataArray

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._streamflow.stats(discharge: Union[DataArray, str] = 'discharge', *, op: str, freq: str = 'YS', ds: Dataset = None, **indexer) → DataArray

Statistic of the daily flow for a given period. (realm: land)

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

Parameters

discharge (str or DataArray) – The amount of water, in all phases, flowing in the river channel and flood plain. Default : ds.discharge. [Required units : m3 s-1]
op ({‘max’, ‘min’, ‘mean’, ‘sum’, ‘var’, ‘argmin’, ‘count’, ‘std’, ‘argmax’}) – Reduce operation. Can either be a DataArray method or a function that can be applied to a DataArray. Default : ds.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}{op (r} : DataArray) – Daily flow statistics [m^3 s-1], with additional attributes: description: {freq} {op} of daily flow ({indexer}).