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: str = '5 cm', sfcWind_thresh: str = '15 km/h', window: int = 3, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

Days with blowing snow events. (realm: land)

Number of days where both snowfall over the last days and daily wind speeds are above respective thresholds.

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 with units)) – Threshold on net snowfall accumulation over the last window days. Default : 5 cm. [Required units : [length]]

  • sfcWind_thresh (quantity (string 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) – Number of days where snowfall and wind speeds are above respective thresholds. [days] description: {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: str = '2 cm', window: int = 14, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

End date of continuous snow cover. (realm: land)

First day after the start of the continuous snow cover when snow depth is below threshold for at least window consecutive days. WARNING: The default freq is valid for the northern hemisphere.

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 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) description: Day of year when snow depth is below {thresh} for {window} consecutive days.

References

Chaumont D., Mailhot A., Diaconescu E.P., Fournier É., Logan T. 2017: Élaboration du portrait bioclimatique futur du Nunavik – Tome II. [Rapport présenté au Ministère de la forêt, de la faune et des parcs], Ouranos.

xclim.indicators.land._snow.continuous_snow_cover_start(snd: Union[DataArray, str] = 'snd', *, thresh: str = '2 cm', window: int = 14, freq: str = 'AS-JUL', ds: Dataset = None) → DataArray

Start date of continuous snow cover. (realm: land)

Day of year when snow depth is above or equal threshold for at least window consecutive days. WARNING: The default freq is valid for the northern hemisphere.

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 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) description: Day of year when snow depth is above or equal to {thresh} for {window} consecutive days.

References

Chaumont D., Mailhot A., Diaconescu E.P., Fournier É., Logan T. 2017: Élaboration du portrait bioclimatique futur du Nunavik – Tome II. [Rapport présenté au Ministère de la forêt, de la faune et des parcs], Ouranos.

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

Maximum snow depth day of year. (realm: land)

Day of year when surface snow reaches its peak value. If snow depth is 0 over entire period, return NaN.

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) – Date when snow depth reaches its maximum value. (day_of_year) description: {freq} day of year when snow depth reaches its maximum value.

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

Number of days with snow depth above a threshold. (realm: land)

Number of days where surface snow depth is greater or equal to given threshold. WARNING: The default freq is valid for the northern hemisphere.

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 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 above threshold [days] description: {freq} number of days with snow depth greater or equal to {thresh}

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

Mean of daily average snow depth. (realm: land)

Resample the original daily mean snow depth series by taking the mean over each period.

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

Parameters

  • snd (str or DataArray) – 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] cell_methods: time: mean over days description: {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 maximum snow melt over a given number of days expressed in snow water equivalent.

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) – The maximum snow melt over a given number of days for each period. [mass/area]. (change_over_time_in_surface_snow_amount) [kg m-2] description: {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 daily snow amount.

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 daily snow amount (surface_snow_amount) [kg m-2] description: {freq} day of year when snow amount on the surface reaches its maximum.

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

Maximum snow amount day of year. (realm: land)

Day of year when surface snow amount reaches its peak value. If snow amount is 0 over entire period, return NaN.

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 (day_of_year) description: {freq} maximum snow amount on the surface.

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

Days with snowfall over threshold. (realm: land)

Number of days with snowfall accumulation greater or equal to threshold.

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 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) – Number of days per period identified as winter storms. [days] description: {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 description: Minimum 7-day 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. (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 0x7fea13c34f70>.

Parameters

  • da (str or DataArray) – Input data. Default : ds.da.

  • 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 over {indexer} description: Day of the year of the maximum 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. (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 0x7fea13c10040>.

Parameters

  • da (str or DataArray) – Input data. Default : ds.da.

  • 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 over {indexer} description: Day of the year of the minimum over {indexer}

xclim.indicators.land._streamflow.fit(da: Union[DataArray, str] = 'da', *, 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

  • da (str or DataArray) – Time series to be fitted along the time dimension. Default : ds.da.

  • dist (str) – Name of the univariate distribution, such as beta, expon, genextreme, gamma, gumbel_r, lognorm, norm (see 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 ({‘PWM’, ‘ML’}) – 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.

  • 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) 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(da: Union[DataArray, str] = 'da', *, mode: str, t: int | Sequence[int], dist: str, window: int = 1, freq: str | None = None, ds: Dataset = None, **indexer) → DataArray

Flow values for given return periods. (realm: land)

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

Parameters

  • da (str or DataArray) – Input data. Default : ds.da.

  • mode ({‘min’, ‘max’}) – Whether we are looking for a probability of exceedance (high) or a probability of non-exceedance (low). Default : ds.da.

  • 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.da.

  • dist (str) – Name of the univariate distribution, such as beta, expon, genextreme, gamma, gumbel_r, lognorm, norm (see scipy.stats). Default : ds.da.

  • 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 period {mode} {indexer} {window}-day flow [m^3 s-1] 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)

Measures oscillations in flow relative to total flow, quantifying the frequency and rapidity of short term changes in flow, based on Baker et al. (2004; [baker2004]).

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 description: {freq} R-B 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

baker2004

Baker, D. B., Richards, R. P., Loftus, T. T., & Kramer, J. W. (2004). A New Flashiness Index: Characteristics and Applications to Midwestern Rivers and Streams1. JAWRA Journal of the American Water Resources Association, 40(2), 503‑522. https://doi.org/10.1111/j.1752-1688.2004.tb01046.x

xclim.indicators.land._streamflow.stats(da: Union[DataArray, str] = 'da', *, op: str, freq: str = 'YS', ds: Dataset = None, **indexer) → DataArray

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

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

Parameters

  • da (str or DataArray) – Input data. Default : ds.da.

  • op ({‘min’, ‘max’, ‘argmin’, ‘mean’, ‘var’, ‘argmax’, ‘sum’, ‘count’, ‘std’}) – Reduce operation. Can either be a DataArray method or a function that can be applied to a DataArray. Default : ds.da.

  • 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) – {freq} {op} of {indexer} daily flow [m^3 s-1] description: {freq} {op} of {indexer} daily flow