% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/glme.gev.R
\name{glme.gev}
\alias{glme.gev}
\title{Generalized L-moments estimation for generalized extreme value distribution}
\usage{
glme.gev(
  xdat,
  ntry = 5,
  pen = "beta",
  pen.choice = 1,
  mu = -0.5,
  std = 0.2,
  p = 6,
  c1 = 3,
  c2 = 1,
  c0 = 0.35,
  q = NULL,
  show = FALSE,
  method = "BFGS",
  maxit = 70,
  abstol = 1e-05
)
}
\arguments{
\item{xdat}{A numeric vector of data to be fitted.}

\item{ntry}{Number of attempts for parameter estimation (default 5). Higher
values increase the chance of finding the global optimum by trying
different initial conditions.}

\item{pen}{Type of penalty function: Choose among "norm", "beta" (default),
"ms", "park", "cannon", "cd", and "no" (without penalty function).}

\item{pen.choice}{Choice number of penalty function specifying hyperparameters
(default 1). For "beta": 1-6 correspond to (p, c1, c2) =
(6,3,1), (6,5,2), (6,7,3), (2,3,0.5), (2,5,1), (2,7,1.5).
For "norm": 1-4 correspond to (mu, std) =
(-0.5,0.25), (-0.5,0.15), (-0.6,0.25), (-0.6,0.15).
Set \code{pen.choice=NULL} to use the hyperparameters given by
\code{p, c1, c2} (beta) or \code{mu, std} (norm) directly.}

\item{mu}{Mean hyperparameter for "norm" penalty function (default -0.5).}

\item{std}{Standard deviation hyperparameter for "norm" penalty function (default 0.2).}

\item{p}{Shape hyperparameter for "beta" penalty function (default 6).}

\item{c1}{Scaling hyperparameter for "beta" penalty function (default 3).}

\item{c2}{Upper limit hyperparameter for "beta" penalty function (default 1).}

\item{c0}{Half-width of the adaptive beta penalty support (default 0.35).}

\item{q}{Optional fixed second shape parameter for the beta penalty. If
given, the beta penalty support is fixed instead of data-adaptive.}

\item{show}{If TRUE, prints the objective value and parameters of each try.}

\item{method}{Optimization method passed to \code{\link[stats]{optim}}
(default "BFGS").}

\item{maxit}{Maximum number of iterations for \code{optim} (default 70).}

\item{abstol}{Absolute and relative convergence tolerance for \code{optim}
(default 1e-5).}
}
\value{
The glme.gev function returns a list containing the following elements:
\itemize{
 \item para.glme - The estimated parameters of the Generalized Extreme Value distribution.
 \item para.lme - The L-moment estimates of the parameters.
 \item nllh.glme - The penalized negative log-likelihood of the GLME solution.
 \item convergence - 0 if the optimization converged, 5 otherwise.
 \item pen, pen_pen.choice - The penalization method (and choice) used.
 \item p_q - (for beta penalty) The p and q values used.
 \item c1_c2, c0_c1_c2 - (for beta penalty) The hyperparameters used.
 \item mu_std - (for norm penalty) The mu and std values used.
 \item covinv.lmom - The inverse of the covariance matrix of the L-moments.
 \item lcovdet - The log determinant of the covariance matrix.
 \item data - The input data (used by the plot method).
}
The object has class \code{"glme"}; see \code{\link{GLmom-methods}}.
}
\description{
This function estimates the parameters of the Generalized Extreme Value
distribution by the generalized method of L-moment estimation (GLME),
which minimizes the generalized L-moment distance plus a penalty
(preference) function on the shape parameter.
}
\details{
The equations for the L-moments for LME of the GEVD are
\deqn{ \underline{\bf \lambda} - \underline{\bf l} = \underline{\bf 0},}
where \eqn{ \underline{\bf \lambda} =(\lambda_1,\; \lambda_2,\; \lambda_3)^t } and \eqn{\underline{\bf l} =(l_1,\; l_2,\; l_3)^t}.
Next, we define the generalized L-moments distance (GLD) as;
\deqn{(\underline{\bf \lambda} -\underline{\bf l})^t V^{-1} (\underline{\bf \lambda} -\underline{\bf l}),}
where \eqn{V} is the variance-covariance matrix of the sample L-moments up to the third order.
}
\examples{
# Load example heavy-rainfall data
data(haenam)
x <- haenam$X1

# Estimate GEV parameters using beta penalty (default)
result <- glme.gev(x, ntry = 5)
print(result$para.glme)

# Using Martins-Stedinger penalty
result_ms <- glme.gev(x, ntry = 5, pen = "ms")
print(result_ms$para.glme)

}
\references{
Shin, Y., Shin, Y., Park, J. & Park, J.-S. (2025). Generalized method of
L-moment estimation for stationary and nonstationary extreme value models.
arXiv preprint arXiv:2512.20385. \doi{10.48550/arXiv.2512.20385}
}
\seealso{
\code{\link{glme.gev11}} for non-stationary GEV estimation,
  \code{\link{ma.gev}} for model averaging estimation,
  \code{\link{glme.like}} for the objective function,
  \code{\link{quagev.NS}} for quantile computation.
}
\author{
Yonggwan Shin, Seokkap Ko, Jihong Park, Yire Shin, Jeong-Soo Park
}
