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 (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(). Keywords : 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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

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

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_op='>=', prsn_op='>=', date_start='12-25', date_end=None, freq='YS-JUL', ds=None)

Perfect Christmas snow days (realm: land)

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 indice holiday_snow_and_snowfall_days(). Keywords : snow.

Parameters:

  • snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

  • prsn (str or DataArray, optional) – Snowfall flux. [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_op ({‘gt’, ‘ge’, ‘>=’, ‘>’}) – Comparison operation for snow depth. Default: “>=”. Default : >=.

  • prsn_op ({‘gt’, ‘ge’, ‘>=’, ‘>’}) – 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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

holiday_snow_and_snowfall_days (DataArray) – Number of holiday days with snow and snowfall [days], 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', op='>=', date_start='12-25', date_end=None, freq='YS', ds=None)

Christmas snow days (realm: land)

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 indice holiday_snow_days(). Keywords : snow.

Parameters:

  • snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

  • snd_thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default: 20 mm. Default : 20 mm. [Required units : [length]]

  • op ({‘gt’, ‘ge’, ‘>=’, ‘>’}) – 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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

holiday_snow_days (DataArray) – Number of holiday days with snow [days], 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', *, thresh='2 cm', freq='YS-JUL', op='>=', ds=None, **indexer)

Days with snow (depth) (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 snd_days_above(). Keywords : snow.

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. The default value is chosen for the Northern Hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • op ({‘gt’, ‘ge’, ‘>=’, ‘>’}) – Comparison operation. Default: “>=”. Default : >=.

  • 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(). Required.

Returns:

snd_days_above (DataArray) – Number of days with snow [days], 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_doy(snd='snd', *, freq='YS-JUL', ds=None, **indexer)

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

Parameters:

  • snd (str or DataArray) – Surface snow depth. Default : ds.snd. [Required units : [length]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

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.

Return type:

xarray.DataArray

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

Snow cover end date (depth). (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 snd_season_end(). Keywords : snow.

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 the threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. Default: “YS-JUL”. The default value is chosen for the northern hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snd_season_end (DataArray) – End date of continuous snow depth cover (day_of_year), with additional attributes: description: Day of year when snow depth is below {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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

Snow cover duration (depth). (realm: land)

The season starts when snow depth is above a threshold for at least N consecutive days and 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 indice snd_season_length(). Keywords : snow.

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 and below threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. The default value is chosen for the northern hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

snd_season_length (DataArray) – Snow cover duration [days], 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

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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

Snow cover start date (depth). (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 snd_season_start(). Keywords : snow.

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 the threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. The default value is chosen for the Northern Hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snd_season_start (DataArray) – Start date of continuous snow depth cover (day_of_year), with additional attributes: description: Day of year when snow depth is above or equal to {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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

Winter storm days (realm: land)

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 indice snd_storm_days(). Keywords : snow.

Parameters:

  • snd (str or DataArray) – Surface snow depth. Default : ds.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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

{freq}_snd_storm_days (DataArray) – Days with snowfall depth at or above a given threshold [days], 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.snd_to_snw(*args, **kwargs)[source]
xclim.indicators.land._snow.snow_depth(snd='snd', *, freq='YS', ds=None, **indexer)

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

Parameters:

  • snd (str or DataArray) – Mean daily snow depth. Default : ds.snd. [Required units : [length]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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(). Required.

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.

Return type:

xarray.DataArray

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

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

Parameters:

  • snw (str or DataArray) – Snow amount (mass per area). Default : ds.snw. [Required units : [snowamount]]

  • window (number) – Number of days during which the melt is accumulated. Default : 3.

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-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.

Return type:

xarray.DataArray

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

Days with snow (amount) (realm: land)

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 indice snw_days_above(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 4 kg m-2. [Required units : [snowamount]]

  • freq (offset alias (string)) – Resampling frequency. The default value is chosen for the Northern hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • op ({‘gt’, ‘ge’, ‘>=’, ‘>’}) – Comparison operation. Default: “>=”. Default : >=.

  • 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(). Required.

Returns:

snw_days_above (DataArray) – Number of days with snow [days], 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 (realm: land)

The maximum snow amount equivalent on the surface.

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

Parameters:

  • snw (str or DataArray) – Snow amount (mass per area). Default : ds.snw. [Required units : [snowamount]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

{freq}_snw_max (DataArray) – Maximum snow amount equivalent (surface_snow_amount) [kg m-2], 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, **indexer)

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

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 indice snw_max_doy(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

{freq}_snw_max_doy (DataArray) – Day of year of maximum daily snow amount equivalent (day_of_year), 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)

Snow cover end date (amount). (realm: land)

The first date on which snow amount 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 snw_season_end(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 4 kg m-2. [Required units : [snowamount]]

  • window (number) – Minimum number of days with snow water below the threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. The default value is chosen for the Northern Hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snw_season_end (DataArray) – End date of continuous snow amount cover (day_of_year), with additional attributes: description: Day of year when snow amount is below {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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). (realm: land)

The season starts when the snow amount is above a threshold for at least N consecutive days and 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 indice snw_season_length(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 4 kg m-2. [Required units : [snowamount]]

  • window (number) – Minimum number of days with snow amount above and below threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. The default value is chosen for the northern hemisphere. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

snw_season_length (DataArray) – Snow cover duration [days], 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

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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

Snow cover start date (amount). (realm: land)

The first date on which snow amount 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 snw_season_start(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • thresh (quantity (string or DataArray, with units)) – Threshold snow amount. Default : 4 kg m-2. [Required units : [snowamount]]

  • window (number) – Minimum number of days with snow amount above or equal to the threshold. Default : 14.

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-JUL.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

snw_season_start (DataArray) – Start date of continuous snow amount cover (day_of_year), with additional attributes: description: Day of year when snow amount is above or equal to {thresh} for {window} consecutive days.

Return type:

xarray.DataArray

References

Chaumont, Mailhot, Diaconescu, Fournier, and Logan [2017]

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

Winter storm days (realm: land)

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 indice snw_storm_days(). Keywords : snow.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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.indices.generic.select_time(). Required.

Returns:

{freq}_snw_storm_days (DataArray) – Days with snowfall amount at or above a given threshold [days], 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._snow.snw_to_snd(*args, **kwargs)[source]

xclim.indicators.land._streamflow module

Streamflow indicator definitions.

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

Base flow index (realm: land)

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 indice base_flow_index(). Keywords : streamflow snow hydrology.

Parameters:
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.

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

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

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 indice base_flow_index_seasonal_ratio(). Keywords : streamflow snow hydrology streamflow, seasonal.

Parameters:

  • q (str or DataArray) – Rate of river discharge. Default : ds.q. [Required units : [discharge]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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 (DataArray) – 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 (DataArray) – 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.doy_qmax(da='da', *, freq='YS', ds=None, **indexer)

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 0x7ea6d5956b60>, out_units=None. Keywords : streamflow snow hydrology.

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 Resampling. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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. Required.

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

Return type:

xarray.DataArray

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

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 0x7ea6d5956c00>, out_units=None. Keywords : streamflow snow hydrology.

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 Resampling. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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. Required.

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

Return type:

xarray.DataArray

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

Flow index (realm: land)

Calculate the pth percentile of daily streamflow normalized by the median flow.

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

Parameters:

  • q (str or DataArray) – Daily streamflow data. Default : ds.q. [Required units : [discharge]]

  • p (number) – Percentile 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:

q_flow_index (DataArray) – Flow index [1], with additional attributes: description: {p}th percentile normalized by the median flow.

Return type:

xarray.DataArray

References

Clausen and Biggs [2000]

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

High flow frequency (realm: land)

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 indice high_flow_frequency(). Keywords : streamflow snow hydrology.

Parameters:

  • q (str or DataArray) – Daily streamflow data. Default : ds.q. [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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-OCT.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

q_high_flow_frequency (DataArray) – High flow frequency [days], 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', q='q', *, freq='YS-OCT', p=0.9, ds=None)

Time lag between maximum snowpack and river high flows (realm: land)

Number of days between the annual maximum snowpack, measured by the surface snow amount, and the mean date when river flow exceeds a percentile 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 indice lag_snowpack_flow_peaks(). Keywords : streamflow snow hydrology streamflow, snw.

Parameters:

  • snw (str or DataArray) – Surface snow amount. Default : ds.snw. [Required units : [snowamount]]

  • q (str or DataArray) – Streamflow. Default : ds.q. [Required units : [discharge]]

  • freq (offset alias (string)) – Resampling frequency. Defaults to the water year starting on the 1st of October. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-OCT.

  • p (number) – Percentile 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:

lag_snowpack_flow_peaks (DataArray) – Time lag between maximum snowpack and river high flows [days], 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 percentile 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(q='q', *, threshold_factor=0.2, freq='YS-OCT', ds=None)

Low flow frequency (realm: land)

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 indice low_flow_frequency(). Keywords : streamflow snow hydrology.

Parameters:

  • q (str or DataArray) – Daily streamflow data. Default : ds.q. [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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS-OCT.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

q_low_flow_frequency (DataArray) – Low flow frequency [days], 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(q='q', *, freq='YS', ds=None)

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(). Keywords : streamflow snow hydrology.

Parameters:
Returns:

rbi (DataArray) – 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.runoff_ratio(q='q', pr='pr', *, area, freq='YS', ds=None)

Runoff ratio (realm: land)

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 indice runoff_ratio(). Keywords : streamflow snow hydrology streamflow.

Parameters:

  • q (str or DataArray) – Streamflow in discharge units. Default : ds.q. [Required units : [discharge]]

  • pr (str or DataArray) – Mean daily precipitation in precipitation units. Default : ds.pr. [Required units : [precipitation]]

  • area (quantity (string or DataArray, with units)) – Watershed area in area units. Required. [Required units : [area]]

  • freq (offset alias (string)) – Resampling frequency. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. Default : YS.

  • ds (Dataset, optional) – A dataset with the variables given by name. Default : None.

Returns:

runoff_ratio (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(q='q', *, freq='YS', ds=None)

Sen Slope : Temporal robustness analysis of streamflow. (realm: land)

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

Based on indice sen_slope(). Keywords : streamflow hydrology streamflow.

Parameters:
Returns:

  • sen_slope (DataArray) – 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 (DataArray) – 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) (realm: land)

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 indice standardized_groundwater_index(). Keywords : groundwater.

Parameters:

  • gwl (str or DataArray) – Groundwater head level. Default : ds.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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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 ({‘lognorm’, ‘genextreme’, ‘gamma’}) – Name of the univariate distribution, or a callable rv_continuous (see scipy.stats). Default : genextreme.

  • method ({‘ML’, ‘PWM’, ‘APP’}) – 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.indices.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.indices.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.indices.generic.select_time(). Required.

Returns:

sgi (DataArray) – Standardized Groundwater Index (SGI) (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(q='q', *, 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) (realm: land)

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 indice standardized_streamflow_index(). Keywords : streamflow.

Parameters:

  • q (str or DataArray) – Rate of river discharge. Default : ds.q. [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. See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases for available options. 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 ({‘fisk’, ‘genextreme’}) – Name of the univariate distribution, or a callable rv_continuous (see scipy.stats). Default : genextreme.

  • method ({‘ML’, ‘PWM’, ‘APP’}) – 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.indices.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.indices.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.indices.generic.select_time(). Required.

Returns:

ssi (DataArray) – Standardized Streamflow Index (SSI) (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]