xclim.indicators.land package¶

Land Indicators¶

Submodules¶

xclim.indicators.land._snow module¶

Snow indicator definitions.

xclim.indicators.land._snow.blowing_snow(snd='snd', sfcWind='sfcWind', *, snd_thresh='5 cm', sfcWind_thresh='15 km/h', window=3, freq='YS-JUL', ds=None, **indexer)

Blowing snow days

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 function blowing_snow().

Parameters:

snd (str or DataArray) – Surface snow depth. Default: ‘snd’. [Required units : [length]]
sfcWind (str or DataArray) – Wind velocity. Default: ‘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: ‘YS-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. The subset is taken after summing the snowfall over the window. It accepts the same arguments as xclim.compute.generic.select_time().

Returns:

xarray.DataArray, [days] – Days with snowfall and wind speed at or above given thresholds. With additional attributes: description: The {freq} number of days with snowfall over last {window} days above {snd_thresh} and wind speed above {sfcWind_thresh}.

Return type:

xarray.DataArray

xclim.indicators.land._snow.holiday_snow_and_snowfall_days(snd='snd', prsn=None, *, snd_thresh='20 mm', prsn_thresh='1 mm', snd_condition='>=', prsn_condition='>=', date_start='12-25', date_end=None, freq='YS-JUL', ds=None)

Perfect Christmas snow days

The total number of days where there is a significant amount of snow on the ground and a measurable snowfall occurring on December 25th.

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

Parameters:

snd (str or DataArray) – Surface snow depth. Default: ‘snd’. [Required units : [length]]
prsn (str or DataArray, optional) – Snowfall flux. Default: None. [Required units : [precipitation]]
snd_thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default: 20 mm. Default: ‘20 mm’. [Required units : [length]]
prsn_thresh (quantity (string or DataArray, with units)) – Threshold daily snowfall liquid-water equivalent thickness. Default: 1 mm. Default: ‘1 mm’. [Required units : [length]]
snd_condition ({‘>=’, ‘ge’, ‘gt’, ‘>’}) – Comparison operation for snow depth. Default: “>=”. Default: ‘>=’.
prsn_condition ({‘>=’, ‘ge’, ‘gt’, ‘>’}) – Comparison operation for snowfall flux. Default: “>=”. Default: ‘>=’.
date_start (str) – Beginning of analysis period. Default: “12-25” (December 25th). Default: ‘12-25’.
date_end (str) – End of analysis period. If not provided, date_start is used. Default: None. Default: None.
freq (offset alias (string)) – Resampling frequency. Default: “YS-JUL”. The default value is chosen for the northern hemisphere. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [days] – Number of holiday days with snow and snowfall. With additional attributes: description: The total number of days where snow on the ground was greater than or equal to {snd_thresh} and snowfall was greater than or equal to {prsn_thresh} occurring on {date_start} and ending on {date_end}.

Return type:

xarray.DataArray

References

https://www.canada.ca/en/environment-climate-change/services/weather-general-tools-resources/historical-christmas-snowfall-data.html

xclim.indicators.land._snow.holiday_snow_days(snd='snd', *, snd_thresh='20 mm', condition='>=', date_start='12-25', date_end=None, freq='YS', ds=None)

Christmas snow days

The total number of days where there is a significant amount of snow on the ground on December 25th.

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

Parameters:

snd (str or DataArray) – Surface snow depth. Default: ‘snd’. [Required units : [length]]
snd_thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default: 20 mm. Default: ‘20 mm’. [Required units : [length]]
condition ({‘>=’, ‘ge’, ‘gt’, ‘>’}) – Comparison operation. Default: “>=”. Default: ‘>=’.
date_start (str) – Beginning of the analysis period. Default: “12-25” (December 25th). Default: ‘12-25’.
date_end (str) – End of analysis period. If not provided, date_start is used. Default: None. Default: None.
freq (offset alias (string)) – Resampling frequency. Default: “YS”. The default value is chosen for the northern hemisphere. Default: ‘YS’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [days] – Number of holiday days with snow. With additional attributes: description: The total number of days where snow on the ground was greater than or equal to {snd_thresh} occurring on {date_start} and ending on {date_end}.

Return type:

xarray.DataArray

References

https://www.canada.ca/en/environment-climate-change/services/weather-general-tools-resources/historical-christmas-snowfall-data.html

xclim.indicators.land._snow.snd_days_above(snd='snd', *, condition='>=', thresh='2 cm', freq='YS-JUL', ds=None, **indexer)

Days with snow (depth)

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 function count_occurrences(). With injected parameters: constrain=(‘>’, ‘>=’).

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
condition ({‘>=’, ‘>’, ‘le’, ‘gt’, ‘<’, ‘ge’, ‘lt’, ‘<=’}) – Logical comparison operator. Comparison is done as data {condition} thresh. Default: ‘>=’.
thresh (quantity (string or DataArray, with units)) – Threshold value. Should have the same dimensionality as data. Default: ‘2 cm’. [Required units : ([length])]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, the time dimension is completely reduced. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Number of days with snow. With additional attributes: description: The {freq} number of days with snow depth greater than or equal to {thresh}.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_max(snd='snd', *, freq='YS-JUL', ds=None, **indexer)

Maximum snow depth

The maximum snow depth on the surface.

This indicator will check for missing values according to the method “from_context”. Based on function statistics(). With injected parameters: statistic=max, out_units=None.

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [mm] – snow_depth, Maximum snow depth. With additional attributes: description: The {freq} maximum snow depth on the surface.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_max_doy(snd='snd', *, freq='YS-JUL', ds=None)

Day of year of maximum snow depth

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 function snd_max_doy().

Parameters:

snd (str or DataArray) – Surface snow depth. Default: ‘snd’. [Required units : [length]]
freq (offset alias (string)) – Resampling frequency. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray – day_of_year, Day of the year when snow depth reaches its maximum value. With additional attributes: description: The {freq} day of the year when snow depth reaches its maximum value.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_season_end(snd='snd', *, thresh='2 cm', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover end date (depth).

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 function season(). With injected parameters: condition=>=, aspect=end, mid_date=None, constrain=None.

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘2 cm’. [Required units : ([length])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [dimensionless] or [time] – day_of_year, End date of continuous snow depth cover. With additional attributes: description: Day of year when snow depth is below {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_season_length(snd='snd', *, thresh='2 cm', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover duration (depth).

The season starts when snow depth is above a threshold for at least N consecutive daysand stops when it drops below the same threshold for the same number of days.

This indicator will check for missing values according to the method “from_context”. Based on function season(). With injected parameters: condition=>=, aspect=length, mid_date=None, constrain=None.

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘2 cm’. [Required units : ([length])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Snow cover duration. With additional attributes: description: The duration of the snow season, starting with at least {window} days with snow depth above {thresh} and ending with at least {window} days with snow depth under {thresh}.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_season_start(snd='snd', *, thresh='2 cm', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover start date (depth).

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 function season(). With injected parameters: condition=>=, aspect=start, mid_date=None, constrain=None.

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘2 cm’. [Required units : ([length])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [dimensionless] or [time] – day_of_year, Start date of continuous snow depth cover. With additional attributes: description: Day of year when snow depth is above or equal to {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snd_storm_days(snd='snd', *, thresh='25 cm', freq='YS-JUL', ds=None, **indexer)

Winter storm days

Number of days with snowfall depth accumulation greater or equal to threshold (default: 25 cm).

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

Parameters:

snd (str or DataArray) – Surface snow depth. Default: ‘snd’. [Required units : [length]]
thresh (quantity (string or DataArray, with units)) – Threshold on snowfall depth accumulation require to label an event a snd storm. Default: ‘25 cm’. [Required units : [length]]
freq (offset alias (string)) – Resampling frequency. Default: ‘YS-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.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Days with snowfall depth at or above a given threshold. With additional attributes: description: The {freq} number of days with snowfall depth accumulation above {thresh}.

Return type:

xarray.DataArray

Notes

Snowfall accumulation is estimated by the change in snow depth.

xclim.indicators.land._snow.snow_depth(snd='snd', *, freq='YS', ds=None, **indexer)

Mean snow depth

Mean of daily snow depth.

This indicator will check for missing values according to the method “from_context”. Based on function statistics(). With injected parameters: statistic=mean, out_units=None.

Parameters:

snd (str or DataArray) – Surface snow thickness. Default: ‘snd’. [Required units : [length]]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, time dimension is reduced completely. 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. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [cm] – surface_snow_thickness, Mean of daily snow depth. With additional attributes: description: The {freq} mean of daily mean snow depth., cell_methods: time: mean over days

Return type:

xarray.DataArray

xclim.indicators.land._snow.snow_melt_we_max(snw='snw', *, window=3, freq='YS-JUL', ds=None)

Maximum snow melt

The water equivalent of the maximum snow melt.

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

Parameters:

snw (str or DataArray) – Snow amount (mass per area). Default: ‘snw’. [Required units : [snowamount]]
window (number) – Number of days during which the melt is accumulated. Default: 3.
freq (offset alias (string)) – Resampling frequency. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [kg m-2] – change_over_time_in_surface_snow_amount, Maximum snow melt. With additional attributes: description: The {freq} maximum negative change in melt amount over {window} days.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_days_above(snw='snw', *, condition='>=', thresh='4 kg m-2', freq='YS-JUL', ds=None, **indexer)

Days with snow (amount)

Number of days when the snow amount is greater than or equal to a given threshold.

This indicator will check for missing values according to the method “from_context”. Based on function count_occurrences(). With injected parameters: constrain=(‘>’, ‘>=’).

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [mass]/[area]]
condition ({‘>=’, ‘>’, ‘le’, ‘gt’, ‘<’, ‘ge’, ‘lt’, ‘<=’}) – Logical comparison operator. Comparison is done as data {condition} thresh. Default: ‘>=’.
thresh (quantity (string or DataArray, with units)) – Threshold value. Should have the same dimensionality as data. Default: ‘4 kg m-2’. [Required units : ([mass]/[area])]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, the time dimension is completely reduced. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Number of days with snow. With additional attributes: description: The {freq} number of days with snow amount greater than or equal to {thresh}.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_max(snw='snw', *, freq='YS-JUL', ds=None, **indexer)

Maximum snow amount

The maximum snow amount equivalent on the surface.

This indicator will check for missing values according to the method “from_context”. Based on function statistics(). With injected parameters: statistic=max, out_units=None.

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [mass]/[area]]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [kg m-2] – surface_snow_amount, Maximum snow amount equivalent. With additional attributes: description: The {freq} maximum snow amount equivalent on the surface.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_max_doy(snw='snw', *, freq='YS-JUL', ds=None)

Day of year of maximum snow amount

The day of year when snow amount equivalent on the surface reaches its maximum.

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

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [snowamount]]
freq (offset alias (string)) – Resampling frequency. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray – day_of_year, Day of year of maximum daily snow amount equivalent. With additional attributes: description: The {freq} day of year when snow amount equivalent on the surface reaches its maximum.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_season_end(snw='snw', *, thresh='4 kg m-2', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover end date (amount).

The first date on which snow amount is below a given threshold for a given number of consecutive days.

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [mass]/[area]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘4 kg m-2’. [Required units : ([mass]/[area])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [dimensionless] or [time] – day_of_year, End date of continuous snow amount cover. With additional attributes: description: Day of year when snow amount is below {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_season_length(snw='snw', *, thresh='4 kg m-2', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover duration (amount).

The season starts when the snow amount is above a threshold for at least N consecutive daysand stops when it drops below the same threshold for the same number of days.

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [mass]/[area]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘4 kg m-2’. [Required units : ([mass]/[area])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Snow cover duration. With additional attributes: description: The duration of the snow season, starting with at least {window} days with snow amount above {thresh} and ending with at least {window} days with snow amount under {thresh}.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_season_start(snw='snw', *, thresh='4 kg m-2', window=14, freq='YS-JUL', ds=None, **indexer)

Snow cover start date (amount).

The first date on which snow amount is greater than or equal to a given threshold for a given number of consecutive days.

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [mass]/[area]]
thresh (quantity (string or DataArray, with units)) – Threshold for the condition. Default: ‘4 kg m-2’. [Required units : ([mass]/[area])]
window (number) – Minimum number of days that the condition must be met / not met for the start / end of the season. Default: 14.
freq (offset alias (string)) – Resampling frequency. If None, time dimension is reduced completely. Default: ‘YS-JUL’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.
indexer – Time attribute and values over which to subset the array. See xclim.core.calendar.select_time().

Returns:

xarray.DataArray, [dimensionless] or [time] – day_of_year, Start date of continuous snow amount cover. With additional attributes: description: Day of year when snow amount is above or equal to {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

xclim.indicators.land._snow.snw_storm_days(snw='snw', *, thresh='10 kg m-2', freq='YS-JUL', ds=None, **indexer)

Winter storm days

Number of days with snowfall amount accumulation greater or equal to threshold (default: 10 kg m-2).

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

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [snowamount]]
thresh (quantity (string or DataArray, with units)) – Threshold on snowfall amount accumulation require to label an event a snw storm. Default: ‘10 kg m-2’. [Required units : [snowamount]]
freq (offset alias (string)) – Resampling frequency. Default: ‘YS-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.core.calendar.select_time().

Returns:

xarray.DataArray, [days] – Days with snowfall amount at or above a given threshold. With additional attributes: description: The {freq} number of days with snowfall amount accumulation above {thresh}.

Return type:

xarray.DataArray

Notes

Snowfall accumulation is estimated by the change in snow amount.

xclim.indicators.land._streamflow module¶

Streamflow indicator definitions.

xclim.indicators.land._streamflow.base_flow_index(rivo='rivo', *, freq='YS', ds=None)

Base flow index

Minimum of the 7-day moving average flow divided by the mean flow.

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

Parameters:

rivo (str or DataArray) – Rate of river discharge. Default: ‘rivo’. [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:

xarray.DataArray, [dimensionless] – Base flow index. With additional attributes: description: Minimum of the 7-day moving average flow divided by the mean flow.

Return type:

xarray.DataArray

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.base_flow_index_seasonal_ratio(rivo='rivo', *, freq='QS-DEC', numerator='DJF', denominator='JJA', ds=None)

Seasonal Base flow index (bfi) and {numerator} to {denominator} bfi ratio

Yearly base flow index per season, defined as the minimum 7-day average flow divided by the mean flowas well as yearly {numerator} to {denominator} bfi ratio.

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

Parameters:

rivo (str or DataArray) – Rate of river discharge. Default: ‘rivo’. [Required units : [discharge]]
freq (offset alias (string)) – Resampling frequency. Default: ‘QS-DEC’.
numerator (str) – String indicating the season in the numerator of the ratio. Default: ‘DJF’.
denominator (str) – String indicating the season in the denominator of the ratio. Default: ‘JJA’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

bfi (xarray.DataArray, [dimensionless]) – Seasonal baseflow index. With additional attributes: description: Yearly base flow index per season, defined as the minimum 7-day average flow divided by the mean flow.
bfi_ratio (xarray.DataArray, [dimensionless]) – Baseflow index season ratio. With additional attributes: description: Yearly baseflow index {numerator} to {denominator} ratio, defined as the minimum 7-day average flow divided by the mean flow as well.

Return type:

tuple[xarray.DataArray, xarray.DataArray]

Notes

It is recommended to have at least 70% of valid data per month in order to compute significant values. The default arguments compute the bfi ratio of the winter (“DJF”) to summer (“JJA”) ratio.

References

Singh, Pahlow, Booker, Shankar, and Chamorro [2019] Jaffrés, Cuff, Cuff, Faichney, Knott, and Rasmussen [2021]

xclim.indicators.land._streamflow.flow_index(rivo='rivo', *, q=0.95, ds=None)

Flow index

Calculate the qth quantile of daily streamflow normalized by the median flow.

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

Parameters:

rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [Required units : [discharge]]
q (number) – Quantile for calculating the flow index, between 0 and 1. Default of 0.95 is for high flows. Default: 0.95.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [1] – Flow index. With additional attributes: description: {q}th quantile normalized by the median flow.

Return type:

xarray.DataArray

References

Clausen and Biggs [2000]

xclim.indicators.land._streamflow.high_flow_frequency(rivo='rivo', *, threshold_factor=9, freq='YS-OCT', ds=None)

High flow frequency

Calculate the number of days in a given period with flows greater than a specified threshold, given as a multiple of the median flow. By default, the period is the water year starting on 1st October and ending on 30th September, as commonly defined in North America.

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

Parameters:

rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [Required units : [discharge]]
threshold_factor (number) – Factor by which the median flow is multiplied to set the high flow threshold, default is 9. Default: 9.
freq (offset alias (string)) – Resampling frequency, default is ‘YS-OCT’ for water year starting in October and ending in September. Default: ‘YS-OCT’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [days] – High flow frequency. With additional attributes: description: {freq} frequency of flows greater than {threshold_factor} times the median flow.

Return type:

xarray.DataArray

References

Addor, Nearing, Prieto, Newman, Le Vine, and Clark [2018], Clausen and Biggs [2000]

xclim.indicators.land._streamflow.lag_snowpack_flow_peaks(snw='snw', rivo='rivo', *, freq='YS-OCT', q=0.9, ds=None)

Time lag between maximum snowpack and river high flows

Number of days between the annual maximum snowpack, measured by the surface snow amount, and the mean date when river flow exceeds a quantile threshold during a given year. If the time lag between maximum snowpack and river high flows is ≤ 50 days, the watershed is likely in a nival regime.

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

Parameters:

snw (str or DataArray) – Surface snow amount. Default: ‘snw’. [Required units : [snowamount]]
rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [Required units : [discharge]]
freq (offset alias (string)) – Resampling frequency. Defaults to the water year starting on the 1st of October. Default: ‘YS-OCT’.
q (number) – Quantile for calculating the flow index, between 0 and 1. Default of 0.9 is for high flows. Default: 0.9.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [days] – Time lag between maximum snowpack and river high flows. With additional attributes: description: Number of days between the annual maximum snowpack, measured by the snow waterequivalent, and the mean date when river flow exceeds a quantile thresholdduring a given year.

Return type:

xarray.DataArray

Notes

The default freq is the water year used in the Northern Hemisphere, from October to September.
It is recommended to have at least 70% of valid data per water year in order to compute significant values.
Nival regime is characterized by a hydrological response dominated by snowmelt, where maximum flows occur shortly after peak snow cover (Burn et al., 2010).
The 50-day threshold is approximate and depends on the specific responsiveness of each watershed.
A negative value means the high flows occur before the peak snow cover.

References

Burn, Sharif, and Zhang [2010]

xclim.indicators.land._streamflow.low_flow_frequency(rivo='rivo', *, threshold_factor=0.2, freq='YS-OCT', ds=None)

Low flow frequency

Calculate the number of days in a given period with flows lower than a specified threshold, given by a fraction of the mean flow. By default, the period is the water year starting on 1st October and ending on 30th September, as commonly defined in North America.

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

Parameters:

rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [Required units : [discharge]]
threshold_factor (number) – Factor by which the mean flow is multiplied to set the low flow threshold, default is 0.2. Default: 0.2.
freq (offset alias (string)) – Resampling frequency, default is ‘YS-OCT’ for water year starting in October and ending in September. Default: ‘YS-OCT’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray, [days] – Low flow frequency. With additional attributes: description: {freq} frequency of flows smaller than a fraction ({threshold_factor}) of the mean flow.

Return type:

xarray.DataArray

References

Olden and Poff [2003]

xclim.indicators.land._streamflow.rb_flashiness_index(rivo='rivo', *, freq='YS', ds=None)

Richards-Baker Flashiness Index

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 function rb_flashiness_index().

Parameters:

rivo (str or DataArray) – Rate of river discharge. Default: ‘rivo’. [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:

xarray.DataArray, [dimensionless] – Richards-Baker Flashiness Index. With additional attributes: description: {freq} of Richards-Baker Index, an index measuring the flashiness of flow.

Return type:

xarray.DataArray

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.rivo_max_doy(discharge='discharge', *, freq='YS', ds=None, **indexer)

Day of year of the maximum streamflow

This indicator will check for missing values according to the method “from_context”. Based on function statistics(). With injected parameters: statistic=doymax, out_units=None.

Parameters:

discharge (str or DataArray) – The amount of water, in all phases, flowing in the river channel and flood plain. Default: ‘discharge’. [Required units : [length]**3/[time]]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, time dimension is reduced completely. 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. See xclim.core.calendar.select_time().

Returns:

xarray.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}.

Return type:

xarray.DataArray

xclim.indicators.land._streamflow.rivo_min_doy(discharge='discharge', *, freq='YS', ds=None, **indexer)

Day of year of the minimum streamflow

This indicator will check for missing values according to the method “from_context”. Based on function statistics(). With injected parameters: statistic=doymin, out_units=None.

Parameters:

discharge (str or DataArray) – The amount of water, in all phases, flowing in the river channel and flood plain. Default: ‘discharge’. [Required units : [length]**3/[time]]
freq (offset alias (string)) – Resampling frequency defining the periods as defined in Resampling. If None, time dimension is reduced completely. 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. See xclim.core.calendar.select_time().

Returns:

xarray.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}.

Return type:

xarray.DataArray

xclim.indicators.land._streamflow.runoff_ratio(rivo='rivo', pr='pr', *, area, freq='YS', ds=None)

Runoff ratio

Ratio of runoff volume measured at the stream to the total precipitation volume over the watershed.

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

Parameters:

rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [Required units : [discharge]]
pr (str or DataArray) – Mean daily precipitation. Default: ‘pr’. [Required units : [precipitation]]
area (quantity (string or DataArray, with units)) – Watershed area. Required. [Required units : [area]]
freq (offset alias (string)) – Resampling frequency. Default: ‘YS’.
ds (Dataset, optional) – A dataset with the variables given by name. Default: None.

Returns:

xarray.DataArray – Runoff ratio. With additional attributes: description: Ratio of runoff volume measured at the stream to the total precipitation volume over the watershed.Temporal analysis: Yearly values computed from seasonal daily data and yearly data, depending on chosen frequency.

Return type:

xarray.DataArray

Notes

Runoff ratio values are comparable to runoff coefficients.
Values near 0 mean most precipitation infiltrates watershed soil or is lost to evapotranspiration.
Values near 1 mean most precipitation leaves the watershed as runoff. Possible causes are impervious surfaces from urban sprawl, thin soils, steep slopes, etc.
Annual runoff ratios are typically ≤ 1.
Annual runoff ratios are typically higher than summer runoff ratios due to higher levels of evapotranspiration in summer months.
For snow-driven watersheds, spring runoff ratios are typically higher than annual runoff ratios, as snowmelt generates concentrated runoff events.
Temporal analysis: Yearly values computed from seasonal daily data and yearly data, depending on chosen frequency. (e.g., ‘YS’ for yearly starting Jan, or ‘QS-DEC’ for seasons, ‘30YS’ to compute the value over slices of 30 years from the start of the time series).

References

:cite:cts:’knoben_2024’

xclim.indicators.land._streamflow.sen_slope(rivo='rivo', *, freq='YS', ds=None)

Sen Slope : Temporal robustness analysis of streamflow.

Computes Theil-Sen slope estimators and performs the Mann-Kendall test for trend evaluation.

Based on function sen_slope().

Parameters:

rivo (str or DataArray) – Daily streamflow data. Default: ‘rivo’. [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:

sen_slope (xarray.DataArray, [dimensionless]) – Sen Slope from observed data. With additional attributes: description: Compute annual and seasonal Theil-Sen slope estimators and perform the Mann-Kendall test for trend evaluation.
p_value (xarray.DataArray, [dimensionless]) – p_value from observed data. With additional attributes: description: Statistical analysis value.

Return type:

tuple[xarray.DataArray, xarray.DataArray]

Notes

If p-value <= 0.05, the trend is statistically significant at the 5% level.
The ratio of observed Sen_slope over simulated Sen_slope is considered acceptable within the range 0.5-2 and is optimal when equal to 1 (Sauquet et al., 2025).

References

Sauquet, Evin, Siauve, Aissat, Arnaud, Bérel, Bonneau, Branger, Caballero, Colléoni, Ducharne, Gailhard, Habets, Hendrickx, Héraut, Hingray, Huang, Jaouen, Jeantet, Lanini, Le Lay, Magand, Mimeau, Monteil, Munier, Perrin, Robelin, Rousset, Soubeyroux, Strohmenger, Thirel, Tocquer, Tramblay, Vergnes, and Vidal [2025]

xclim.indicators.land._streamflow.standardized_groundwater_index(gwl='gwl', *, freq='MS', window=1, dist='genextreme', method='ML', fitkwargs=None, cal_start=None, cal_end=None, params=None, ds=None, **indexer)

Standardized Groundwater Index (SGI)

Groundwater over a moving window, normalized such that SGI averages to 0 for the calibration data. The window unit X is the minimal time period defined by the resampling frequency.

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

Parameters:

gwl (str or DataArray) – Groundwater head level. Default: ‘gwl’. [Required units : [length]]
freq (offset alias (string)) – Resampling frequency. A monthly or daily frequency is expected. Option None assumes that the desired resampling has already been applied input dataset and will skip the resampling step. Default: ‘MS’.
window (number) – Averaging window length relative to the resampling frequency. For example, if freq=”MS”, i.e. a monthly resampling, the window is an integer number of months. Default: 1.
dist ({‘genextreme’, ‘lognorm’, ‘gamma’}) – Name of the univariate distribution, or a callable rv_continuous (see scipy.stats). Default: ‘genextreme’.
method ({‘APP’, ‘ML’, ‘PWM’}) – Name of the fitting method, such as ML (maximum likelihood), APP (approximate). The approximate method uses a deterministic function that does not involve any optimization. PWM should be used with a lmoments3 distribution. Default: ‘ML’.
fitkwargs (dict) – Kwargs passed to xclim.compute.stats.fit used to impose values of certain parameters (floc, fscale). Default: None.
cal_start (date (string, YYYY-MM-DD)) – Start date of the calibration period. A DateStr is expected, that is a str in format “YYYY-MM-DD”. Default option None means that the calibration period begins at the start of the input dataset. Default: None.
cal_end (date (string, YYYY-MM-DD)) – End date of the calibration period. A DateStr is expected, that is a str in format “YYYY-MM-DD”. Default option None means that the calibration period finishes at the end of the input dataset. Default: None.
params (quantity (string or DataArray, with units)) – Fit parameters. The params can be computed using xclim.compute.stats.standardized_index_fit_params in advance. The output can be given here as input, and it overrides other options. Default: None. [Required units : []]
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.compute.generic.select_time().

Returns:

xarray.DataArray, [unitless] – sgi, Standardized Groundwater Index (SGI). With additional attributes: description: Groundwater over a moving {window}-X window, normalized such that SGI averages to 0 for calibration data. The window unit `X` is the minimal time period defined by resampling frequency {freq}.

Return type:

xarray.DataArray

Notes

N-month SGI / N-day SGI is determined by choosing the window = N and the appropriate frequency freq.
Supported statistical distributions are: [“gamma”, “genextreme”, “lognorm”].
If params is provided, it overrides the cal_start, cal_end, freq, window, dist, method options.
“APP” method only supports two-parameter distributions. Parameter loc needs to be fixed to use method “APP”.

References

Bloomfield and Marchant [2013]

xclim.indicators.land._streamflow.standardized_streamflow_index(rivo='rivo', *, freq='MS', window=1, dist='genextreme', method='ML', fitkwargs=None, cal_start=None, cal_end=None, params=None, ds=None, **indexer)

Standardized Streamflow Index (SSI)

Streamflow over a moving window, normalized such that SSI averages to 0 for the calibration data. The window unit X is the minimal time period defined by the resampling frequency.

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

Parameters:

rivo (str or DataArray) – Rate of river discharge. Default: ‘rivo’. [Required units : [discharge]]
freq (offset alias (string)) – Resampling frequency. A monthly or daily frequency is expected. Option None assumes that the desired resampling has already been applied input dataset and will skip the resampling step. Default: ‘MS’.
window (number) – Averaging window length relative to the resampling frequency. For example, if freq=”MS”, i.e. a monthly resampling, the window is an integer number of months. Default: 1.
dist ({‘genextreme’, ‘fisk’}) – Name of the univariate distribution, or a callable rv_continuous (see scipy.stats). Default: ‘genextreme’.
method ({‘APP’, ‘ML’, ‘PWM’}) – Name of the fitting method, such as ML (maximum likelihood), APP (approximate). The approximate method uses a deterministic function that does not involve any optimization. PWM should be used with a lmoments3 distribution. Default: ‘ML’.
fitkwargs (dict) – Kwargs passed to xclim.compute.stats.fit used to impose values of certain parameters (floc, fscale). Default: None.
cal_start (date (string, YYYY-MM-DD)) – Start date of the calibration period. A DateStr is expected, that is a str in format “YYYY-MM-DD”. Default option None means that the calibration period begins at the start of the input dataset. Default: None.
cal_end (date (string, YYYY-MM-DD)) – End date of the calibration period. A DateStr is expected, that is a str in format “YYYY-MM-DD”. Default option None means that the calibration period finishes at the end of the input dataset. Default: None.
params (quantity (string or DataArray, with units)) – Fit parameters. The params can be computed using xclim.compute.stats.standardized_index_fit_params in advance. The output can be given here as input, and it overrides other options. Default: None. [Required units : []]
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.compute.generic.select_time().

Returns:

xarray.DataArray, [unitless] – ssi, Standardized Streamflow Index (SSI). With additional attributes: description: Streamflow over a moving {window}-X window, normalized such that SSI averages to 0 for calibration data. The window unit `X` is the minimal time period defined by resampling frequency {freq}.

Return type:

xarray.DataArray

Notes

N-month SSI / N-day SSI is determined by choosing the window = N and the appropriate frequency freq.
Supported statistical distributions are: [“genextreme”, “fisk”], where “fisk” is scipy’s implementation of
a log-logistic distribution.
If params is provided, it overrides the cal_start, cal_end, freq, window, dist, and method options.
“APP” method only supports two-parameter distributions. Parameter loc needs to be fixed to use method “APP”.
The standardized index is bounded by ±8.21. 8.21 is the largest standardized index as constrained by the float64 precision in the inversion to the normal distribution.

References

Vicente-Serrano, López-Moreno, Beguer\'ıa, Lorenzo-Lacruz, Azorin-Molina, and Morán-Tejeda [2012]