Commit 047bc0d7 authored by Jana Ulrich's avatar Jana Ulrich
Browse files

worked on description (IDF-package) + references + equations. Still need to...

worked on description (IDF-package) + references + equations. Still need to change parameter names in gev.d.diag, gev.d.fit, ged.d.params, gev.d.nll (tomorrow)
parent 8415f671
# This file contains the functions:
# This file contains:
# -IDF-package description
# -IDF.agg for preparing the data
# -IDF.plot for plotting of IDF curves at a chosen station
#### IDF-package ####
#' Introduction
#' @name IDF-package
#' @docType package
#' @description This package provides functions to estimate IDF relations for given
#' precipitation time series on the basis of a duration-dependent
#' generalized extreme value distribution (d-GEV).
#' 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. This function was implemented on the basis of \code{\link[ismev]{gev.fit}}.
#' 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).
#' @details
#' * The __d-GEV__ is defined following Koutsoyannis et al. (1998):
#' \deqn{G(x)= \exp[-( 1+\xi(x/\sigma(d)- \tilde{\mu}) ) ^{-1/\xi}] }
#' defined on \eqn{ \{ x: 1+\xi(x/\sigma(d)- \tilde{\mu} > 0) \} },
#' with the duration dependent scale parameter \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta > 0},
#' modified location parameter \eqn{\tilde{\mu}=\mu/\sigma(d)\in R}
#' and shape parameter \eqn{\xi\in R}, \eqn{\xi\neq 0}.
#' The parameters \eqn{\theta \leq 0} and \eqn{0<\eta<1} are duration offset and duration exponent
#' and describe the slope and curvature in the resulting IDF curves, respectively.
#' * A useful introduction to __Maximum Likelihood Estimation__ for fitting for the
#' generalized extreme value distribution (GEV) is provided by Coles (2001). It should be noted, however, that this method uses
#' the assumption that block maxima (of different durations or stations) are independent of each other.
#' @references
#' * Ulrich, J.; Jurado, O.E.; Peter, M.; Scheibel, M.;
#' Rust, H.W. Estimating IDF Curves Consistently over Durations with Spatial Covariates. Water 2020, 12, 3119,
#' https://doi.org/10.3390/w12113119
#' * Demetris Koutsoyiannis, Demosthenes Kozonis, Alexandros Manetas,
#' A mathematical framework for studying rainfall intensity-duration-frequency relationships,
#' Journal of Hydrology,
#' Volume 206, Issues 1–2,1998,Pages 118-135,ISSN 0022-1694, https://doi.org/10.1016/S0022-1694(98)00097-3
#' * Coles, S.An Introduction to Statistical Modeling of Extreme Values; Springer: New York, NY, USA, 2001,
#' https://doi.org/10.1198/tech.2002.s73
#' @md
NULL
#### IDF.agg ####
#' Aggregation and annual maxima for chosen durations
......@@ -105,7 +145,7 @@
#'
#' @param durations vector of durations for which to calculate the quantiles.
#' @param fitparams vector containing parameters mut, sigma0, xi, theta, eta
#' (modified location, scale, shape, duration offset, duration exponent) for chosen station
#' (modified location, scale offset, shape, duration offset, duration exponent) for chosen station
#' as obtained from \code{\link{gev.d.fit}}
#' (or \code{\link{gev.d.params}} for model with covariates).
#' @param probs vector of exeedance probabilities for which to plot IDF curves (p = 1-1/ReturnPeriod)
......
......@@ -2,26 +2,23 @@
#### dgev.d() ####
#' Density function of duration dependent GEV distribution
#' d-GEV probability density function
#'
#' @description Probability density function of duration-dependent GEV distribution
#' @param q vector of quantiles
#' @param mut,sigma0,xi numeric value, giving modified location, modified scale and shape parameter
#' @param theta numeric value, giving duration offset (defining curvature of the IDF curve)
#' @param eta numeric value, giving duration exponent (defining slope of the IDF curve)
#' @param mut,sigma0,xi numeric value, giving modified location \eqn{\tilde{\mu}}, scale offset \eqn{\tilde{\sigma_0}} and
#' shape parameter \eqn{\xi}.
#' @param theta numeric value, giving duration offset \eqn{\theta} (defining curvature of the IDF curve)
#' @param eta numeric value, giving duration exponent \eqn{\eta} (defining slope of the IDF curve)
#' @param d positive numeric value, giving duration
#' @param ... additional parameters passed to \code{\link[evd]{dgev}}
#'
#' @details The duration dependent GEV distribution is defined after
#' [Koutsoyannis et al., 1998]:
#' \deqn{ G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
#' with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
#' modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
#' @details For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
#'
#' @return list containing vectors of density values for given quantiles
#' the first element of the list are the dens. values for the first given duration and so on
#' @return list containing vectors of density values for given quantiles.
#' The first element of the list are the density values for the first given duration etc.
#'
#' @seealso \code{\link{pgev.d}}, \code{\link{qgev.d}}, \code{\link{rgev.d}}
#' @references Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
#'
#' @export
#' @importFrom evd dgev
......@@ -57,8 +54,9 @@ dgev.d <- function(q,mut,sigma0,xi,theta,eta,d,...) {
#### pgev.d() ####
#' Distribution function of duration dependent GEV distribution
#' d-GEV cumulative distribution function
#'
#' @description Cumulative probability distribution function of duration-dependent GEV distribution
#' @param q vector of quantiles
#' @param mut,sigma0,xi numeric value, giving modified location, modified scale and shape parameter
#' @param theta numeric value, giving duration offset (defining curvature of the IDF curve)
......@@ -72,11 +70,12 @@ dgev.d <- function(q,mut,sigma0,xi,theta,eta,d,...) {
#' with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
#' modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
#'
#' @return list containing vectors of probability values for given quantiles
#' the first element of the list are the prob. values for the first given duration and so on
#' @details For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
#'
#' @return list containing vectors of probability values for given quantiles.
#' The first element of the list are the probability values for the first given duration etc.
#'
#' @seealso \code{\link{dgev.d}}, \code{\link{qgev.d}}, \code{\link{rgev.d}}
#' @references Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
#'
#' @export
#' @importFrom evd pgev
......@@ -101,8 +100,9 @@ pgev.d <- function(q,mut,sigma0,xi,theta,eta,d,...) {
#### qgev.d() ####
#' Quantile function of duration dependent GEV distribution
#' d-GEV quantile function
#'
#' @description Quantile function of duration-dependent GEV distribution (inverse of the cumulative probability distribution function)
#' @param p vector of probabilities
#' @param mut,sigma0,xi numeric value, giving modified location, modified scale and shape parameter
#' @param theta numeric value, giving duration offset (defining curvature of the IDF curve)
......@@ -116,11 +116,12 @@ pgev.d <- function(q,mut,sigma0,xi,theta,eta,d,...) {
#' with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
#' modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
#'
#' @return list containing vectors of quantile values for given probabilities
#' the first element of the list are the q. values for the first given duration and so on
#' @return list containing vectors of quantile values for given probabilities.
#' The first element of the list are the q. values for the first given duration etc.
#'
#' @details For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
#'
#' @seealso \code{\link{pgev.d}}, \code{\link{dgev.d}}, \code{\link{rgev.d}}
#' @references Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
#'
#' @export
#' @importFrom evd qgev
......@@ -159,25 +160,22 @@ qgev.d <- function(p,mut,sigma0,xi,theta,eta,d,...) {
#### rgev.d() ####
#' random generation of variables from duration dependent GEV distribution
#' Generation of random variables from d-GEV
#'
#' @param n number of observations.
#' @description Generation of random variables following duration-dependent GEV.
#' @param n number of random variables per duration
#' @param mut,sigma0,xi numeric value, giving modified location, modified scale and shape parameter
#' @param theta numeric value, giving duration offset (defining curvature of the IDF curve)
#' @param eta numeric value, giving duration exponent (defining slope of the IDF curve)
#' @param d positive numeric value, giving duration
#'
#' @details The duration dependent GEV distribution is defined after
#' [Koutsoyannis et al., 1998]:
#' \deqn{ G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
#' with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
#' modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
#' @details For details on the d-GEV and the parameter definitions, see \link{IDF-package}
#'
#' @return list containing vectors of random values
#' the first element of the list are the random values for the first given duration and so on
#' @return list containing vectors of random variables.
#' The first element of the list are the random values for the first given duration etc.
#' Note that the random variables for different durations are nor ordered (contrary to precipitation maxima of different durations).
#'
#' @seealso \code{\link{pgev.d}}, \code{\link{qgev.d}}, \code{\link{dgev.d}}
#' @references Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
#'
#' @export
#' @importFrom evd rgev
......
......@@ -496,23 +496,26 @@ gev.d.params <- function(fit,ydat){
#### example data ####
#' Sampled data for duration dependent GEV
#' Sampled data for duration-dependent GEV
#'
#' A dataset containing:
#' @description
#' Randomly sampled data set used for running the example code, containing:
#' \itemize{
#' \item \code{$xdat}: 'annual' maxima values
#' \item \code{$ds}: corresponding durations
#' \item \code{$cov1}, \code{$cov2}: covariates}
#' GEV parameters:
#' d-GEV parameters used for sampling:
#' \itemize{
#' \item mu = 4 + 0.2*cov1 +0.5*cov2
#' \item sigma = 2+0.5*cov1
#' \item xi = 0.5
#' \item theta = 0
#' \item eta = 0.5}
#' \item \eqn{\tilde{\mu} = 4 + 0.2 cov_1 +0.5 cov_2}
#' \item \eqn{\sigma_0 = 2+0.5 cov_1}
#' \item \eqn{\xi = 0.5}
#' \item \eqn{\theta = 0}
#' \item \eqn{\eta = 0.5}}
#'
#'
#' @docType data
#' @keywords datasets
#' @name example
#' @usage data('example',package ='IDF')
#' @format A data frame with 330 rows and 4 variables
NULL
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/IDF.R
\docType{package}
\name{IDF-package}
\alias{IDF-package}
\title{Introduction}
\description{
This package provides functions to estimate IDF relations for given
precipitation time series on the basis of a duration-dependent
generalized extreme value distribution (d-GEV).
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. This function was implemented on the basis of \code{\link[ismev]{gev.fit}}.
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).
}
\details{
\itemize{
\item The \strong{d-GEV} is defined following Koutsoyannis et al. (1998):
\deqn{G(x)= \exp[-( 1+\xi(x/\sigma(d)- \tilde{\mu}) ) ^{-1/\xi}] }
defined on \eqn{ \{ x: 1+\xi(x/\sigma(d)- \tilde{\mu} > 0) \} },
with the duration dependent scale parameter \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta > 0},
modified location parameter \eqn{\tilde{\mu}=\mu/\sigma(d)\in R}
and shape parameter \eqn{\xi\in R}, \eqn{\xi\neq 0}.
The parameters \eqn{\theta \leq 0} and \eqn{0<\eta<1} are duration offset and duration exponent
and describe the slope and curvature in the resulting IDF curves, respectively.
\item A useful introduction to \strong{Maximum Likelihood Estimation} for fitting for the
generalized extreme value distribution (GEV) is provided by Coles (2001). It should be noted, however, that this method uses
the assumption that block maxima (of different durations or stations) are independent of each other.
}
}
\references{
\itemize{
\item Ulrich, J.; Jurado, O.E.; Peter, M.; Scheibel, M.;
Rust, H.W. Estimating IDF Curves Consistently over Durations with Spatial Covariates. Water 2020, 12, 3119,
https://doi.org/10.3390/w12113119
\item Demetris Koutsoyiannis, Demosthenes Kozonis, Alexandros Manetas,
A mathematical framework for studying rainfall intensity-duration-frequency relationships,
Journal of Hydrology,
Volume 206, Issues 1–2,1998,Pages 118-135,ISSN 0022-1694, https://doi.org/10.1016/S0022-1694(98)00097-3
\item Coles, S.An Introduction to Statistical Modeling of Extreme Values; Springer: New York, NY, USA, 2001,
https://doi.org/10.1198/tech.2002.s73
}
}
......@@ -18,7 +18,7 @@ IDF.plot(
\item{durations}{vector of durations for which to calculate the quantiles.}
\item{fitparams}{vector containing parameters mut, sigma0, xi, theta, eta
(modified location, scale, shape, duration offset, duration exponent) for chosen station
(modified location, scale offset, shape, duration offset, duration exponent) for chosen station
as obtained from \code{\link{gev.d.fit}}
(or \code{\link{gev.d.params}} for model with covariates).}
......
......@@ -2,36 +2,33 @@
% Please edit documentation in R/d-gev.R
\name{dgev.d}
\alias{dgev.d}
\title{Density function of duration dependent GEV distribution}
\title{d-GEV probability density function}
\usage{
dgev.d(q, mut, sigma0, xi, theta, eta, d, ...)
}
\arguments{
\item{q}{vector of quantiles}
\item{mut, sigma0, xi}{numeric value, giving modified location, modified scale and shape parameter}
\item{mut, sigma0, xi}{numeric value, giving modified location \eqn{\tilde{\mu}}, scale offset \eqn{\tilde{\sigma_0}} and
shape parameter \eqn{\xi}.}
\item{theta}{numeric value, giving duration offset (defining curvature of the IDF curve)}
\item{theta}{numeric value, giving duration offset \eqn{\theta} (defining curvature of the IDF curve)}
\item{eta}{numeric value, giving duration exponent (defining slope of the IDF curve)}
\item{eta}{numeric value, giving duration exponent \eqn{\eta} (defining slope of the IDF curve)}
\item{d}{positive numeric value, giving duration}
\item{...}{additional parameters passed to \code{\link[evd]{dgev}}}
}
\value{
list containing vectors of density values for given quantiles
the first element of the list are the dens. values for the first given duration and so on
list containing vectors of density values for given quantiles.
The first element of the list are the density values for the first given duration etc.
}
\description{
Density function of duration dependent GEV distribution
Probability density function of duration-dependent GEV distribution
}
\details{
The duration dependent GEV distribution is defined after
[Koutsoyannis et al., 1998]:
\deqn{ G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
}
\examples{
x <- seq(4,20,0.1)
......@@ -48,9 +45,6 @@ for(i in 2:4){
}
legend('topright',title = 'duration',legend = 1:4,lty=1:4)
}
\references{
Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
}
\seealso{
\code{\link{pgev.d}}, \code{\link{qgev.d}}, \code{\link{rgev.d}}
}
......@@ -3,22 +3,25 @@
\docType{data}
\name{example}
\alias{example}
\title{Sampled data for duration dependent GEV}
\title{Sampled data for duration-dependent GEV}
\format{
A data frame with 330 rows and 4 variables
}
\usage{
data('example',package ='IDF')
}
\description{
A dataset containing:
Randomly sampled data set used for running the example code, containing:
\itemize{
\item \code{$xdat}: 'annual' maxima values
\item \code{$ds}: corresponding durations
\item \code{$cov1}, \code{$cov2}: covariates}
GEV parameters:
d-GEV parameters used for sampling:
\itemize{
\item mu = 4 + 0.2*cov1 +0.5*cov2
\item sigma = 2+0.5*cov1
\item xi = 0.5
\item theta = 0
\item eta = 0.5}
\item \eqn{\tilde{\mu} = 4 + 0.2 cov_1 +0.5 cov_2}
\item \eqn{\sigma_0 = 2+0.5 cov_1}
\item \eqn{\xi = 0.5}
\item \eqn{\theta = 0}
\item \eqn{\eta = 0.5}}
}
\keyword{datasets}
......@@ -2,7 +2,7 @@
% Please edit documentation in R/d-gev.R
\name{pgev.d}
\alias{pgev.d}
\title{Distribution function of duration dependent GEV distribution}
\title{d-GEV cumulative distribution function}
\usage{
pgev.d(q, mut, sigma0, xi, theta, eta, d, ...)
}
......@@ -20,11 +20,11 @@ pgev.d(q, mut, sigma0, xi, theta, eta, d, ...)
\item{...}{additional parameters passed to \code{\link[evd]{pgev}}}
}
\value{
list containing vectors of probability values for given quantiles
the first element of the list are the prob. values for the first given duration and so on
list containing vectors of probability values for given quantiles.
The first element of the list are the probability values for the first given duration etc.
}
\description{
Distribution function of duration dependent GEV distribution
Cumulative probability distribution function of duration-dependent GEV distribution
}
\details{
The duration dependent GEV distribution is defined after
......@@ -32,14 +32,13 @@ The duration dependent GEV distribution is defined after
\deqn{G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
}
\examples{
x <- seq(4,20,0.1)
prob <- pgev.d(q=x,mut=4,sigma0=2,xi=0,theta=0.1,eta=0.1,d=1)
}
\references{
Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
}
\seealso{
\code{\link{dgev.d}}, \code{\link{qgev.d}}, \code{\link{rgev.d}}
}
......@@ -2,7 +2,7 @@
% Please edit documentation in R/d-gev.R
\name{qgev.d}
\alias{qgev.d}
\title{Quantile function of duration dependent GEV distribution}
\title{d-GEV quantile function}
\usage{
qgev.d(p, mut, sigma0, xi, theta, eta, d, ...)
}
......@@ -20,11 +20,11 @@ qgev.d(p, mut, sigma0, xi, theta, eta, d, ...)
\item{...}{additional parameters passed to \code{\link[evd]{qgev}}}
}
\value{
list containing vectors of quantile values for given probabilities
the first element of the list are the q. values for the first given duration and so on
list containing vectors of quantile values for given probabilities.
The first element of the list are the q. values for the first given duration etc.
}
\description{
Quantile function of duration dependent GEV distribution
Quantile function of duration-dependent GEV distribution (inverse of the cumulative probability distribution function)
}
\details{
The duration dependent GEV distribution is defined after
......@@ -32,6 +32,8 @@ The duration dependent GEV distribution is defined after
\deqn{ G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
For details on the d-GEV and the parameter definitions, see \link{IDF-package}.
}
\examples{
p <- c(0.5,0.9,0.99)
......@@ -50,9 +52,6 @@ for(i in 2:3){
legend('topright',title = 'Annual frequency of exceedance',
legend = 1-p,lty=1:3,bty = 'n')
}
\references{
Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
}
\seealso{
\code{\link{pgev.d}}, \code{\link{dgev.d}}, \code{\link{rgev.d}}
}
......@@ -2,12 +2,12 @@
% Please edit documentation in R/d-gev.R
\name{rgev.d}
\alias{rgev.d}
\title{random generation of variables from duration dependent GEV distribution}
\title{Generation of random variables from d-GEV}
\usage{
rgev.d(n, mut, sigma0, xi, theta, eta, d)
}
\arguments{
\item{n}{number of observations.}
\item{n}{number of random variables per duration}
\item{mut, sigma0, xi}{numeric value, giving modified location, modified scale and shape parameter}
......@@ -18,18 +18,15 @@ rgev.d(n, mut, sigma0, xi, theta, eta, d)
\item{d}{positive numeric value, giving duration}
}
\value{
list containing vectors of random values
the first element of the list are the random values for the first given duration and so on
list containing vectors of random variables.
The first element of the list are the random values for the first given duration etc.
Note that the random variables for different durations are nor ordered (contrary to precipitation maxima of different durations).
}
\description{
random generation of variables from duration dependent GEV distribution
Generation of random variables following duration-dependent GEV.
}
\details{
The duration dependent GEV distribution is defined after
[Koutsoyannis et al., 1998]:
\deqn{ G(x)= \exp[-\left( 1+\xi(x/\sigma(d)-\mu_t) \right)^{-1/\xi}] }
with the duration dependent scale \eqn{\sigma(d)=\sigma_0/(d+\theta)^\eta} and
modified location parameter \eqn{\mu_t=\mu/\sigma(d)}.
For details on the d-GEV and the parameter definitions, see \link{IDF-package}
}
\examples{
# random sample for one duration
......@@ -43,9 +40,6 @@ hist(samp[[1]],breaks = 10,col=rgb(1,0,0,0.5),freq = FALSE
,ylim=c(0,0.3),xlab='x',main = 'd-GEV samples for two different durations')
hist(samp[[2]],breaks = 10,add=TRUE,col=rgb(0,0,1,0.5),freq = FALSE)
}
\references{
Koutsoyannis et al., 1998, doi:10.1016/S0022-1694(98)00097-3
}
\seealso{
\code{\link{pgev.d}}, \code{\link{qgev.d}}, \code{\link{dgev.d}}
}
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