tyears {lfstat}

Calculate Low-Flow Quantiles for given Return Periods

Description

Fits an extreme value distribution using L-moments to the minima 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

tyears(lfobj, event = 1/probs, probs = 0.01,
       dist = "wei", check = TRUE, zeta = zetawei, zetawei = NULL,
       plot = TRUE, col = 1, log = TRUE, legend = TRUE,
       rp.axis = "top", 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",
       hyearstart = hyear_start(lfobj),
       n = NULL)

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.

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.

zetawei

same as zeta

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

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.

n

Argument 'n' is deprecated and ignored. To apply a moving average, do it prior to calling 'tyears'. See section Examples.

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)

Daniel Koffler and 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")
ng <- subset(ngaruroro, hyear %in% 1964:2000)

# vector of return periods
rp <- c(1.5, 5, 10, 100)

# Fitting some distributions for the low flows (annual minima)
# and estimating the quantile for arbitrary return periods
y <- tyears(ng, dist = c("gum", "wei", "ln3", "pe3"), event = rp,
            plot = FALSE)

# print()ing the object shows just the return periods
y

# but y is actually a list
str(y)

# there is a summary method, returning L-moments and estimated parameters
summary(y)

plot(y)


# fitting just one distribution, with annotated quantiles
z <- tyears(ng, dist = c("gevR"), event = rp)
rpline(y, return.period = rp, suffix = c("a", "m\u00B3"))


# applying a moving average before fitting
ng2 <- ng
ng2$flow <- ma(ng2$flow, n = 4)
tyears(ng2, dist = c("gum", "wei", "ln3", "pe3"), event = rp,
       plot = FALSE)