Generate a virtual species probability map with presence/absence sampling

Creates a virtual species probability-of-detection map based on environmental time-series data and a set of species-specific parameters, then samples presence/absence points based on a user-defined probability threshold.

Usage

vsp(param_list, env_data, size_presence, size_absence, threshold = 0.5)

Arguments

param_list

A named list of biological‑scale parameters required by `log_prob_detect()`. Must include `mu`, `sigltil`, `sigrtil`, `ctil`, `pd`, and `o_mat`. Values like `sigltil`/`sigrtil` can be `Inf`.

env_data

A named list of time‑series raster objects (e.g., from the `terra` package). Each element must be a `SpatRaster` with the same geometry and number of layers.

size_presence

Integer. Number of sample points to draw from cells where the detection probability **exceeds** `threshold`.

size_absence

Integer. Number of sample points to draw from cells where the detection probability is **less than or equal to** `threshold`.

threshold

Numeric in `[0, 1]`. Probability cutoff used to distinguish presence vs. absence sampling areas. Default `0.5`.

Value

A tibble with columns `lon`, `lat`, `presence` (0/1), where each row corresponds to a sampled point. The presence/absence is drawn from a binomial distribution using the habitat suitability value as the success probability.

Details

Internally the function:

1. Computes a habitat suitability raster using `habitat_suitability()`.

2. Splits the raster into two layers based on `threshold`: cells with prob > threshold (presence pool) and ≤ threshold (absence pool).

3. Samples `size_presence` and `size_absence` points from each pool (without replacement), with probabilities proportional to the suitability value.

4. Generates a binomial outcome for each sampled point using its suitability as the probability of success.

See also

[habitat_suitability()], [log_prob_detect()], [terra::spatSample()]

Examples

# \donttest{
data("example_1", package = "xsdm")
bio1_ts  <- terra::unwrap(example_1$bio01) / 100
bio12_ts <- terra::unwrap(example_1$bio12) / 100
env_data <- list(bio1 = bio1_ts, bio12 = bio12_ts)

vsp(
  param_list    = example_1$true_par_list,
  env_data      = env_data,
  size_presence = 100,
  size_absence  = 100,
  threshold     = 0.7
)
#> # A tibble: 200 × 3
#>         lon      lat presence
#>       <dbl>    <dbl>    <int>
#>  1  -738723 1552222.        1
#>  2 -1003723 1502222.        1
#>  3 -1133723 1407222.        0
#>  4  -748723 1567222.        0
#>  5 -1088723 1387222.        0
#>  6  -783723 1482222.        1
#>  7 -1123723 1357222.        1
#>  8 -1073723 1312222.        1
#>  9 -1008723 1587222.        1
#> 10 -1008723 1517222.        0
#> # ℹ 190 more rows
# }