\HeaderA{GevGlmFit}{Modelling the GEV Distribution including GLM}{GevGlmFit}
\aliasA{gevglmFit}{GevGlmFit}{gevglmFit}
\aliasA{gevglmprofPlot}{GevGlmFit}{gevglmprofPlot}
\aliasA{gevglmprofxiPlot}{GevGlmFit}{gevglmprofxiPlot}
\aliasA{plot.gevglmFit}{GevGlmFit}{plot.gevglmFit}
\aliasA{print.gevglmFit}{GevGlmFit}{print.gevglmFit}
\aliasA{summary.gevglmFit}{GevGlmFit}{summary.gevglmFit}
\keyword{models}{GevGlmFit}
\begin{Description}\relax
A collection and description of functions to model the 
Generalized Extreme Value, GEV, distribution by maximum 
likelihood approximation based on R's 'ismev' package. In 
addition to the function gevFit the parameter estimation 
allows to include generalized linear modelling, GLM, of 
each parameter.
\\

The functions are:

\Tabular{ll}{
\code{gevglmFit} & fits empirical or simulated data to the distribution, \\ 
\code{print} & print method for a fitted GEV object of class ..., \\
\code{plot} & plot method for a fitted GEV object, \\ 
\code{summary} & summary method for a fitted GEV object, \\
\code{gevglmprofPlot} & profile log-likelihoods for return levels, \\ 
\code{gevglmprofxiPlot} & profile log-likelihoods for shape parameters. }
\end{Description}
\begin{Usage}
\begin{verbatim}
gevglmFit(x, y = NULL, gumbel = FALSE, mul = NULL, sigl = NULL, shl = NULL, 
    mulink = identity, siglink = identity, shlink = identity, show = FALSE, 
    method = "Nelder-Mead", maxit = 10000, ...)

## S3 method for class 'gevglmFit':
print(x, ...)
## S3 method for class 'gevglmFit':
plot(x, which = "ask", ...)
## S3 method for class 'gevglmFit':
summary(object, doplot = TRUE, which = "all", ...)

gevglmprofPlot(object, m, xlow, xup, conf = 0.95, nint = 100)
gevglmprofxiPlot(object, xlow, xup, conf = 0.95, nint = 100)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{conf}] [gevglmprof*Plot] - \\
the confidence coefficient of the plotted profile confidence 
interval.

\item[\code{doplot}] a logical. Should the results be plotted?

\item[\code{gumbel}] [gevglmFit] - \\
a logical, should a Gumbel fit be created? In this case the shape
parameter equals zero, and the arguments \code{shl} and and 
\code{shlink} are omitted.

\item[\code{m}] [gevglmprofPlot] - \\
the return level; i.e. the profile likelihood is for the value 
that is exceeded with probability 1/\code{m}.

\item[\code{maxit}] [gevglmFit] - \\
the maximum number of iterations.

\item[\code{method}] [gevglmFit] - \\
the optimization method (see \code{\LinkA{optim}{optim}} for details).

\item[\code{mul, sigl, shl}] [gevglmFit] - \\
numeric vectors of integers, giving the columns
of \code{ydat} that contain covariates for generalized linear
modelling of the location, scale and shape parameters repectively
(or \code{NULL} (the default) if the corresponding parameter is
stationary).

\item[\code{mulink, siglink, shlink}] [gevglmFit] - \\
inverse link functions for generalized linear modelling of the 
location, scale and shape parameters repectively.

\item[\code{nint}] [gevglmprof*Plot] - \\
the number of points at which the profile likelihood is evaluated.

\item[\code{object}] [summary][grlevelPlot] - \\
a fitted object of class \code{"gevglmFit"}.

\item[\code{show}] [gevglmFit] - \\
a logical; if \code{TRUE} (the default), print details of
the fit.

\item[\code{x}] [gevglmFit] - \\
a numeric vector of data to be fitted.
\\{}
[print][plot] - \\
a fitted object of class \code{"gevglmFit"}.

\item[\code{xlow, xup}] [gevglmprof*Plot] - \\
the least and greatest value at which to evaluate the profile 
likelihood.

\item[\code{y}] [gevglmFit] - \\
a matrix of covariates for generalized linear modelling
of the parameters (or \code{NULL} (the default) for stationary
fitting). The number of rows should be the same as the length
of \code{xdat}.

\item[\code{which}] [plot][summary] - \\
a vector of logicals, one for each plot, denoting which plot 
should be displayed.

\item[\code{...}] [gevglmFit] - \\
control parameters optionally passed to the 
optimization function. Parameters for the optimization
function are passed to components of the \code{control} argument of
\code{optim}. 
\\{}
[plot][summary] - \\
arguments passed to the plot function.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\bold{Simulation:}
\\\\
To simulate a GEV series use the function \code{gevSim}. 
\\

\bold{Parameter Estimation:}
\\\\
\code{gevglmFit} fits by the Maximum-likelihood approach the generalized 
extreme value distribution, including generalized linear modelling 
of each parameter. 
\\

\bold{Methods:}
\\\\
\code{print.gevglm}, \code{plot.gevglm} and \code{summary.gevglm} 
are print, plot, and summary methods for a fitted object of class 
\code{gevglmFit}.
\\

\bold{Profile Likelihood:}
\\\\
\code{gevglmprofPlot} and \code{gevglmprofxiPlot} produce profile 
log-likelihoods for shape parameters and \code{m} year/block return 
levels for stationary GEV models using the output of the function 
\code{gevFit}.
\\

\bold{Nonstationary Models:}
\\\\
For non-stationary fitting it is recommended that the covariates
within the generalized linear models are (at least approximately)
centered and scaled (i.e.\ the columns of \code{ydat} should be
approximately centered and scaled).
\end{Details}
\begin{Value}
\code{gevglmFit}
\\
returns a list containing the following components.
A subset of these components are printed after the fit. If \code{show} 
is \code{TRUE}, then assuming that successful convergence is
indicated, the components \code{nllh}, \code{mle} and \code{se}
are always printed.

\begin{ldescription}
\item[\code{trans}] an logical indicator for a non-stationary fit.

\item[\code{model}] a list with components \code{mul}, \code{sigl}
and \code{shl}.

\item[\code{link}] a character vector giving inverse link functions.

\item[\code{conv}] the convergence code, taken from the list returned by
\code{\LinkA{optim}{optim}}. A zero indicates successful convergence.

\item[\code{nllh}] the negative logarithm of the likelihood evaluated at
the maximum likelihood estimates.

\item[\code{data}] the data that has been fitted. For non-stationary
models, the data is standardized.

\item[\code{mle}] a vector containing the maximum likelihood estimates.

\item[\code{cov}] the covariance matrix.

\item[\code{se}] a vector containing the standard errors.

\item[\code{vals}] a matrix with three columns containing the maximum
likelihood estimates of the location, scale and shape parameters
at each data point.

\end{ldescription}
  

For stationary models four plots are produced; a probability
plot, a quantile plot, a return level plot and a histogram
of data with fitted density. For non-stationary models two plots 
are produced; a residual probability plot and a residual quantile 
plot.
\\

\code{gevglmprofPlot}\\
\code{gevglmprofxiPlot}\\
a plot of the profile likelihood is produced, with a horizontal line 
representing a profile confidence interval with confidence coefficient 
\code{conf}.
\end{Value}
\begin{Author}\relax
Alec Stephenson for the code implemented from \R's ismev package, \\
Stuart Scott for the original code, and
Diethelm Wuertz for this \R-port.
\end{Author}
\begin{References}\relax
Coles S. (2001);
\emph{Introduction to Statistical Modelling of Extreme Values},
Springer.
\end{References}
\begin{Examples}
\begin{ExampleCode}
## SOURCE("fExtremes.54A-ExtremesGlm")

## Simulated GEV Data:
   xmpExtremes("\nStart: Simulte GEV Sample >")
   x = gevSim(model = list(shape = 0.25, location = 0, scale = 1), n = 1000)
   par(mfrow = c(2, 2))
   plot(x, main = "Simulated GEV Data")
   # Fit GEV Data:
   fit = gevglmFit(x) 
   print(fit)
   # Summarize Results:
   summary(fit, which = c(TRUE, TRUE, TRUE, FALSE))
   
## Simulated GEV Data:
   xmpExtremes("\nNext: Estimate Parameters >")
   ##> x = gevSim(model = list(shape = 0, location = 0, scale = 1), n = 1000)
   ##> par(mfrow = c(2, 2))
   ##> plot(x, main = "Simulated Gumbel Data")
   # Fit GEV Data:
   ##> fit = gevglmFit(x, gumbel = TRUE) 
   ##> print(fit)
   # Summarize Results:
   ##> summary(fit, which = c(TRUE, TRUE, TRUE, FALSE))
   
## Portpirie Data:
   xmpExtremes("\nNext: Fit Portpirie Data >")
   par(mfrow = c(2, 1))
   data(portpirie)
   fit = gevglmFit(portpirie[, 2])
   gevglmprofPlot(fit, m = 10, 4.1, 5)
   title(main = "Portpirie")
   gevglmprofxiPlot(fit, -0.3, 0.3)
   title(main = "Portpirie")
   
## Interactive Plot:
   ##> par(mfrow = c(2, 2))
   ##> plot(fit)
\end{ExampleCode}
\end{Examples}

