integrateHazrateLines: Integrate Hazard-rate line survey distance functions

Description

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

Usage

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

Value

A vector of areas under distance functions. 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(fit$par,1)). If a matrix, each row corresponds to a distance function and each column is a parameter. If object is a matrix, it should not have measurement units. Only quantities derived from function parameters (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} (1 - e^{-(x/\sigma_i)^{-k}}) dx = w - \frac{\sigma_i}{k} \Gamma(-\frac{1}{k}, {\frac{\sigma_i}{w}}^{k}),$$ where $w = w.hi - w.lo$, $\sigma_i$ and $k$ are estimated hazard-rate distance function parameters for the i-th observed distance, and $\Gamma()$ is the incomplete gamma function. Rdistance uses the incomplete gamma function implemented in gammainc, which for all intents and purposes is exact.

Examples

Run this code


# A pre-estimated hazard rate distance function: sparrowDfuncObserver
fit <- sparrowDfuncObserver
table(ESW(fit))
table(integrateHazrateLines(fit))

# Check: Integral of 1 - exp(-(x/s)^(-k)) from 0 to w.hi-w.lo
w <- dropUnits(fit$w.hi - fit$w.lo)
params <- predict(fit)
sigma <- params[,1]
minusk <- -params[,2]

outArea <- w + sigma * 
           expint::gammainc(1/minusk, (w/sigma)^(minusk)) / minusk
table(outArea)