Density → suitability-scale [0,100] transforms

Maps a density-response surface (individuals km^-2 per cell over a model's domain) onto the 0,100 scale the per-taxon merge operates on. Four candidates, all monotone in density; they differ in how they DISTRIBUTE values, which is what an extinction-risk- weighted sum (Σ er × val / 100) and an ecoregional min–max rescale respond to:

"cap"

Linear in density, 100 at the p_cap quantile of the positive densities, clamped above. Proportional — Σ val is proportional to modelled abundance below the cap — so a surface keeps its meaning as a relative-abundance layer. Heavy-tailed densities leave most cells near 0. What the v8 gm/nc ingests do.

"log"

Linear in log density between the p_floor and p_cap quantiles (0 below, 100 above). Compresses the tail; loses proportionality; the floor is arbitrary.

"ud"

The population percentile of the cell: 100 minus the percent of the modelled population living in cells STRICTLY denser than this one (area-weighted). The densest cell is 100; the cells with val >= 100 - p are exactly the p % core — the utilization-distribution isopleth convention (50 % core, 95 % home range).

"qmap"

Quantile mapping (histogram matching) of the density distribution onto a reference suitability distribution ref: val = Q_ref(F_d(d)). Keeps the density's spatial ordering and takes the incumbent's marginal, so folding the surface in REDISTRIBUTES the taxon's values inside the domain rather than re-levelling them.

A non-positive density is 0 under every method (absent is absent), and NA passes through.

Usage

density_to_suit(
  d,
  method = c("cap", "log", "ud", "qmap"),
  p_cap = 0.995,
  p_floor = 0.01,
  area = NULL,
  ref = NULL,
  digits = 2
)

Arguments

d

numeric; density per cell (individuals km^-2) over the model domain.

method

one of "cap", "log", "ud", "qmap".

p_cap

quantile of the POSITIVE densities that maps to 100 (cap, log); default 0.995.

p_floor

quantile of the positive densities that maps to 0 under log; default 0.01.

area

numeric; cell areas (km^2) weighting ud (default NULL = equal areas).

ref

numeric in 0,100; the reference distribution for qmap (e.g. the taxon's own AquaMaps/AquaX suitability over the same cells). Required for qmap.

digits

rounding of the result (default 2, the atlas' val precision); NULL = none.

Value

numeric in 0,100 of length(d); NA where d is NA.

Examples

d <- c(0, 0.001, 0.01, 0.1, 1)
density_to_suit(d, "cap", p_cap = 1)     # 0, 0.1, 1, 10, 100
#> [1]   0.0   0.1   1.0  10.0 100.0
density_to_suit(d, "ud")                 # population percentile: densest cell = 100
#> [1]   0.00   0.09   0.99   9.99 100.00
density_to_suit(d, "qmap", ref = c(5, 20, 40, 60, 90))
#> [1]  0.00  5.00 26.67 53.33 90.00