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(snd='snd', *, snr=None, const='312 kg m-3', out_units=None, ds=None)

Surface snow amount (realm: atmos)

Based on indice snd_to_snw().

Parameters:

• snd (str or DataArray) – Snow Depth. Default : ds.snd. [Required units : [length]]

• snr (quantity (string or DataArray, with units)) – Snow Density. Default : None. [Required units : [mass]/[volume]]

• const (quantity (string or DataArray, with units)) – Constant snow density. const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]

• out_units (str) – Desired units of the snow amount output. If None, output units simply follow from snd * snr. Default : None.

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

Returns:

snw (DataArray) – Approximation of daily snow amount from snow depth and density (surface_snow_amount) [kg m-2], with additional attributes: description: The approximation of daily snow amount from snow depth and density.

Return type:

xarray.DataArray

Notes

The estimated mean snow density value of 312 kg m-3 is taken from Sturm et al. [2010].

References

Sturm, Taras, Liston, Derksen, Jonas, and Lea [2010]

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 : [mass]/[area]]

• 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 : [mass]/[area]]

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

• 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 : [mass]/[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-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 : [mass]/[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-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 : [mass]/[area]]

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

• 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 : [mass]/[area]]

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

• 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 : [mass]/[area]]

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

• 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 : [mass]/[area]]

• 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 : [mass]/[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-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(snw='snw', *, snr=None, const='312 kg m-3', out_units=None, ds=None)

Surface snow depth (realm: atmos)

Based on indice snw_to_snd().

Parameters:

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

• snr (quantity (string or DataArray, with units)) – Snow density. Default : None. [Required units : [mass]/[volume]]

• const (quantity (string or DataArray, with units)) – Constant snow density. const is only used if snr is None. Default : 312 kg m-3. [Required units : [mass]/[volume]]

• out_units (str) – Desired units of the snow depth output. If None, output units simply follow from snw / snr. Default : None.

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

Returns:

snd (DataArray) – Approximation of daily snow depth from snow amount and density (surface_snow_thickness) [m], with additional attributes: description: The approximation of daily snow depth from snow amount and density.

Return type:

xarray.DataArray

Notes

The estimated mean snow density value of 312 kg m-3 is taken from Sturm et al. [2010].

References

Sturm, Taras, Liston, Derksen, Jonas, and Lea [2010]

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

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

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

Returns:

base_flow_index (DataArray) – Base flow index, with additional attributes: description: Minimum of the 7-day moving average flow divided by the mean flow.

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

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

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

Returns:

rbi (DataArray) – Richards-Baker Flashiness Index, with additional attributes: description: {freq} of Richards-Baker Index, an index measuring the flashiness of flow.

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.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 ({‘genextreme’, ‘gamma’, ‘lognorm’}) – Name of the univariate distribution, or a callable rv_continuous (see scipy.stats). Default : genextreme.

• method ({‘APP’, ‘PWM’, ‘ML’}) – 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 ({‘APP’, ‘PWM’, ‘ML’}) – 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]