integrateGammaLines: Integrate Gamma line surveys

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Integrate Gamma line surveys

Description

Compute integral of the Gamma distance function for line-transect surveys.

Usage

integrateGammaLines(
  object,
  newdata = NULL,
  w.lo = NULL,
  w.hi = NULL,
  Units = NULL
)

Arguments

object	Either an Rdistance fitted distance function (an object that inherits from class "dfunc"; usually produced by a call to dfuncEstim), or a matrix of canonical distance function parameters (e.g., matrix(exp(fit$par),1)). If a matrix, each row corresponds to a distance function and each column is a parameter. The first column is the parameter related to sighting covariates and must be transformed to the "real" space (i.e., inverse link, which is exp(), must be applied outside this routine). If object is a matrix, it should not have measurement units because only derived quantities (e.g., ESW) have units; Rdistance function parameters themselves never have units.
newdata	A data frame containing new values for the distance function covariates. If NULL and object is a fitted distance function, the observed covariates stored in object are used (behavior similar to predict.lm). Argument newdata is ignored if object is a matrix.
w.lo	Minimum sighting distance or left-truncation value if object is a matrix. Ignored if object is a fitted distance function. Must have physical measurement units.
w.hi	Maximum sighting distance or right-truncation value if object is a matrix. Ignored if object is a fitted distance function. Must have physical measurement units.
Units	Physical units of sighting distances if object is a matrix. Sighting distance units can differ from units of w.lo or w.hi. Ignored if object is a fitted distance function.

Details

#' Returned integrals are

\int_0^{w} \left(\frac{x}{m}\right)^{\alpha -1} e^{-(x - m)/\sigma_i}dx,

where w = w.hi - w.lo, \sigma_i is the i-th estimated scale parameter for the Gamma distance function, and m is the mode of Gamma (i.e., (\alpha - 1)\sigma_i. Rdistance computes the integral using R's base function pgamma(), which for all intents and purposes is exact. See also Gamma.like.

Value

A vector of areas under the distance functions represented in object. If object is a distance function and newdata is specified, the returned vector's length is nrow(newdata). If object is a distance function and newdata is NULL, returned vector's length is length(distances(object)). If object is a matrix, return's length is nrow(object).

Note

Users will not normally call this function. It is called internally by nLL and effectiveDistance.

See Also

integrateNumeric; integrateNegexpLines; integrateOneStepLines

Examples

# Fake distance function object w/ minimum inputs for integration
d <- rep(1,4) %m%. # Only units needed, not values
obs <- factor(rep(c("obs1", "obs2"), 2))
beta <- c(4.0, -0.5, 1.5) # {'Intercept', b_1, shape}
w.hi <- 125
w.lo <- 20
ml <- list(
    mf = model.frame(d ~ obs)
  , par = beta 
  , likelihood = "Gamma"
  , w.lo = w.lo %#% "m"
  , w.hi = w.hi %#% "m"
  , expansions = 0
)
class(ml) <- "dfunc"
integrateGammaLines(ml)

# Check: Integral of Gamma density from 0 to w.hi-w.lo
b <- exp(c(beta[1], beta[1] + beta[2]))
B <- Rdistance::GammaReparam(shp = beta[3], scl = b)
m <- (B$shp - 1)*B$scl
f.at.m <- dgamma(m, shape = B$shp, scale = B$scl)
intgral <- pgamma(q = w.hi - w.lo, shape = B$shp, scale = B$scl) / f.at.m
intgral

Rdistance documentation built on Jan. 10, 2026, 1:07 a.m.