expansionTerms: Distance function expansion terms

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Distance function expansion terms

Description

Compute "expansion" terms that modify the shape of a base distance function.

Usage

expansionTerms(a, d, series, nexp, w)

Arguments

a	A vector or matrix of (estimated) coefficients. a has length p + nexp (if a vector) or dimension (k, p + nexp), where p is the number of canonical parameters in the likelihood and k is the number of 'cases' (coefficient vectors = nrow(a)) to evaluate. The first p elements of a, or the first p columns if a is a matrix, are ignored. I.e., Expansion term coefficients are the last nexp elements or columns of a.
d	A vector or 1-column matrix of distances at which to evaluate the expansion terms. d should be distances above w.lo, i.e., distances - w.lo. Parameters d and w must have compatible measurement units.
series	If expansions > 0, this string specifies the type of expansion to use. Valid values at present are 'simple', 'hermite', and 'cosine'.
nexp	Number of expansion terms. Integer from 0 to 5.
w	A vector specifying strip width for every 'case' in a. Vector must have length length(a) or nrow(a). In general, this is constant vector containing the range of sighting distances, i.e., rep(w.hi - w.low, nrow(a)). But, for some likelihoods (e.g., 'oneStep') this vector allows the user to restrict application of the expansion terms to less than the full range of distances. For the 'oneStep' likelihood, expansion terms are only applied between 0 and \Theta, the boundary of the two uniforms, which varies by 'case' when covariates are present. Parameters d and w must have compatible measurement units.

Details

Expansion terms modify the base likelihood function and are used to incorporate "wiggle". The modified distance function is, key * expTerms where key is a vector of values in the base likelihood function (e.g., halfnorm.like()$L.unscaled) and expTerms is the matrix returned by this routine. In equation form,

f(x_i|\beta,a_1,a_2,\dots,a_m) = f(x_i|\beta)(1 + \sum_{k=1}^{m} a_k h_{k}(x_i/w)).

, where m = the the number of expansions (nexp), h_{j}(x) are expansion terms for distance x, and a_1, a_2, \dots, a_m are the (estimated) expansion term coefficients.

Value

If nexp equals 0, 1 is returned. If nexp is greater than 0, a matrix of size nXk containing expansion terms, where n = length(d) and k = nrow(a). The expansion series associated with row j of a are in column j of the return. i.e., element (i,j) of the return is

1 + \sum_{k=1}^{m} a_{jk} h_{k}(x_{i}/w).

Examples

a1 <- c(log(40), 0.5, -.5)
a2 <- c(log(40), 0.25, -.5)
dists <- seq(0, 100, length = 100) %m%.
w = 100 %m%.

expTerms1 <- expansionTerms(a1, dists, "cosine", 2, w)
expTerms2 <- expansionTerms(a2, dists, "cosine", 2, w)
plot(dists, expTerms2, ylim = c(0,2.5))
points(dists, expTerms1, pch = 16)

# Same as above
a <- rbind(a1, a2)
w <- rep(w, nrow(a))
expTerms <- expansionTerms(a, dists, "cosine", 2, w)
matlines(dists, expTerms, lwd=2, col=c("red", "blue"), lty=1)

# Showing key and expansions
key <- halfnorm.like(log(40), dists, matrix(1,length(dists),1))$L.unscaled
plot(dists, key, type = "l", col = "blue", ylim=c(0,1.5))
lines(dists, key * expTerms1, col = "red")
lines(dists, key * expTerms2, col = "purple")

Rdistance documentation built on Jan. 10, 2026, 1:07 a.m.