% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/0-base-distributions.R
\name{InvGauss}
\alias{InvGauss}
\alias{dInvGauss}
\alias{pInvGauss}
\alias{rInvGauss}
\alias{qInvGauss}
\title{Inverse Gaussian (Wald) distribution}
\usage{
dInvGauss(x, mean, shape, log = 0)

pInvGauss(q, mean, shape, lower.tail = 1, log.p = 0)

rInvGauss(n, mean, shape)

qInvGauss(
  p,
  mean,
  shape,
  lower.tail = TRUE,
  log.p = FALSE,
  tol = 1e-10,
  maxiter = 200
)
}
\arguments{
\item{x}{Numeric scalar giving the point at which the density is evaluated.}

\item{mean}{Numeric scalar mean parameter \eqn{\mu>0}.}

\item{shape}{Numeric scalar shape parameter \eqn{\lambda>0}.}

\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 giving the probability for the quantile.}

\item{tol}{Numeric scalar tolerance passed to \code{stats::uniroot}.}

\item{maxiter}{Integer maximum number of iterations for \code{stats::uniroot}.}
}
\value{
\code{dInvGauss()} returns a numeric scalar density, \code{pInvGauss()} returns a numeric scalar
CDF, \code{rInvGauss()} returns one random draw, and \code{qInvGauss()} returns a numeric quantile.
}
\description{
Scalar inverse Gaussian utilities under the \eqn{(\mu, \lambda)} parameterization, where
\code{mean = mu > 0} and \code{shape = lambda > 0}. These functions are used directly and as building
blocks for inverse-Gaussian mixtures and spliced inverse-Gaussian-plus-GPD families.
}
\details{
The density is
\deqn{
f(x) = \left(\frac{\lambda}{2 \pi x^3}\right)^{1/2}
\exp\left\{- \frac{\lambda (x - \mu)^2}{2 \mu^2 x}\right\}, \qquad x > 0.
}

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 inverse Gaussian is the first-passage-time distribution of a Brownian motion with positive
drift. Under the \eqn{(\mu, \lambda)} parameterization used here, the mean is \eqn{E(X)=\mu} and
the variance is \eqn{\mathrm{Var}(X)=\mu^3/\lambda}. The implementation follows that
parameterization throughout the package, so inverse-Gaussian mixture and splice families inherit
the same interpretation.

The distribution function is evaluated through the standard normal representation
\deqn{
F(x) =
\Phi\left(\sqrt{\frac{\lambda}{x}}\left(\frac{x}{\mu}-1\right)\right) +
\exp\left(\frac{2\lambda}{\mu}\right)
\Phi\left(-\sqrt{\frac{\lambda}{x}}\left(\frac{x}{\mu}+1\right)\right),
}
and the quantile is obtained numerically because no simple closed form is available.
}
\section{Functions}{
\itemize{
\item \code{dInvGauss()}: Inverse Gaussian density function

\item \code{pInvGauss()}: Inverse Gaussian distribution function

\item \code{rInvGauss()}: Inverse Gaussian random generation

\item \code{qInvGauss()}: Inverse Gaussian quantile function

}}
\examples{
mean <- 2
shape <- 5

dInvGauss(2.0, mean, shape, log = 0)
pInvGauss(2.0, mean, shape, lower.tail = 1, log.p = 0)
qInvGauss(0.50, mean, shape)
qInvGauss(0.95, mean, shape)
replicate(10, rInvGauss(1, mean, shape))

}
\seealso{
\code{\link[=InvGauss_mix]{InvGauss_mix()}}, \code{\link[=InvGauss_gpd]{InvGauss_gpd()}}, \code{\link[=base_lowercase]{base_lowercase()}}, \code{\link[=build_nimble_bundle]{build_nimble_bundle()}}.

Other base bulk distributions: 
\code{\link{amoroso}},
\code{\link{cauchy}}
}
\concept{base bulk distributions}
