Gamma.like: Gamma distance function
In Rdistance: Density and Abundance from Distance-Sampling Surveys

Gamma.like

R Documentation

Gamma distance function

Description

Evaluate the gamma distance function for sighting distances, potentially including covariates and expansion terms

Usage

Gamma.like(a, dist, covars, w.hi = NULL)

Arguments

`a`	A vector or matrix of covariate and expansion term coefficients. If matrix, dimension is k X p, where k = `nrow(a)`) is the number of coefficient vectors to evaluate (cases) and p = `ncol(a)`) is the number of covariate and expansion coefficients in the likelihood (i.e., rows are cases and columns are covariates). If `a` is a dimensionless vector, it is interpreted as a single row with k = 1. Covariate coefficients in `a` are the first q values (q <= p), and must be on a log scale.
`dist`	A numeric vector of length n or a single-column matrix (dimension nX1) containing detection distances at which to evaluate the likelihood.
`covars`	A numeric vector of length q or a matrix of dimension nXq containing covariate values associated with distances in argument `dist`.
`w.hi`	A numeric scalar containing maximum distance. The right-hand cutoff or upper limit. Ignored by some likelihoods (such as halfnorm, negexp, and hazrate), but is a fixed parameter in other likelihoods (such as oneStep and uniform).

Details

The Rdistance implementation of a Gamma distance function follows Becker and Quang (2009). Rdistance's Gamma distance function is

f(d|\alpha, \sigma) = \left(\frac{d}{m}\right)^{\alpha - 1}e^{-(d-m)/\sigma},

where \alpha is the shape parameter, \sigma is the scale parameter, and m = (\alpha-1)\sigma. m is the mode of the Gamma function, and in Rdistance it's scaled to have a maximum of 1.0 at m. The scale parameter is a function of the shape parameter and sighting covariates, i.e.,

\sigma = k [exp(x'\beta)],

where x is a vector of covariate values associated with distance d (i.e., a row of covars), \beta is a vector of the first q (=ncol(covars)) values of the first argument of the function (a), and k is a function of the shape parameter, i.e.,

k = \frac{1}{\Gamma(\alpha)} \left(\frac{a - 1}{e^1} \right)^{a - 1}.

The shape parameter \alpha is the q+1-st value in the function's first argument and is constrained to be strictly greater than 1.0.

See Examples for use of GammaReparam to compute \alpha and \sigma from fitted object coefficients.

Value

A list containing the following two components:

L.unscaled: A matrix of size nXk (n = length dist; k = number of cases = nrow(a)) containing likelihood values evaluated at distances in dist. Each row is associated with a single distance, and each column is associated with a single case (row of a). Values in this matrix are the distance function g(d) which generally have g(0) = 1. These values are "unscaled" likelihood values; they must be scaled (divided by) with the area under g(x) between w.lo and w.hi to form proper likelihood values.
params: A nXbXk array of the likelihood's (canonical) parameters in link space (i.e., on log scale; b = number of canonical parameters in the likelihood; k = number of cases). Rows correspond to distances in dist. Columns correspond to parameters (columns of a), and pages correspond to cases (rows of a).

References

Becker, E. F., and P. X. Quang, 2009. A Gamma-Shaped Detection Function for Line-Transect Surveys with Mark-Recapture and Covariate Data. Journal of Agricultural, Biological, and Environmental Statistics 14(2):207-223.

Examples

x <- seq(0, 100, length=100)
covars <- matrix(1,100,1)

# Plots showing changes in scale
plot(x, Gamma.like(c(log(20),2.5), x, covars)$L.unscaled, type="l", col="red")
lines(x, Gamma.like(c(log(40),2.5), x, covars)$L.unscaled, col="blue")

# Plots showing changes in shape
plot(x, Gamma.like(c(log(20),1.5), x, covars)$L.unscaled, type="l", col="red")
lines(x, Gamma.like(c(log(20),2.5), x, covars)$L.unscaled, col="blue")
lines(x, Gamma.like(c(log(20),4.5), x, covars)$L.unscaled, col="green")

# Roll-your-own plot, showing "re-parameterization":
# Assume fitted object coefficients are c(log(20), 4.5)
fit <- list(par = c(log(20), 4.5))

# The distance function is then,
gammaPar <- GammaReparam( scl = exp(fit$par[1])
                        , shp = fit$par[2] ) # returns scl=k*exp(x'B)
scl <- gammaPar$scl
shp <- gammaPar$shp
m <- (shp - 1) * scl
g <- (x / m)^(shp - 1) * exp(-(x - m) / scl) # distance function
lines(x, g, lwd = 3, lty = 2, col="green3")

Rdistance documentation built on April 23, 2026, 1:06 a.m.