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"