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 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). This matrix is "unscaled" because the underlying likelihood does not integrate to one. Values in L.unscaled are always greater than or equal to zero.
params: A nXkXb array of the likelihood's (canonical) parameters in link space (i.e., on log scale). First page contains parameter values related to covariates (i.e., s = exp(x'a)), while subsequent pages contain other parameters. b = 1 for halfnorm, negexp; b = 2 for hazrate, oneStep, Gamma, and others. Rows correspond to distances in dist. Columns correspond to rows from argument 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 Jan. 10, 2026, 1:07 a.m.