halfnorm.like: Half-normal likelihood function for distance analyses

Description

This function computes the likelihood contributions for sighting distances, scaled appropriately, for use as a distance likelihood.

Usage

halfnorm.like(
  a,
  dist,
  covars = NULL,
  w.lo = units::set_units(0, "m"),
  w.hi = max(dist),
  series = "cosine",
  expansions = 0,
  scale = TRUE,
  pointSurvey = FALSE
)

Value

A numeric vector the same length and order as dist containing the likelihood contribution for corresponding distances in dist. Assuming L is the returned vector from one of these functions, the negative log likelihood of all the data is -sum(log(L), na.rm=T). Note that the returned likelihood value for distances less than w.lo or greater than w.hi is NA, hence na.rm=TRUE in the sum. If scale = TRUE, the integral of the likelihood from

w.lo to w.hi is 1.0. If scale = FALSE, the integral of the likelihood is something else. Values are always greater than or equal to zero.

Arguments

a: A vector of likelihood parameter values. Length and meaning depend on series and expansions. If no expansion terms were called for (i.e., expansions = 0), the distance likelihoods contain one or two canonical parameters (see Details). If one or more expansions are called for, coefficients for the expansion terms follow coefficients for the canonical parameters. i.e., if p is the number of canonical parameters, coefficients for the expansion terms are a[(p+1):length(a)].
dist: A numeric vector containing the observed distances.
covars: Data frame containing values of covariates at each observation in dist.
w.lo: Scalar value of the lowest observable distance. This is the left truncation of sighting distances in dist. Same units as dist. Values less than w.lo are allowed in dist, but are ignored and their contribution to the likelihood is set to NA in the output.
w.hi: Scalar value of the largest observable distance. This is the right truncation of sighting distances in dist. Same units as dist. Values greater than w.hi are allowed in dist, but are ignored and their contribution to the likelihood is set to NA in the output.
series: A string specifying the type of expansion to use. Currently, valid values are 'simple', 'hermite', and 'cosine'; but, see dfuncEstim about defining other series.
expansions: A scalar specifying the number of terms in series. Depending on the series, this could be 0 through 5. The default of 0 equates to no expansion terms of any type.
scale: Logical scalar indicating whether or not to scale the likelihood so it integrates to 1. This parameter is used to stop recursion in other functions. If scale equals TRUE, a numerical integration routine (integration.constant) is called, which in turn calls this likelihood function again with scale = FALSE. Thus, this routine knows when its values are being used to compute the likelihood and when its value is being used to compute the constant of integration. All user defined likelihoods must have and use this parameter.
pointSurvey: Boolean. TRUE if distances in dist are radial from point transects, FALSE if distances are perpendicular off-transect distances.

Details

The half-normal likelihood is $$f(x|a) = \exp(-x^2 / (2*a^2))$$ where $a$ is the parameter to be estimated. Some half-normal distance functions in the literature do not use a "2" in the denominator of the exponent. Rdistance uses a "2" in the denominator of the exponent to make quantiles of this function agree with the standard normal which means a can be interpreted as a normal standard error. e.g., approximately 95% of all observations will occur between 0 and 2a.

Expansion Terms: If expansions = k (k > 0), the expansion function specified by series is called (see for example cosine.expansion). Assuming $h_{ij}(x)$ is the $j^{th}$ expansion term for the $i^{th}$ distance and that $c_1, c_2, \dots, c_k$are (estimated) coefficients for the expansion terms, the likelihood contribution for the $i^{th}$ distance is, $$f(x|a,b,c_1,c_2,\dots,c_k) = f(x|a,b)(1 + \sum_{j=1}^{k} c_j h_{ij}(x)).$$ f(x|a,b,c_1,c_2,...,c_k) = f(x|a,b)(1 + c(1) h_i1(x) + c(2) h_i2(x) + ... + c(k) h_ik(x)).

Examples

Run this code

 if (FALSE) {
set.seed(238642)
x <- seq(0, 100, length=100)

# Plots showing effects of changes in parameter Sigma
plot(x, halfnorm.like(20, x), type="l", col="red")
plot(x, halfnorm.like(40, x), type="l", col="blue")

# Estimate 'halfnorm' distance function
a <- 5
x <- rnorm(1000, mean=0, sd=a)
x <- x[x >= 0]
dfunc <- dfuncEstim(x~1, likelihood="halfnorm")
plot(dfunc)

# evaluate the log Likelihood
L <- halfnorm.like(dfunc$parameters, dfunc$detections$dist, covars=dfunc$covars, 
    w.lo=dfunc$w.lo, w.hi=dfunc$w.hi, 
    series=dfunc$series, expansions=dfunc$expansions, 
    scale=TRUE)
-sum(log(L), na.rm=TRUE)  # the negative log likelihood
}