A drought is assumed to be defined as an instance when the vector x exceeds
(if exceed = TRUE) or falls below (if exceed = FALSE) the specified
thresholds in thresholds.
thresholds can be a single value, or a vector of values. In the latter case,
each threshold is assumed to be a different level or intensity of the drought.
If exceed = TRUE then a higher threshold corresponds to a higher intensity,
and if exceed = FALSE then a lower threshold corresponds to a higher intensity.
For example, if thresholds = c(1, 1.5, 2), then a level 1 drought occurs
whenever x exceeds 1 but is lower than 1.5, a level 2 drought occurs
whenever x exceeds 1.5 but is lower than 2, and a level 3 drought occurs
whenever x exceeds 2.
By default, thresholds = c(1.28, 1.64, 1.96), which corresponds to the
90th, 95th, and 97.5th percentiles of the standard normal distribution. These
thresholds are often used alongside standardised indices to define hydrometeorological
droughts; see references.
cluster represents the number
of time steps between different drought events that should be attributed to the same drought.
For example, suppose \(x_{i} \geq t, x_{i + 1} < t, x_{i + 2} \geq t\),
where \(x_{i}\) represents the \(i\)-th value in x, and \(t\) is the
lowest threshold in thresholds. In this case, one drought event will finish
at time point \(i\) and a new drought event will begin at time point \(i + 2\);
no drought will occur at time point \(i + 1\) because the value \(x_{i + 1}\) is
below the threshold defining a drought. Since both \(x_{i}\) and \(x_{i + 2}\)
are classed as drought events, it may be desirable to ignore the fluctuation, and
assume that the drought persists through \(x_{i + 1}\) despite its value. This can
be achieved by setting cluster = 1. If there were two time points separating
different drought events, these can be clustered together by setting cluster = 2,
and so on. The default is that no clustering should be implemented, i.e. cluster = 0.
Alternatively, we may wish to assume that the drought persists until x falls below
a value that is not necessarily equal to the threshold defining a drought. For example,
hydrometeorological droughts based on standardised indices, such as the Standardised
Precipitation Index (SPI), are often defined to persist until the standardised index changes
sign, i.e. falls below zero. This can be achieved by setting lag = 0. More generally,
lag can be any numerical value. If exceed = TRUE, a warning is issued if
lag is above the lowest threshold, and if exceed = FALSE, a warning is
issued if lag is below the highest threshold. If lag is NULL
(the default), then no lagging is performed.
get_drought() currently does not use the time series information in
the xts input, thereby assuming that the time series is complete, without missing
time periods. If x is a vector, rather than an xts object, then this
is also implicitly assumed.
The output is a dataframe containing the vector x, a logical vector
specifying whether each value of x corresponds to a drought event,
and the magnitude of the drought, defined as the sum of the values of x during
the drought; see references. The magnitude of the drought is only shown
on the last day of the drought. This makes it easier to compute statistics about
the drought magnitude, such as the average drought magnitude.
If thresholds is a vector, the intensity or level of the drought is also returned.