logistic.like: logistic.like - Logistic distance function likelihood
In Rdistance: Distance-Sampling Analyses for Density and Abundance Estimation

logistic.like

R Documentation

logistic.like - Logistic distance function likelihood

Description

Computes a two parameter logistic distance function.

Usage

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

Arguments

`a`	A vector of likelihood parameter values. Length and meaning depend on whether covariates and `expansions` are present as follows: If no covariates and no expansions: `a` = [a, b] (see Details) If no covariates and k expansions: `a` = [a, b, e1, ..., ek] If p covariates and no expansions: `a` = [a, b, b1, ..., bp] If p covariates and k expansions: `a` = [a, b, b1, ..., bp, e1, ..., ek]
`dist`	A numeric vector containing observed distances with measurement units.
`covars`	Data frame containing values of covariates at each observation in `dist`.
`w.lo`	Scalar value of the lowest observable distance, with measurement units. This is the left truncation sighting distance. Values less than `w.lo` are allowed in `dist`, but are ignored and their likelihood value is set to `NA` in the output.
`w.hi`	Scalar value of the largest observable distance, with measurement units. This is the right truncation sighting distance. Values greater than `w.hi` are allowed in `dist`, but are ignored and their likelihood value 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 into a density function, i.e., so that 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 values are being used to compute the constant of integration. All user defined likelihoods must have and use this parameter.
`pointSurvey`	Boolean. TRUE if `dist` is point transect data, FALSE if line transect data.

Details

The 'logistic' likelihood contains two parameters. Parameter a determines the scale and is labeled 'threshold' in Rdistance. Parameter b determines sharpness (slope) of the likelihood's decrease at a and is labeled 'knee' in Rdistance. This function is sometimes called the heavy side function (e.g., engineering). The technical form of the function is,

f(x|a,b) = 1 - \frac{1}{1 + \exp(-b(x-a))} = \frac{\exp( -b(x-a) )}{1 + exp( -b(x-a) )},

Parameter a is the location (distance) of 0.5. That is, the inverse likelihood of 0.5 is a before scaling (i.e., logistic.like( c(a,b), a, scale=FALSE) equals 0.5).

Parameter b is slope of function at a. Prior to scaling, slope of the likelihood at a is -b/4. If b is large, the "knee" is sharp and the likelihood can look uniform with support from w.lo to a/f(0). If b is small, the "knee" is shallow and the density of observations declines in an elongated "S" shape pivoting at a/f(0). As b grows large and assuming f(0) = 1, the effective strip width approaches a.

See plots in Examples.

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, the log likelihood of all 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, and thus it is essential to use 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 arbitrary.

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, 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)).

Examples

x <- units::set_units(seq(0, 100, length=100), "m")

# Plots showing effects of changes in Threshold
plot(x, logistic.like(c(20, 20), x), type="l", col="red")
lines(x, logistic.like(c(40, 20), x), type="l", col="blue")

# Plots showing effects of changes in Knee
plot(x, logistic.like(c(50, 100), x), type="l", col="red")
lines(x, logistic.like(c(50, 1), x), type="l", col="blue")
lines(x, logistic.like(c(50, .1), x), type="l", col="orange")

Rdistance documentation built on July 9, 2023, 6:46 p.m.