tyearsS {lfstat}

Calculate Low-Flow Quantiles for given Return Periods

Description

Fits an extreme value distribution using L-moments to the dry spells of a time series of discharges and subsequently estimates quantiles (the so called T-years event) for given return periods. In the presence of zero flow observations a mixed distribution is fitted.

Usage

tyearsS(lfobj, event = 1/probs, probs = 0.01, pooling = NULL,
        dist = "wei", check = TRUE, zeta = NULL,
        plot = TRUE, col = 1, log = TRUE, legend = TRUE,
        rp.axis = "bottom", rp.lab = "Return period", freq.axis = TRUE,
        freq.lab = expression(paste("Frequency " *(italic(F)),
                                    " = Non-Exceedance Probability P ",
                                    (italic(X) <= italic(x)))),
        xlab = expression("Reduced variate,  " * -log(-log(italic(F)))),
        ylab = "Quantile",
        variable = c("volume", "duration"), aggr = "max",
        hyearstart = hyear_start(lfobj), ...)

Arguments

lfobj

An object of class 'lfobj' or an object which can be coerced to class 'xts'. Either with a single column or with a column named 'discharge'.

event

numeric vector specifying the return periods. E.g. event = 100 will yield the 100 years extreme low flow event.

probs

Alternate way to specify the return period of the event.

pooling

a pooling function, see pooling.

dist

A character vector of distributions to fit. Basically all distributions provided by Hosking's lmom-package and their reversed counterparts can be chosen.

check

logical, should check_distribution get called?

zeta

numeric vector of length one for manually setting a lower bound. Only a few distributions allow for a lower bound, namely 'gpa', 'ln3', 'wak' and 'wei'. The default value of NULL results in not bounding the distribution, therefore the parameter zeta is estimated.

plot

logical. If TRUE, sample observations as well as estimated quantile functions are plotted.

col

numeric or character vector of length one or as long as dist, specifying the colour used for plotting.

log

logical. If TRUE probabilities will be plotted on a double logarithmic scale.

legend

logical, should a legend be added to the plot?

rp.axis

vector of length one, specifying if and how an additional scale bar for the return periods is drawn. Possible choices are 'bottom', 'top' and 'none'. Alternatively, the position of the scale bar can be specified as an real number between 0 and 1, indicating the y-position of the legend.

rp.lab

character vector, text above the scale bar for return periods

freq.axis

logical, should an additional abscissa showing the probabilities be drawn on top of the plot?

freq.lab

character vector, text above the probability axis

xlab

character vector, a label for the x axis

ylab

character vector, a label for the y axis

variable

character vector of length one. Either 'v' to calculate volumes or 'd' for durations.

aggr

function like max or sum used for aggregating volumes or durations of a hydrological year.

hyearstart

vector of length one, providing the start of the hydrological year. This is evaluated by water_year. The default is, to retrieve the values stored in the attributes of the lfobj.

...

arguments passed on to find_droughts, e.g. threshold.

Details

This function is vectorised over dist and event.

According to paragraph 7.4.2 of the WNO manual, special care has to be taken in the presence of zero flow observations. A cdf called G(x) is fitted to the non-zero values of the original time series

If a distribution is fitted which allows for finite lower bound (zeta), and zeta is estimated being negative, estimation is repeated constraining zeta = 0. If this behavior is not desired, the parameter zeta has to be set explicitly.

Value

An object of class 'evfit', see evfit.

Author(s)

Gregor Laaha

References

Gustard, A. & Demuth, S. (2009) (Eds) Manual on Low-flow Estimation and Prediction. Operational Hydrology Report No. 50, WNO-No. 1029, 136p.

See Also

There are methods for printing summarizing objects of class 'evfit'.

evfit

Examples

data("ngaruroro")
rp <- c(1.3, 3, 5, 35)
sumD <- tyearsS(ngaruroro, event = rp, dist = "wei",
                variable = "d", aggr = sum)
sumD
summary(sumD)