Derives time series of the cumulative water deficit (CWD), given time series of the daily soil water balance (infiltration minus evapotranspiration). CWD "events" are identified as periods of consecutive days where the CWD is positive (a water deficit). An event ends and CWD resets to zero when: a) on a specified day-of-year (doy_reset), or b) when CWD falls below 0mm (always active), or c) when CWD falls more than thresh_reset_absolute below the event peak, or d) when CWD falls below thresh_reset_relative times the event peak.

cwd(
  df,
  varname_wbal,
  varname_date,
  thresh_drop = 0,
  doy_reset = NA,
  thresh_reset_absolute = NA,
  thresh_reset_relative = NA_real_,
  do_surplus = FALSE,
  thresh_terminate_absolute = NULL,
  thresh_terminate_relative = NULL
)

Arguments

df

a data frame that contains the variable named according to argument varname_wbal

varname_wbal

name of the variable representing the daily soil water balance (infiltration minus evapotranspiration)

varname_date

name of the variable representing information about the date (format irrelevant)

thresh_drop

Level, relative to the CWD maximum of the same event, after which all data during the remainder of the event is set to missing values. This is to avoid interpreting data after rain events but before full compensation of CWD. Defaults to 0.

doy_reset

Day-of-year (integer) when CWD is to be reset to zero each year. Defaults to NA (not considered).

thresh_reset_absolute

Amount by which CWD must fall below the maximum CWD attained during the event to end the event and reset CWD to zero. Units are the same as varname_wbal. Defaults to NA (not considered).

thresh_reset_relative

Fraction of the event's peak by which CWD must fall to end the event and reset CWD to zero. Must be between 0 and 1. For example, 0.1 terminates an event once CWD falls by 10 percent, i.e. below 90 percent of its peak. Defaults to NA (not considered). Cannot be combined with thresh_reset_absolute.

do_surplus

A logical specifying whether the cumulative surplus should be calculated. Defaults to FALSE.

thresh_terminate_absolute

Deprecated argument. Use thresh_reset_absolute instead; supplying this argument raises an error.

thresh_terminate_relative

Deprecated argument. Use thresh_reset_relative instead; supplying this argument raises an error.

Details

A list of two data frames (tibbles). inst contains information about CWD "events". Each row corresponds to one event. An event is defined as a period of consecutive days where the CWD is positive (a water deficit) and has the following columns:

idx_start: row number of df of which the date corresponds to the start of the event len: length of the event, quantified as number of rows in df corresponding to the event iinst: event number date_start: starting date of the event, formatted as varname_date in df. date_end: end date of the event, formatted as varname_date in df. max_deficit: maximum CWD recorded during this event. Units correspond to units of varname_wbal in df.