# IDF

Intensity-duration-frequency (IDF) curves are a widely used analysis-tool in hydrology to assess the characteristics of extreme precipitation. The package ‘IDF’ functions to estimate IDF relations for given precipitation time series on the basis of a duration-dependent generalized extreme value (GEV) distribution. The central function is , which uses the method of maximum-likelihood estimation for the d-GEV parameters, whereby it is possible to include generalized linear modeling for each parameter. For more detailed information on the methods and the application of the package for estimating IDF curves with spatial covariates, see Ulrich et. al (2020, https://doi.org/10.3390/w12113119).

## Installation

You can install the released version of IDF from CRAN with:

install.packages("IDF")

or from gitlab using:

devtools::install_git("https://gitlab.met.fu-berlin.de/Rpackages/idf_package")

## Example

Here are a few examples to illustrate the order in which the functions are intended to be used.

• Step 0: sample 20 years of example hourly ‘precipitation’ data
set.seed(999)
dates <- seq(as.POSIXct("2000-01-01 00:00:00"),as.POSIXct("2019-12-31 23:00:00"),by = 'hour')
sample.precip <- rgamma(n = length(dates), shape = 0.05, rate = 0.4)
precip.df <- data.frame(date=dates,RR=sample.precip)
• Step 1: get annual maxima
library(IDF)

durations <- 2^(0:6) # accumulation durations [h]
ann.max <- IDF.agg(list(precip.df),ds=durations,na.accept = 0.1)
# plotting the annual maxima in log-log representation
plot(ann.max$ds,ann.max$xdat,log='xy',xlab = 'Duration [h]',ylab='Intensity [mm/h]')

• Step 2: fit d-GEV to annual maxima
fit <- gev.d.fit(xdat = ann.max$xdat,ds = ann.max$ds,sigma0link = make.link('log'))
#> $conv #> [1] 0 #> #>$nllh
#> [1] 59.34496
#>
#> $mle #> [1] 6.478887e+00 3.817184e-01 -1.833254e-02 2.843666e-09 7.922310e-01 #> #>$se
#> [1] 4.018974e-01 6.677404e-02 4.931317e-02 2.000063e-06 1.141522e-02
# checking the fit
gev.d.diag(fit,pch=1,)

# parameter estimates
params <- gev.d.params(fit)
print(params)
#>        mut sigma0          xi        theta      eta     eta2 tau
#> 1 6.478887 1.4648 -0.01833254 2.843666e-09 0.792231 0.792231   0

# plotting the probability density for a single duration
q.min <- floor(min(ann.max$xdat[ann.max$ds%in%1:2]))
q.max <- ceiling(max(ann.max$xdat[ann.max$ds%in%1:2]))
q <- seq(q.min,q.max,0.2)
plot(range(q),c(0,0.55),type = 'n',xlab = 'Intensity [mm/h]',ylab = 'Density')
for(d in 1:2){ # d=1h and d=2h
# sampled data:
hist(ann.max$xdat[ann.max$ds==d],main = paste('d=',d),q.min:q.max
# etimated prob. density:
lines(q,dgev.d(q,params$mut,params$sigma0,params$xi,params$theta,params$eta,params$tau,d = d),col=d)
}
legend('topright',col=1:2,lwd=1,legend = paste('d=',1:2,'h'),title = 'Duration')

• Step 3: adding the IDF-curves to the data
plot(ann.max$ds,ann.max$xdat,log='xy',xlab = 'Duration [h]',ylab='Intensity [mm/h]')
IDF.plot(durations,params,add=TRUE)

## IDF Features

This Example depicts the different features that can be used to model the IDF curves (submitted for publication: Fauer et al. An Extended Model in Estimating Consistent Quantiles for Intensity-Duration-Frequency Curves, 2020). Here we assume, that the block maxima of each duration can be modeled with the GEV distribution ($\xi\neq0 "\xi\neq0"$):
$G(z;\mu,\sigma,\xi)=\exp \left\lbrace -\left[ 1+\xi \left( \frac{z-\mu}{\sigma} \right) \right]^{-1/\xi} \right\rbrace, "G(z;\mu,\sigma,\xi)=\exp \left\lbrace -\left[ 1+\xi \left( \frac{z-\mu}{\sigma} \right) \right]^{-1/\xi} \right\rbrace,"$

where the GEV parameters depend on duration according to:

The function gev.d.fit provides the options:

• theta_zero = TRUE $\theta = 0 "\theta = 0"$
• eta2_zero = TRUE (default) $\eta_2 = \eta "\eta_2 = \eta"$
• tau_zero = TRUE (default) $\tau = 0 "\tau = 0"$

resulting in the following features for IDF-curves:

• simple scaling: using only parameters $\tilde{\mu}, \sigma_0, \xi, \eta "\tilde{\mu}, \sigma_0, \xi, \eta"$
• curvature for small durations: allowing $\theta \neq 0 "\theta \neq 0"$ (default)
• multi-scaling: allowing $\eta_2 \neq \eta "\eta_2 \neq \eta"$
• flattening for long durations: allowing $\tau \neq 0 "\tau \neq 0"$.

Example:

### sampling example data
set.seed(42)
# durations
ds <- 1/60*2^(seq(0,13,1))
# random data for each duration
xdat <- sapply(ds,rgev.d,n = 20,mut = 2,sigma0 =3,xi = 0.2,theta = 0.1,eta = 0.6,tau = 0.1,eta2 = 0.8)
# transform to data.frame
example <- data.frame(xdat=as.numeric(xdat),ds=rep(ds,each=dim(xdat)[1]))

### different fit options
fit.simple <- gev.d.fit(xdat=example$xdat,ds = example$ds,theta_zero = TRUE,show=FALSE)
fit.theta <- gev.d.fit(xdat=example$xdat,ds = example$ds,show=FALSE)
fit.eta2 <- gev.d.fit(xdat=example$xdat,ds = example$ds,eta2_zero = FALSE,show=FALSE)
fit.tau <- gev.d.fit(xdat=example$xdat,ds = example$ds,eta2_zero = FALSE,tau_zero = FALSE,show=FALSE)

### compare resulting idf-curves
# group fits
all.fits <- list(fit.simple,fit.theta,fit.eta2,fit.tau)
fit.cols <- c('red','purple','blue','darkgreen')
fit.labels <- c('simple-scaling','theta!=0','eta2!=eta','tau!=0')
# plotting probabilities
idf.probs <- c(0.5,0.75,0.99)
# create 4 plots: one for each additional parameter
par(mfrow=c(2,2),mar=c(0.2,0.2,0.2,0.2),oma=c(3.5,4.5,0,0),mgp=c(2.5,0.6,0))
for(i.fit in 1:length(all.fits)){
plot(example$ds,example$xdat,log='xy',type='n',axes=FALSE)
box()
boxplot(example$xdat~example$ds,at=ds,add = TRUE,
boxwex=0.2,cex=0.4,axes=FALSE)
if(i.fit %in% c(1,3)){
axis(2,las=2)
mtext('Intensity [mm/h]',2,3)
}
if(i.fit %in% 3:4){
axis(1,at=c(0.1,1,24,120),labels = c(0.1,1,24,120))
mtext('Duration [h]',1,2)
}
for(i.p in 1:length(idf.probs)){
# plotting IDF curves for each model (different colors) and probability (different lty)
IDF.plot(1/60*2^(seq(0,13,0.5)),gev.d.params(all.fits[[i.fit]]),probs = idf.probs[i.p]
,add = TRUE,legend = FALSE,lty = i.p,cols = fit.cols[i.fit])
}
mtext(fit.labels[i.fit],3,-1.25)
}
legend('topright',lty=rev(1:3),legend = rev(idf.probs),title = 'p-quantile')