def precip_accumulation(
pr: xarray.DataArray,
tas: xarray.DataArray = None,
phase: Optional[str] = None,
freq: str = "YS",
) -> xarray.DataArray:
r"""Accumulated total (liquid and/or solid) precipitation.
Resample the original daily mean precipitation flux and accumulate over each period.
If the daily mean temperature is provided, the phase keyword can be used to only sum precipitation of a certain phase.
When the mean temperature is over 0 degC, precipitatio is assumed to be liquid rain and snow otherwise.
Parameters
----------
pr : xarray.DataArray
Mean daily precipitation flux [Kg m-2 s-1] or [mm].
tas : xarray.DataArray, optional
Mean daily temperature [℃] or [K]
phase : str, optional,
Which phase to consider, "liquid" or "solid", if None (default), both are considered.
freq : str
Resampling frequency as defined in
http://pandas.pydata.org/pandas-docs/stable/timeseries.html#resampling. Defaults to "YS"
Returns
-------
xarray.DataArray
The total daily precipitation at the given time frequency for the given phase.
Notes
-----
Let :math:`PR_i` be the mean daily precipitation of day :math:`i`, then for a period :math:`j` starting at
day :math:`a` and finishing on day :math:`b`:
.. math::
PR_{ij} = \sum_{i=a}^{b} PR_i
If `phase` is "liquid", only times where the daily mean temperature :math:`T_i` is above or equal to 0 °C are considered, inversely for "solid".
Examples
--------
The following would compute for each grid cell of file `pr_day.nc` the total
precipitation at the seasonal frequency, ie DJF, MAM, JJA, SON, DJF, etc.:
>>> import xarray as xr
>>> pr_day = xr.open_dataset('pr_day.nc').pr
>>> prcp_tot_seasonal = precip_accumulation(pr_day, freq="QS-DEC")
"""
if phase in ["liquid", "solid"]:
frz = utils.convert_units_to("0 degC", tas)
if phase == "liquid":
pr = pr.where(tas >= frz, 0)
elif phase == "solid":
pr = pr.where(tas < frz, 0)
out = pr.resample(time=freq).sum(dim="time", keep_attrs=True)
return utils.pint_multiply(out, 1 * units.day, "mm")
def daily_pr_intensity(pr, thresh="1 mm/day", freq="YS"):
r"""Average daily precipitation intensity
Return the average precipitation over wet days.
Parameters
----------
pr : xarray.DataArray
Daily precipitation [mm/d or kg/m²/s]
thresh : str
precipitation value over which a day is considered wet. Default : '1 mm/day'
freq : str
Resampling frequency defining the periods defined in
http://pandas.pydata.org/pandas-docs/stable/timeseries.html#resampling; Defaults to "YS".
Returns
-------
xarray.DataArray
The average precipitation over wet days for each period
Notes
-----
Let :math:`\mathbf{p} = p_0, p_1, \ldots, p_n` be the daily precipitation and :math:`thresh` be the precipitation
threshold defining wet days. Then the daily precipitation intensity is defined as
.. math::
\frac{\sum_{i=0}^n p_i [p_i \leq thresh]}{\sum_{i=0}^n [p_i \leq thresh]}
where :math:`[P]` is 1 if :math:`P` is true, and 0 if false.
Examples
--------
The following would compute for each grid cell of file `pr.day.nc` the average
precipitation fallen over days with precipitation >= 5 mm at seasonal
frequency, ie DJF, MAM, JJA, SON, DJF, etc.:
>>> import xarray as xr
>>> import xclim.indices
>>> pr = xr.open_dataset("pr_day.nc").pr
>>> daily_int = xclim.indices.daily_pr_intensity(pr, thresh='5 mm/day', freq="QS-DEC")
"""
t = utils.convert_units_to(thresh, pr, "hydro")
# put pr=0 for non wet-days
pr_wd = xarray.where(pr >= t, pr, 0)
pr_wd.attrs["units"] = pr.units
# sum over wanted period
s = pr_wd.resample(time=freq).sum(dim="time", keep_attrs=True)
sd = utils.pint_multiply(s, 1 * units.day, "mm")
# get number of wetdays over period
wd = wetdays(pr, thresh=thresh, freq=freq)
return sd / wd
def max_n_day_precipitation_amount(pr, window: int = 1, freq: str = "YS"):
r"""Highest precipitation amount cumulated over a n-day moving window.
Calculate the n-day rolling sum of the original daily total precipitation series
and determine the maximum value over each period.
Parameters
----------
pr : xarray.DataArray
Daily precipitation values [Kg m-2 s-1] or [mm]
window : int
Window size in days.
freq : str
Resampling frequency; Defaults to "YS" (yearly).
Returns
-------
xarray.DataArray
The highest cumulated n-day precipitation value at the given time frequency.
Examples
--------
The following would compute for each grid cell of file `pr.day.nc` the highest 5-day total precipitation
at an annual frequency:
>>> import xarray as xr
>>> pr = xr.open_dataset('pr.day.nc').pr
>>> window = 5
>>> output = max_n_day_precipitation_amount(pr, window=window, freq="YS")
"""
# rolling sum of the values
arr = pr.rolling(time=window).sum(allow_lazy=True, skipna=False)
out = arr.resample(time=freq).max(dim="time", keep_attrs=True)
out.attrs["units"] = pr.units
# Adjust values and units to make sure they are daily
return utils.pint_multiply(out, 1 * units.day, "mm")
def precip_accumulation(pr, freq='YS'):
r"""Accumulated total (liquid + solid) precipitation.
Resample the original daily mean precipitation flux and accumulate over each period.
Parameters
----------
pr : xarray.DataArray
Mean daily precipitation flux [Kg m-2 s-1] or [mm].
freq : str, optional
Resampling frequency as defined in
http://pandas.pydata.org/pandas-docs/stable/timeseries.html#resampling.
Returns
-------
xarray.DataArray
The total daily precipitation at the given time frequency.
Notes
-----
Let :math:`PR_i` be the mean daily precipitation of day :math:`i`, then for a period :math:`j` starting at
day :math:`a` and finishing on day :math:`b`:
.. math::
PR_{ij} = \sum_{i=a}^{b} PR_i
Examples
--------
The following would compute for each grid cell of file `pr_day.nc` the total
precipitation at the seasonal frequency, ie DJF, MAM, JJA, SON, DJF, etc.:
>>> pr_day = xr.open_dataset('pr_day.nc').pr
>>> prcp_tot_seasonal = precip_accumulation(pr_day, freq="QS-DEC")
"""
out = pr.resample(time=freq).sum(dim='time', keep_attrs=True)
return utils.pint_multiply(out, 1 * units.day, 'mm')
def max_n_day_precipitation_amount(pr, window=1, freq='YS'):
r"""Highest precipitation amount cumulated over a n-day moving window.
Calculate the n-day rolling sum of the original daily total precipitation series
and determine the maximum value over each period.
Parameters
----------
da : xarray.DataArray
Daily precipitation values [Kg m-2 s-1] or [mm]
window : int
Window size in days.
freq : str, optional
Resampling frequency : default 'YS' (yearly)
Returns
-------
xarray.DataArray
The highest cumulated n-day precipitation value at the given time frequency.
Examples
--------
The following would compute for each grid cell of file `pr.day.nc` the highest 5-day total precipitation
at an annual frequency:
>>> da = xr.open_dataset('pr.day.nc').pr
>>> window = 5
>>> output = max_n_day_precipitation_amount(da, window, freq="YS")
"""
# rolling sum of the values
arr = pr.rolling(time=window, center=False).sum()
out = arr.resample(time=freq).max(dim='time', keep_attrs=True)
out.attrs['units'] = pr.units
# Adjust values and units to make sure they are daily
return utils.pint_multiply(out, 1 * units.day, 'mm')
def test_pint_multiply(self, pr_series):
a = pr_series([1, 2, 3])
out = utils.pint_multiply(a, 1 * units.days)
assert out[0] == 1 * 60 * 60 * 24
assert out.units == "kg m-2"
