integrateHalfnormLines: Integrate Half-normal line surveys

Description

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

Usage

integrateHalfnormLines(
  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} e^{-x^2/2\sigma_i^2} dx = \sqrt{2\pi}\sigma_i (\Phi(w) - 0.5),$$ where $w = w.hi - w.lo$, $\sigma_i$ is the estimated half-normal distance function parameter for the i-th observed distance, and $\Phi$ is the standard normal cumulative probability function. Rdistance uses R's base function pnorm(), which for all intents and purposes is exact.

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(3.5, -0.5)
w.hi <- 125
w.lo <- 20
ml <- list(
    mf = model.frame(d ~ obs)
  , par = beta 
  , likelihood = "halfnorm"
  , w.lo = w.lo %#% "m"
  , w.hi = w.hi %#% "m"
)
class(ml) <- "dfunc"
integrateHalfnormLines(ml)

# Check: Integral of exp(-x^2/(2*s^2)) from 0 to w.hi-w.lo
b <- exp(c(beta[1], beta[1] + beta[2]))
intgral <- (pnorm(w.hi, mean=w.lo, sd = b) - 0.5) * sqrt(2*pi)*b
intgral