Commit 1bd06d3b authored by Jana Ulrich's avatar Jana Ulrich
Browse files

added Readme and NEWS

parent 65507354
......@@ -15,8 +15,8 @@ Description: Intensity-duration-frequency (IDF) curves are a widely used analysi
The package 'IDF' provides functions to estimate IDF parameters for given
precipitation time series on the basis of a duration-dependent
generalised extreme value distribution
[Koutsoyannis et al., 1998, <doi:10.1016/S0022-1694(98)00097-3>].
Author: Jana Ulrich [aut, cre], Laura Mack [ctb], Christoph Ritschel [aut], Carola Detring [ctb], Sarah Joedicke [ctb]
[Koutsoyiannis et al., 1998, <doi:10.1016/S0022-1694(98)00097-3>].
Author: Jana Ulrich [aut, cre], Laura Mack [ctb], Oscar E. Jurado [ctb], Christoph Ritschel [aut], Carola Detring [ctb], Sarah Joedicke [ctb]
Maintainer: Jana Ulrich <jana.ulrich@fu-berlin.de>
Imports: stats,
evd,
......
# IDF 2.0.0
The package was extended to allow generalized linear modeling of the d-GEV parameters. This can be used to model for example spatial variations of the parameters.
The packet was extensively revised and restructured and some functions were removed as they were too specific.
# IDF 1.0.0
R package for maximum likelihood fitting of duration-dependent generalized extreme value distribution (d-GEV).
Additional functions forprocessing data (obtaining annual maxima) plotting IDF curves.
\ No newline at end of file
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# IDF
<!-- badges: start -->
<!-- badges: end -->
Intensity-duration-frequency (IDF) curves are a widely used analysis-tool
in hydrology to assessthe 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 \code{\link{gev.d.fit}}, 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](https://CRAN.R-project.org) with:
``` r
install.packages("IDF")
```
or from gitlab using:
``` r
devtools::install_git("https://gitlab.met.fu-berlin.de/Rpackages/IDF")
```
## 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
```{r sample data}
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
```{r annual max}
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
```{r fit}
fit <- gev.d.fit(xdat = ann.max$xdat,ds = ann.max$ds,sigma0link = make.link('log'))
# checking the fit
gev.d.diag(fit,pch=1,)
# parameter estimates
params <- gev.d.params(fit)
print(params)
# 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
,freq = FALSE,add=TRUE,border = d)
# etimated prob. density:
lines(q,dgev.d(q,params$mut,params$sigma0,params$xi,params$theta,params$eta,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
```{r idf}
plot(ann.max$ds,ann.max$xdat,log='xy',xlab = 'Duration [h]',ylab='Intensity [mm/h]')
IDF.plot(durations,params,add=TRUE)
```
<!-- README.md is generated from README.Rmd. Please edit that file -->
# IDF
<!-- badges: start -->
<!-- badges: end -->
Intensity-duration-frequency (IDF) curves are a widely used
analysis-tool in hydrology to assessthe 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](https://CRAN.R-project.org) with:
``` r
install.packages("IDF")
```
or from gitlab using:
``` r
devtools::install_git("https://gitlab.met.fu-berlin.de/Rpackages/IDF")
```
## 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
<!-- end list -->
``` r
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
<!-- end list -->
``` r
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]')
```
<img src="man/figures/README-annual max-1.png" width="100%" />
- Step 2: fit d-GEV to annual maxima
<!-- end list -->
``` r
fit <- gev.d.fit(xdat = ann.max$xdat,ds = ann.max$ds,sigma0link = make.link('log'))
#> $conv
#> [1] 0
#>
#> $nllh
#> [1] 73.81918
#>
#> $mle
#> [1] 5.384207e+00 6.400833e-01 -9.082818e-03 5.752210e-09 8.153861e-01
#>
#> $se
#> [1] 3.531081e-01 7.670363e-02 5.422432e-02 2.000074e-06 1.279425e-02
# checking the fit
gev.d.diag(fit,pch=1,)
```
<img src="man/figures/README-fit-1.png" width="100%" />
``` r
# parameter estimates
params <- gev.d.params(fit)
print(params)
#> mut sigma0 xi theta eta
#> 1 5.384207 1.896639 -0.009082818 5.75221e-09 0.8153861
# 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
,freq = FALSE,add=TRUE,border = d)
# etimated prob. density:
lines(q,dgev.d(q,params$mut,params$sigma0,params$xi,params$theta,params$eta,d = d),col=d)
}
legend('topright',col=1:2,lwd=1,legend = paste('d=',1:2,'h'),title = 'Duration')
```
<img src="man/figures/README-fit-2.png" width="100%" />
- Step 3: adding the IDF-curves to the data
<!-- end list -->
``` r
plot(ann.max$ds,ann.max$xdat,log='xy',xlab = 'Duration [h]',ylab='Intensity [mm/h]')
IDF.plot(durations,params,add=TRUE)
```
<img src="man/figures/README-idf-1.png" width="100%" />
......@@ -25,6 +25,10 @@ CRAN repository db overrides:
X-CRAN-Comment: Archived on 2020-03-13 as check problems were not
corrected in time.
The maintainer of this package has changed. The former maintainer did not inform us that check problems had occurred.
This submission is a substantially revised version.
## Reverse dependencies
This is a new release, so there are no reverse dependencies.
There are currently no downstream dependencies for this package.
......@@ -24,7 +24,7 @@ gev.d.diag(
\item{subset}{an optional vector specifying a subset of observations to be used in the plot}
\item{cols}{optional either one value or vector of same length as \code{unique(fit$ds)} to
specify the colors of plotting points.
specify the colors of plotting points.
The default uses the \code{rainbow} function.}
\item{pch}{optional either one value or vector of same length as \code{unique(fit$ds)} containing
......@@ -44,8 +44,8 @@ set to \code{c(1,1)}.}
\item{...}{additional parameters passed on to the plotting function}
}
\description{
Produces diagnostic plots for d-gev models using
the output of the function \code{\link{gev.d.fit}}. Values for different durations can be plotted in
Produces diagnostic plots for d-gev models using
the output of the function \code{\link{gev.d.fit}}. Values for different durations can be plotted in
different colors of with different symbols.
}
\examples{
......@@ -53,8 +53,8 @@ data('example',package ='IDF')
fit <- gev.d.fit(xdat=example$dat,ds = example$d,ydat=as.matrix(example[,c('cov1','cov2')])
,mutl=c(1,2),sigma0l=1)
# diagnostic plots for complete data
gev.d.diag(fit,pch=1)
# diagnostic plots for subset of data (e.g. one station)
# diagnostic plots for complete data
gev.d.diag(fit,pch=1)
# diagnostic plots for subset of data (e.g. one station)
gev.d.diag(fit,subset = example$cov1==1,pch=1)
}
......@@ -27,27 +27,27 @@ gev.d.fit(
)
}
\arguments{
\item{xdat}{A vector containing maxima for different durations.
\item{xdat}{A vector containing maxima for different durations.
This can be obtained from \code{\link{IDF.agg}}.}
\item{ds}{A vector of aggregation levels corresponding to the maxima in xdat.
\item{ds}{A vector of aggregation levels corresponding to the maxima in xdat.
1/60 corresponds to 1 minute, 1 corresponds to 1 hour.}
\item{ydat}{A matrix of covariates for generalized linear modeling of the parameters
(or NULL (the default) for stationary fitting). The number of rows should be the same as the
\item{ydat}{A matrix of covariates for generalized linear modeling of the parameters
(or NULL (the default) for stationary fitting). The number of rows should be the same as the
length of xdat.}
\item{mutl, sigma0l, xil, thetal, etal}{Numeric vectors of integers, giving the columns of ydat that contain
covariates for generalized linear modeling of the parameters (or NULL (the default)
covariates for generalized linear modeling of the parameters (or NULL (the default)
if the corresponding parameter is stationary).
Parameters are: modified location, scale offset, shape, duration offset, duration exponent, respectively.}
\item{mutlink, sigma0link, xilink, thetalink, etalink}{Link functions for generalized linear
\item{mutlink, sigma0link, xilink, thetalink, etalink}{Link functions for generalized linear
modeling of the parameters, created with \code{\link{make.link}}. The default is \code{make.link("identity")}.}
\item{init.vals}{list of length 5, giving initial values for all or some parameters
(order: mut, sigma0, xi, theta, eta). If as.list(rep(NA,5)) (the default) is given, initial parameters are obtained
internally by fitting the GEV separately for each duration and applying a linear model to obtain the
(order: mut, sigma0, xi, theta, eta). If as.list(rep(NA,5)) (the default) is given, initial parameters are obtained
internally by fitting the GEV separately for each duration and applying a linear model to obtain the
duration dependency of the location and shape parameter.
Initial values for covariate parameters are assumed as 0 if not given.}
......@@ -63,29 +63,29 @@ should stay zero.}
\item{...}{Other control parameters for the optimization.}
}
\value{
A list containing the following components.
A subset of these components are printed after the fit.
If \code{show} is TRUE, then assuming that successful convergence is indicated,
the components nllh, mle and se are always printed.
\item{nllh}{single numeric giving the negative log-likelihood value}
\item{mle}{numeric vector giving the MLE's for the modified location, scale_0, shape,
duration offset and duration exponent, resp.}
A list containing the following components.
A subset of these components are printed after the fit.
If \code{show} is TRUE, then assuming that successful convergence is indicated,
the components nllh, mle and se are always printed.
\item{nllh}{single numeric giving the negative log-likelihood value}
\item{mle}{numeric vector giving the MLE's for the modified location, scale_0, shape,
duration offset and duration exponent, resp.}
\item{se}{numeric vector giving the standard errors for the MLE's (in the same order)}
\item{trans}{A logical indicator for a non-stationary fit.}
\item{model}{A list with components mutl, sigma0l, xil, thetal and etal.}
\item{link}{A character vector giving inverse link functions.}
\item{conv}{The convergence code, taken from the list returned by \code{\link{optim}}.
\item{conv}{The convergence code, taken from the list returned by \code{\link{optim}}.
A zero indicates successful convergence.}
\item{data}{data is standardized to standard Gumbel.}
\item{cov}{The covariance matrix.}
\item{data}{data is standardized to standard Gumbel.}
\item{cov}{The covariance matrix.}
\item{vals}{Parameter values for every data point.}
\item{init.vals}{Initial values that were used.}
\item{ds}{Durations for every data point.}
}
\description{
Modified \code{\link[ismev]{gev.fit}} function for Maximum-likelihood fitting
for the duration-dependent generalized extreme
value distribution, following Koutsoyiannis et al. (1998), including generalized linear
Modified \code{\link[ismev]{gev.fit}} function for Maximum-likelihood fitting
for the duration-dependent generalized extreme
value distribution, following Koutsoyiannis et al. (1998), including generalized linear
modeling of each parameter.
}
\details{
......
......@@ -15,8 +15,8 @@ gev.d.params(fit, ydat = NULL)
data.frame containing mu_tilde, sigma0, xi, theta, eta (or mu, sigma, xi for gev.fit objects)
}
\description{
function to calculate mut, sigma0, xi, theta, eta
(modified location, scale offset, shape, duration offset, duration exponent)
function to calculate mut, sigma0, xi, theta, eta
(modified location, scale offset, shape, duration offset, duration exponent)
from results of \code{\link{gev.d.fit}} with covariates or link funktions other than identity.
}
\examples{
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment