% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/0-base-distributions.R
\name{gpd}
\alias{gpd}
\alias{dGpd}
\alias{pGpd}
\alias{rGpd}
\alias{qGpd}
\title{Generalized Pareto distribution}
\usage{
dGpd(x, threshold, scale, shape, log = 0)

pGpd(q, threshold, scale, shape, lower.tail = 1, log.p = 0)

rGpd(n, threshold, scale, shape)

qGpd(p, threshold, scale, shape, lower.tail = TRUE, log.p = FALSE)
}
\arguments{
\item{x}{Numeric scalar giving the point at which the density is evaluated.}

\item{threshold}{Numeric scalar threshold at which the GPD is attached.}

\item{scale}{Numeric scalar GPD scale parameter; must be positive.}

\item{shape}{Numeric scalar GPD shape parameter.}

\item{log}{Logical; if \code{TRUE}, return the log-density (integer flag \code{0/1} in NIMBLE).}

\item{q}{Numeric scalar giving the point at which the distribution function is evaluated.}

\item{lower.tail}{Logical; if \code{TRUE} (default), probabilities are \eqn{P(X \le q)}.}

\item{log.p}{Logical; if \code{TRUE}, probabilities are returned on the log scale.}

\item{n}{Integer giving the number of draws. For portability inside NIMBLE,
the RNG implementation supports \code{n = 1}.}

\item{p}{Numeric scalar probability in \eqn{(0,1)} for the quantile function.}
}
\value{
\code{dGpd()} returns a numeric scalar density, \code{pGpd()} returns a numeric scalar CDF,
\code{rGpd()} returns one random draw, and \code{qGpd()} returns a numeric quantile.
}
\description{
Scalar generalized Pareto distribution (GPD) utilities for threshold exceedances above
\code{threshold}. These NIMBLE-compatible functions provide the tail component used by the spliced
bulk-tail families elsewhere in the package.
}
\details{
The parameterization is
\deqn{
G(x) = 1 - \left(1 + \xi \frac{x - u}{\sigma_u}\right)^{-1 / \xi}, \qquad x \ge u,
}
where \code{threshold = u}, \code{scale = sigma_u > 0}, and \code{shape = xi}. When \code{shape} approaches zero,
the distribution reduces to the exponential tail limit.

These uppercase NIMBLE-compatible functions are scalar (\code{x}/\code{q} and \code{n = 1}).
For vectorized R usage, use \code{\link[=base_lowercase]{base_lowercase()}}.

The associated density is
\deqn{
g(x) = \frac{1}{\sigma_u}
\left(1 + \xi \frac{x - u}{\sigma_u}\right)^{-1/\xi - 1},
}
on the support where \eqn{1 + \xi (x-u)/\sigma_u > 0}. When \eqn{\xi = 0}, this reduces to the
exponential density with mean excess \eqn{\sigma_u}. The GPD has finite mean only when
\eqn{\xi < 1}, and finite variance only when \eqn{\xi < 1/2}. Those existence conditions matter
for downstream predictive means in the package: spliced models with \eqn{\xi \ge 1} require
restricted means rather than ordinary means.

If a bulk distribution has CDF \eqn{F_{bulk}}, the package's spliced families use the tail construction
\deqn{
F(x) =
\left\{
\begin{array}{ll}
F_{bulk}(x), & x < u, \\
F_{bulk}(u) + \{1 - F_{bulk}(u)\} G(x), & x \ge u.
\end{array}
\right.
}
}
\section{Functions}{
\itemize{
\item \code{dGpd()}: Generalized Pareto density function

\item \code{pGpd()}: Generalized Pareto distribution function

\item \code{rGpd()}: Generalized Pareto random generation

\item \code{qGpd()}: Generalized Pareto quantile function

}}
\examples{
threshold <- 1
tail_scale <- 0.8
tail_shape <- 0.2

dGpd(1.5, threshold, tail_scale, tail_shape, log = 0)
pGpd(1.5, threshold, tail_scale, tail_shape, lower.tail = 1, log.p = 0)
qGpd(0.50, threshold, tail_scale, tail_shape)
qGpd(0.95, threshold, tail_scale, tail_shape)
replicate(10, rGpd(1, threshold, tail_scale, tail_shape))
}
\seealso{
\code{\link[=base_lowercase]{base_lowercase()}}, \code{\link[=normal_gpd]{normal_gpd()}}, \code{\link[=lognormal_gpd]{lognormal_gpd()}}, \code{\link[=gamma_gpd]{gamma_gpd()}},
\code{\link[=InvGauss_gpd]{InvGauss_gpd()}}, \code{\link[=laplace_gpd]{laplace_gpd()}}, \code{\link[=amoroso_gpd]{amoroso_gpd()}}.
}
\concept{base tail distributions}
