integrateGammaLines: 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
)

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).

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.

Examples

Run this code


# 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