Skip to contents

The regional test: is the model contradicted where people looked?

Source: R/range.R
region_effort_test.Rd

The range rule's second test, one row per region. Among the units (cells, or blocks of cells) the model calls present, n_searched were searched (they hold a record of the species' target group) and n_occupied of those hold a record of the species itself. The model's precision everywhere else (p_core, the same ratio over all other searched units) says how many records to expect; the binomial tail P(X <= n_occupied | n_searched, p_core) says how surprising this few are.

Usage

region_effort_test(
  n_searched,
  n_occupied,
  n_searched_all,
  n_occupied_all,
  n_records = n_occupied,
  alpha = 0.05,
  ratio = 0.25
)

Arguments

n_searched

model-present units in the region that were searched

n_occupied

those among them holding a record of the species

n_searched_all, n_occupied_all

the same two counts over ALL model-present units (one value per species, recycled)

n_records

units in the region holding a record of the species, whether or not the model calls them present (decides the label only)

alpha

rejection level

ratio

a region is dropped only if its record rate is below this share of p_core (in (0, 1]; 1 = significance alone)

Value

a data frame, one row per region: p_core, rate, n_min, p_value, verdict, label

Details

  • p_value < alpha and the region's own record rate (n_occupied / n_searched) is below ratio times p_core -> "dropped": searched, and the species is not there.

  • fewer searched units than n_min, the smallest number at which even zero records could reach alpha -> "unsearched": kept, and flagged. Empty of observers is not empty of turtles.

  • otherwise "kept".

The second condition is the effect size. With hundreds of searched units the binomial tail alone rejects any region where the species is merely scarcer than in its stronghold: on the published OBIS models it dropped the whole US Pacific for the loggerhead (139 occupied blocks of 978 searched, against 23 % elsewhere) and for the green turtle, Hawaii included. A region is contradicted only when records are both significantly AND materially fewer. ratio = 1 is the test without the guard.

A dropped region with at least one record of the species (n_records > 0) is labelled "documented occurrence only": the vagrant is on the record, the region is not range.

Leaving the tested region out of p_core is what lets the test see a region at all: a species' stronghold is compared with the rest of its range, not with itself.

Examples

# 400 searched units and 2 records, where the rest of the range shows 1 record in 10
region_effort_test(n_searched = 400, n_occupied = 2, n_searched_all = 5400, n_occupied_all = 502)
#>   p_core  rate n_min     p_value verdict                      label
#> 1    0.1 0.005    29 5.12987e-16 dropped documented occurrence only