Skip to contents

Probability of detection under the ellipsoidal niche model

Source: R/probability_detection.R
probability_detection.Rd

Per-point probability of detecting an occurrence, ported from the xsdm detection kernel (xsdm::log_prob_detect) to the symmetric ellipsoidal niche used by arfun/nicherbayes: the suitability surface is the Mahalanobis kernel of the niche ellipse, passed through a softplus detection link.

Usage

probability_detection(env, mu, sigma, rho = 0, ctil = 0, pd = 1)

Arguments

env

Numeric matrix or data.frame of environmental values, \(n \times p\) (rows = points, columns = variables).

mu

Numeric vector of length \(p\): niche optimum (ellipse centre).

sigma

Either a \(p \times p\) covariance matrix Sigma, or a numeric vector of length \(p\) of per-axis standard deviations (then combined with rho).

rho

Scalar correlation in \((-1, 1)\); used only when sigma is a vector. Default 0.

ctil

Scalar detection-link offset: larger values push the detection curve toward zero everywhere (harder to detect). Default 0.

pd

Maximum detection probability in \((0, 1]\) at the niche optimum. Default 1.

Value

Numeric vector of length nrow(env): detection probabilities.

Details

The detection probability is $$p(x) = \mathrm{pd} \, / \, (1 + \exp(\mathrm{ctil} + h(x)))$$ with \(h(x) = \tfrac12 (x-\mu)^\top \Sigma^{-1} (x-\mu)\), the half-squared Mahalanobis distance. This matches the xsdm kernel log p = log pd - log1pexp(ctil + h) with symmetric widths. As ctil -> -Inf the surface flattens toward pd everywhere; in the regime ctil + h >> 0 (large offset or far from the centroid), \(p \approx \mathrm{pd}\,\exp(-\mathrm{ctil}-h)\), i.e. proportional to the J&S suitability \(\exp(-h)\).

See also

[virtual_species_occurrences()] to sample occurrences from this surface.

Examples

env <- expand.grid(x = seq(-3, 3, 0.5), y = seq(-3, 3, 0.5))
probability_detection(as.matrix(env), mu = c(0, 0),
                      sigma = c(1, 1.5), rho = 0.5, ctil = 2, pd = 0.9)
#>   [1] 1.143915e-03 3.663124e-03 8.384363e-03 1.374044e-02 1.618759e-02
#>   [6] 1.374044e-02 8.384363e-03 3.663124e-03 1.143915e-03 2.554941e-04
#>  [11] 4.085808e-05 4.680843e-06 3.842288e-07 1.326311e-03 4.741586e-03
#>  [16] 1.209233e-02 2.203047e-02 2.885829e-02 2.734616e-02 1.871874e-02
#>  [21] 9.189465e-03 3.219357e-03 8.049151e-04 1.439188e-04 1.842730e-05
#>  [26] 1.690396e-06 1.326311e-03 5.295534e-03 1.505117e-02 3.045112e-02
#>  [31] 4.421467e-02 4.660974e-02 3.575435e-02 1.976461e-02 7.790926e-03
#>  [36] 2.184629e-03 4.370444e-04 6.255252e-05 6.412768e-06 1.143915e-03
#>  [41] 5.104083e-03 1.618759e-02 3.639561e-02 5.847225e-02 6.827236e-02
#>  [46] 5.847225e-02 3.639561e-02 1.618759e-02 5.104083e-03 1.143915e-03
#>  [51] 1.830843e-04 2.097770e-05 8.508546e-04 4.245310e-03 1.505117e-02
#>  [56] 3.771133e-02 6.711311e-02 8.653603e-02 8.228715e-02 5.746790e-02
#>  [61] 2.885829e-02 1.025709e-02 2.579698e-03 4.619989e-04 5.917237e-05
#>  [66] 5.457364e-04 3.045970e-03 1.209233e-02 3.389493e-02 6.711311e-02
#>  [71] 9.562514e-02 1.004781e-01 7.822682e-02 4.421467e-02 1.772709e-02
#>  [76] 5.010954e-03 1.004994e-03 1.439188e-04 3.018151e-04 1.884443e-03
#>  [81] 8.384363e-03 2.638101e-02 5.847225e-02 9.250562e-02 1.072826e-01
#>  [86] 9.250562e-02 5.847225e-02 2.638101e-02 8.384363e-03 1.884443e-03
#>  [91] 3.018151e-04 1.439188e-04 1.004994e-03 5.010954e-03 1.772709e-02
#>  [96] 4.421467e-02 7.822682e-02 1.004781e-01 9.562514e-02 6.711311e-02
#> [101] 3.389493e-02 1.209233e-02 3.045970e-03 5.457364e-04 5.917237e-05
#> [106] 4.619989e-04 2.579698e-03 1.025709e-02 2.885829e-02 5.746790e-02
#> [111] 8.228715e-02 8.653603e-02 6.711311e-02 3.771133e-02 1.505117e-02
#> [116] 4.245310e-03 8.508546e-04 2.097770e-05 1.830843e-04 1.143915e-03
#> [121] 5.104083e-03 1.618759e-02 3.639561e-02 5.847225e-02 6.827236e-02
#> [126] 5.847225e-02 3.639561e-02 1.618759e-02 5.104083e-03 1.143915e-03
#> [131] 6.412768e-06 6.255252e-05 4.370444e-04 2.184629e-03 7.790926e-03
#> [136] 1.976461e-02 3.575435e-02 4.660974e-02 4.421467e-02 3.045112e-02
#> [141] 1.505117e-02 5.295534e-03 1.326311e-03 1.690396e-06 1.842730e-05
#> [146] 1.439188e-04 8.049151e-04 3.219357e-03 9.189465e-03 1.871874e-02
#> [151] 2.734616e-02 2.885829e-02 2.203047e-02 1.209233e-02 4.741586e-03
#> [156] 1.326311e-03 3.842288e-07 4.680843e-06 4.085808e-05 2.554941e-04
#> [161] 1.143915e-03 3.663124e-03 8.384363e-03 1.374044e-02 1.618759e-02
#> [166] 1.374044e-02 8.384363e-03 3.663124e-03 1.143915e-03