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 when 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 when snowfall and wind speeds are above respective thresholds. [days], with additional attributes: 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.
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), 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: 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.
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), 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
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), with additional attributes: 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.
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], with additional attributes: 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], with additional attributes: 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], with additional attributes: 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], with additional attributes: 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), with additional attributes: 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], with additional attributes: 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, with additional attributes: 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 0x7f1896cc4670>.- 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}, with additional attributes: 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 0x7f1896cc4700>.- 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}, with additional attributes: 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 ({‘ML’, ‘PWM’}) – Fitting method, either maximum likelihood (ML) or probability weighted moments (PWM), also called L-Moments. The PWM method is usually more robust to outliers. Default : ML.
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(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 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], 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)
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].
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} 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
Baker, Richards, Loftus, and Kramer [2004]
- 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’, ‘sum’, ‘argmax’, ‘var’, ‘max’, ‘argmin’, ‘mean’, ‘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], with additional attributes: description: {freq} {op} of {indexer} daily flow