extended manuals for functions with eta2 and tau

R/IDF.R

@@ -27,6 +27,11 @@
 #' 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.
+#' * The dependence of scale and location parameter on duration, \eqn{\sigma(d)} and \eqn{\mu(d)}, can be extended by multiscaling
+#' and flattening, if requested. Multiscaling introduces a second duration exponent \eqn{\eta_2}, enabling the model to change slope
+#' linearly with return period. Flattening adds a parameter \eqn{\tau}, that flattens the IDF curve for long durations:
+#' \deqn{\sigma(x)=\sigma_0(d+\theta)^{-\eta_2}+\tau }
+#' \deqn{\mu(x)=\tilde{\mu}(\sigma_0(d+\theta)^{-\eta_1}+\tau)}
 #' * 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. 

R/d-gev.R

@@ -10,8 +10,8 @@
 #' 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 eta2 numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.
-#' @param tau numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve)
+#' @param eta2 numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.
+#' @param tau numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.
 #' @param d positive numeric value, giving duration
 #' @param ... additional parameters passed to \code{\link[evd]{dgev}}
 #' 
@@ -68,8 +68,8 @@ dgev.d <- function(q,mut,sigma0,xi,theta,eta,d,eta2=NULL,tau=0,...) {
 #' @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 eta2 numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.
-#' @param tau numeric value, giving intensity offset (defining flattening of the IDF curve)
+#' @param eta2 numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.
+#' @param tau numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.
 #' @param d positive numeric value, giving duration
 #' @param ... additional parameters passed to \code{\link[evd]{pgev}}
 #' 
@@ -121,8 +121,8 @@ pgev.d <- function(q,mut,sigma0,xi,theta,eta,d,tau=0,eta2=NULL, ...) {
 #' @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 for short durations)
 #' @param eta numeric value, giving duration exponent (defining slope of the IDF curve)
-#' @param eta2 numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.
-#' @param tau numeric value, giving intensity offset (defining flattening of the IDF curve for long durations)
+#' @param eta2 numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.
+#' @param tau numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.
 #' @param d positive numeric value, giving duration
 #' @param ... additional parameters passed to \code{\link[evd]{qgev}}
 #' 
@@ -192,8 +192,8 @@ qgev.d <- function(p,mut,sigma0,xi,theta,eta,d,tau=0,eta2=NULL, ...) {
 #' @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 eta2 numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.
-#' @param tau numeric value, giving intensity offset (defining flattening of the IDF curve)
+#' @param eta2 numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.
+#' @param tau numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.
 #' @param d positive numeric value, giving duration
 #' 
 #' @details For details on the d-GEV and the parameter definitions, see \link{IDF-package}

R/gevdfit.R

@@ -44,10 +44,10 @@
 #' 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.}
+#' duration offset and duration exponent, resp. If requested, contains also second duration exponent and intensity-offset}
 #' \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{model}{A list with components mutl, sigma0l, xil, thetal and etal. If requested, contains also eta2l and taul}
 #' \item{link}{A character vector giving inverse link functions.}
 #' \item{conv}{The convergence code, taken from the list returned by \code{\link{optim}}.
 #' A zero indicates successful convergence.}
@@ -550,8 +550,8 @@ gev.d.diag <- function(fit,subset=NULL,cols=NULL,pch=NULL,which='both',mfrow=c(1
 
 #' Calculate gev(d) parameters from \code{gev.d.fit} output
 #'
-#' @description function to calculate mut, sigma0, xi, theta, eta
-#' (modified location, scale offset, shape, duration offset, duration exponent)
+#' @description function to calculate mut, sigma0, xi, theta, eta, eta2, tau
+#' (modified location, scale offset, shape, duration offset, duration exponent, second duration exponent, intensity offset)
 #' from results of \code{\link{gev.d.fit}} with covariates or link functions other than identity.
 #' @param fit fit object returned by \code{\link{gev.d.fit}} or \code{\link{gev.fit}}
 #' @param ydat A matrix containing the covariates in the same order as used in \code{gev.d.fit}.

man/IDF-package.Rd

@@ -25,6 +25,11 @@ 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 The dependence of location and scale parameter on duration, \eqn{\sigma(d)} and \eqn{\mu(d)}, can be extended by multiscaling
+and flattening, if requested. Multiscaling introduces a second duration exponent \eqn{\eta_2}, enabling the model to change slope
+linearly with return period. Flattening adds a parameter \eqn{\tau}, that flattens the IDF curve for long durations:
+\deqn{\sigma(x)=\sigma_0(d+\theta)^{-\eta_2}+\tau }
+\deqn{\mu(x)=\tilde{mu}(\sigma_0(d+\theta)^{-\eta}+\tau)}
 \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.

man/dgev.d.Rd

@@ -18,9 +18,9 @@ shape parameter \eqn{\xi}.}
 
 \item{d}{positive numeric value, giving duration}
 
-\item{eta2}{numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.}
+\item{eta2}{numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.}
 
-\item{tau}{numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve)}
+\item{tau}{numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.}
 
 \item{...}{additional parameters passed to \code{\link[evd]{dgev}}}
 }

man/gev.d.fit.Rd

@@ -79,10 +79,10 @@ 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.}
+duration offset and duration exponent, resp. If requested, contains also second duration exponent and intensity-offset}
 \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{model}{A list with components mutl, sigma0l, xil, thetal and etal. If requested, contains also eta2l and taul}
 \item{link}{A character vector giving inverse link functions.}
 \item{conv}{The convergence code, taken from the list returned by \code{\link{optim}}.
 A zero indicates successful convergence.}

man/gev.d.params.Rd

@@ -15,8 +15,8 @@ gev.d.params(fit, ydat = NULL)
 data.frame containing mu_tilde, sigma0, xi, theta, eta, eta2, tau (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, eta2, tau
+(modified location, scale offset, shape, duration offset, duration exponent, second duration exponent, intensity offset)
 from results of \code{\link{gev.d.fit}} with covariates or link functions other than identity.
 }
 \examples{

man/pgev.d.Rd

@@ -17,9 +17,9 @@ pgev.d(q, mut, sigma0, xi, theta, eta, d, tau = 0, eta2 = NULL, ...)
 
 \item{d}{positive numeric value, giving duration}
 
-\item{tau}{numeric value, giving intensity offset (defining flattening of the IDF curve)}
+\item{tau}{numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.}
 
-\item{eta2}{numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.}
+\item{eta2}{numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.}
 
 \item{...}{additional parameters passed to \code{\link[evd]{pgev}}}
 }

man/qgev.d.Rd

@@ -17,9 +17,9 @@ qgev.d(p, mut, sigma0, xi, theta, eta, d, tau = 0, eta2 = NULL, ...)
 
 \item{d}{positive numeric value, giving duration}
 
-\item{tau}{numeric value, giving intensity offset (defining flattening of the IDF curve for long durations)}
+\item{tau}{numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.}
 
-\item{eta2}{numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.}
+\item{eta2}{numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.}
 
 \item{...}{additional parameters passed to \code{\link[evd]{qgev}}}
 }

man/rgev.d.Rd

@@ -17,9 +17,9 @@ rgev.d(n, mut, sigma0, xi, theta, eta, d, tau = 0, eta2 = NULL)
 
 \item{d}{positive numeric value, giving duration}
 
-\item{tau}{numeric value, giving intensity offset (defining flattening of the IDF curve)}
+\item{tau}{numeric value, giving intensity offset \eqn{\tau} (defining flattening of the IDF curve). Default: \eqn{\tau=0}.}
 
-\item{eta2}{numeric value, giving a second duration exponent (needed for multiscaling). If multiscaling is not requested, \eqn{eta2=eta} should be used.}
+\item{eta2}{numeric value, giving a second duration exponent \eqn{\eta_2} (needed for multiscaling). Default: NULL, treated as \eqn{\eta_2=\eta}.}
 }
 \value{
 list containing vectors of random variables.