Author: Christoph Ritschel, Carola Detring, Sarah Joedicke
Maintainer: Christoph Ritschel <christoph.ritschel@met.fu-berlin.de>
Description: Intensity-duration-frequency (IDF) curves are a widely used analysis-tool in hydrology to assess extreme values of precipitation [e.g. Mailhot et al., 2007, <doi:10.1016/j.jhydrol.2007.09.019>]. The package 'IDF' provides a function to read precipitation data from German weather service (DWD) 'webwerdis' <http://www.dwd.de/EN/ourservices/webwerdis/webwerdis.html> files and Berlin station data from 'Stadtmessnetz' <http://www.geo.fu-berlin.de/en/met/service/stadtmessnetz/index.html> files, and additionally IDF parameters can be estimated also from a given data.frame containing a precipitation time series. The data is aggregated to given levels yearly intensity maxima are calculated either for the whole year or given months. From these intensity maxima IDF parameters are estimated on the basis of a duration-dependent generalised extreme value distribution [Koutsoyannis et al., 1998, <doi:10.1016/S0022-1694(98)00097-3>]. IDF curves based on these estimated parameters can be plotted.
\item{data}{a \code{data,frame}, preferably generated by function \code{IDF.read}. It should at least contain a \code{$RR} and \code{$year} element for the
function tow work properly.}
\item{agg.lev}{a vector of aggregation levels used to fit the IDF curves.}
\item{month}{\code{integer} value specifying the month to be used for estimating the IDF parameters. Type "all" for all months or if
the whole time series should be fitted.}
\item{moving.sum}{\code{logical} specifying if moving sum filtering should be applied for time series aggregation.}
\item{mu.init}{initial estimation of location parameter, default is NA. Initial value estimated by fitting individual gev parameters}
\item{sigma.init}{initial estimation of scale parameter,default is NA. Initial value estimated by fitting individual gev parameters}
\item{xi.init}{inital estimation of shape parameter, default is NA. Initial value estimated by fitting individual gev parameters}
\item{theta.init}{inital value defining the curvature of the IDF, default is zero, it is not recommended to change it}
\item{eta.init}{intial estimation of slope parameter for sigma-power law, default is NA. Initial value estimated by fitting individual gev parameters}
\item{use.log}{\code{logical} value for usage of logarithmic values, default is \code{FALSE}}
\item{DEBUG}{\code{logical} value for usage of debugging, if \code{TRUE} the input parameters and the value of negative}
\item{method}{\code{character} defining the method to be used in \code{optim}, preferences are: "Nelder-Mead", "BFGS", "L-BFGS-B"e}
\item{upper}{\code{vector} specifying the upper boundary of parameters for "L-BFGS-B" method}
\item{lower}{\code{vector} specifying the lower boundary of parameters for "L-BFGS-B" method}
\item{plot}{\code{logical} option of creating a plot of IDF curves with estimated parameters.}
\item{probs}{a vector of probabilities for which the IDF curves are calculated}
\item{cols}{a vector of colors for the seperate IDF curves, needs same length as \code{probs}}
\item{station.name}{\code{character} overall naming of the IDF plot, e.g. name of location or model name}
\item{data.name}{\code{character} naming the data points, e.g. obs or model name}
}
\value{
$ints vector of sorted intensities for selected aggregation levels
$durs vector of sorted aggregation levels
$min minimum value of negative log-likelihood during optimization
$par vector of estimated IDF model parameters mu,sigma,xi,theta,eta at minimum value of negative log-likelihood.
}
\description{
The function \code{IDF.fit} fits the IDF model parameters \code{mu,sigma,xi,eta,theta}
to a data.frame of observations \code{data} with temporal inforamtion (at least years) and values of precipitation
at a given temporal resoultion. This precipitation time series gets aggregated at given aggregation levels.
\code{agg.lev} and yearly maxima of intensity are caluclated for a specific month or the whole year/dataset.
The starting values of the IDF model parameters can be determined by the user as well as specific options to use
during optimization. Logartihmic transformation, debugging, the optimization method, and an option to plot the
IDF curves.
}
\examples{
RR <- rgamma(10*30*24,shape=1)
year <- sort(rep(1:(10),30*24))
data <- data.frame(RR,year)
fit <- IDF.fit(data)
pars <- fit$par
}
\author{
Christoph Ritschel \email{christoph.ritschel@met.fu-berlin.de}
\item{x}{a \code{list} containing a \code{data.frame} named 't1', preferably generated by function \code{IDF.read}.}
\item{data}{a \code{data,frame}, preferably generated by function \code{IDF.read}. It should at least contain a \code{$RR} and \code{$year} element for the
function tow work properly. Also an option to use \code{moving.sum} is given. The function returns a vector of intensities and durations as well as the number of years of data.}
\item{ks}{a numeric \code{vector} of aggregatation levels. Each value represents an aggregation level and will create
a new \code{data.frame} in the output list.}
\item{agg.lev}{a vector of aggregation levels used to fit the IDF curves.}
\item{month}{\code{integer} value specifying the month to be used for estimating the IDF parameters. Type "all" for all months or if
the whole time series should be fitted.}
\item{moving.sum}{\code{logical} specifying if moving sum filtering should be applied for time series aggregation.}
}
\value{
Liste a \code{list} containing \code{data.frames} of original and aggregated precipitation time series with time information and
precipitation values.
$ints.vec vector of sorted intensities for selected aggregation levels
$durs vector of sorted aggregation levels
$n.y number of years of data
}
\description{
The function \code{IDF.agg} aggregates the precipitation values of a \code{data.frame} in a \code{list} in groups.
The list should be created by function \code{IDF.read} in a previous step.
The function \code{IDF.agg} aggregates a data.frame of observations \code{data} with temporal inforamtion (at least years) and values of precipitation
at a given temporal resoultion at given aggregation levels \code{agg.lev} and yearly maxima of intensity are caluclated for a specific month or the whole year/dataset.
}
\details{
This function is designed to aggregate data which has been read by function \code{IDF.read}.
The time given in the data is the end time, so the precipitation was added up to that time.
In this process the data will be summed up in groups, depending on the chosen aggregation levels. In the end,
the aggregated \code{data.frames} will be much shorter than the original one.
In the end, a new \code{list} containing several \code{data.frames} will be created. The first one will be the
initial data frame, now named agg0. The other data frames will be named 'agg' + the aggregation level number from ks.
\examples{
RR <- rgamma(10*30*24,shape=1)
year <- sort(rep(1:(10),30*24))
data <- data.frame(RR,year)
data.agg <- IDF.agg(data)
}
\author{
Sarah Joedicke \email{sarah.joedicke@fu-berlin.de}
}
\seealso{
read.data, agg.f().
Christoph Ritschel \email{christoph.ritschel@met.fu-berlin.de}
