circular: Circular Probability

In secr: Spatially Explicit Capture-Recapture

Circular Probability

Description

Functions to answer the question "what radius is expected to include proportion p of points from a circular bivariate distribution corresponding to a given detection function", and the reverse. These functions may be used to relate the scale parameter(s) of a detection function (e.g., \sigma) to home-range area (specifically, the area within an activity contour for the corresponding simple home-range model) (see Note).

WARNING: the default behaviour of these functions changed in version 2.6.0. Integration is now performed on the cumulative hazard (exposure) scale for all functions unless hazard = FALSE. Results will differ.

Usage

circular.r (p = 0.95, detectfn = 0, sigma = 1, detectpar = NULL, hazard
= TRUE, upper = Inf, ...) 

circular.p (r = 1, detectfn = 0, sigma = 1, detectpar = NULL, hazard
= TRUE, upper = Inf, ...) 

Arguments

p	vector of probability levels for which radius is required
r	vector of radii for which probability level is required
detectfn	integer code or character string for shape of detection function 0 = halfnormal, 2 = exponential etc. – see detectfn for other codes
sigma	spatial scale parameter of detection function
detectpar	named list of detection function parameters
hazard	logical; if TRUE the transformation -log(1-g(d)) is applied before integration
upper	numeric upper limit of integration
...	other arguments passed to integrate

Details

circular.r is the quantile function of the specified circular bivariate distribution (analogous to qnorm, for example). The quantity calculated by circular.r is sometimes called 'circular error probable' (see Note).

For detection functions with two parameters (intercept and scale) it is enough to provide sigma. Otherwise, detectpar should be a named list including parameter values for the requested detection function (g0 may be omitted, and order does not matter).

Detection functions in secr are expressed in terms of the decline in probability of detection with distance g(d), and both circular.r and circular.p integrate this function by default. Rather than integrating g(d) itself, it may be more appropriate to integrate g(d) transformed to a hazard i.e. 1 - log(-g(d)). This is selected with hazard = TRUE.

Integration may also fail with the message “roundoff error is detected in the extrapolation table”. Setting upper to a large number less than infinity sometimes corrects this.

Value

Vector of values for the required radii or probabilities.

Note

The term ‘circular error probable’ has a military origin. It is commonly used for GPS accuracy with the default probability level set to 0.5 (i.e. half of locations are further than CEP from the true location). A circular bivariate normal distriubution is commonly assumed for the circular error probable; this is equivalent to setting detectfn = "halfnormal".

Closed-form expressions are used for the normal and uniform cases; in the circular bivariate normal case, the relationship is r = \sigma \sqrt{-2\mbox{ln}(1-p)} . Otherwise, the probability is computed numerically by integrating the radial distribution. Numerical integration is not foolproof, so check suspicious or extreme values.

When circular.r is used with the default sigma = 1, the result may be interpreted as the factor by which sigma needs to be inflated to include the desired proportion of activity (e.g., 2.45 sigma for 95% of points from a circular bivariate normal distribution fitted on the hazard scale (detectfn = 14) OR 2.24 sigma on the probability scale (detectfn = 0)).

References

Calhoun, J. B. and Casby, J. U. (1958) Calculation of home range and density of small mammals. Public Health Monograph No. 55. United States Government Printing Office.

Johnson, R. A. and Wichern, D. W. (1982) Applied multivariate statistical analysis. Prentice-Hall, Englewood Cliffs, New Jersey, USA.

See Also

detectfn, detectfnplot

Examples

## Calhoun and Casby (1958) p 3.
## give p = 0.3940, 0.8645, 0.9888
circular.p(1:3, hazard = FALSE)

## halfnormal, hazard-rate and exponential
circular.r ()
circular.r (detectfn = "HR", detectpar = list(sigma = 1, z = 4))
circular.r (detectfn = "EX")
circular.r (detectfn = "HHN")
circular.r (detectfn = "HHR", detectpar = list(sigma = 1, z = 4))
circular.r (detectfn = "HEX")

plot(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05)),
    type = "l", xlab = "Radius (multiples of sigma)", ylab = "Probability")
lines(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05), detectfn = 2),
    type = "l", col = "red")
lines(seq(0, 5, 0.05), circular.p(r = seq(0, 5, 0.05), detectfn = 1,
    detectpar = list(sigma = 1,z = 4)), type = "l", col = "blue")
abline (h = 0.95, lty = 2)

legend (2.8, 0.3, legend = c("halfnormal","hazard-rate, z = 4", "exponential"),
    col = c("black","blue","red"), lty = rep(1,3))

## in this example, a more interesting comparison would use
## sigma = 0.58 for the exponential curve.

secr documentation built on Oct. 18, 2023, 1:07 a.m.