halfnorm.like: Half-normal distance function

Description

Evaluate the half-normal distance function, for sighting distances, potentially including covariates and expansion terms

Usage

halfnorm.like(a, dist, covars, w.hi = NULL)

Value

A list containing the following two components:

L.unscaled: A matrix of size nXkXb 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. 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 and others. Rows correspond to distances in dist. Columns correspond to rows from argument a.

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, heber, and uniform).

Details

The half-normal distance function is $$f(d|s) = \exp(-d^2 / (2*s^2))$$ where $s = exp(x'a)$, $x$ is a vector of covariate values associated with distance $d$ (i.e., a row of covars), and $a$ is a vector of the first $q$ (=ncol(covars)) values in argument a.

Some authors parameterize the halfnorm without the "2" in the denominator of the exponent. Rdistance includes "2" in this denominator to make quantiles of the half normal agree with the standard normal. This means that half-normal coefficients in Rdistance (i.e., s = exp(x'a)) can be interpreted as normal standard errors. Approximately 95% of distances should occur between 0 and 2s.

Examples

Run this code

 
d <- seq(0, 100, length=100)
covs <- matrix(1,length(d),1)
halfnorm.like(log(20), d, covs)

plot(d, halfnorm.like(log(20), d, covs)$L.unscaled, type="l", col="red")
lines(d, halfnorm.like(log(40), d, covs)$L.unscaled, col="blue")

# Evaluate 3 functions at once using matrix of coefficients:
# sigma ~ 20, 30, 40
coefs <- matrix(log(c(7.39,7.33, 4.48,44.80, 2.72,216.54))
               , byrow = TRUE
               , ncol=2) # (3 coef vectors)X(2 covars)
covs <- matrix(c(rep(1,length(d))
               , rep(0.5,length(d)))
               , nrow = length(d)) # 100 X 2
L <- halfnorm.like( coefs, d, covs ) 
L$L.unscaled # 100 X (3 coef vectors)
L$params     # 100 X (3 coef vectors); ~ log(c(20,30,40))
matplot(d, L$L.unscaled, type="l")