nulltest: Test significance of split-lines in spatial subdivision

In hespdiv: Hierarchical Spatial Data Subdivision into Topologically Contiguous Units

Test significance of split-lines in spatial subdivision

Description

Assess the statistical significance of each split-line (bioregion boundary) identified by hespdiv by comparing its observed performance to a null distribution. The null is generated by permuting the data n times and recomputing the split-line performance after each permutation. Multiple shuffling strategies are supported to probe the influence of spatial structure on delineation.

Usage

nulltest(
  obj,
  n = 999,
  maintain.n = TRUE,
  shuffle.scope = "within",
  shuffle.type = "localities"
)

Arguments

obj	An object of class hespdiv.
n	Integer. Number of permutations used to form the null distribution.
maintain.n	Logical. Only honored when shuffle.scope = "within" and shuffle.type = "localities". If TRUE, attempts to keep the randomized child polygon occurrence counts close to the observed (maximum discrepancy up to max_n/2, where max_n is the largest locality size). Ignored otherwise.
shuffle.scope	Character. Either "all" (shuffle across the full study area) or "within" (shuffle only within each parent polygon).
shuffle.type	Character. Either "localities" (shuffle whole localities, preserving assemblages) or "occurrences" (shuffle individual occurrences). "localities" is generally preferred.

Details

Two shuffling scopes are available:

"all":

Shuffle across the entire study area, ignoring polygonal subdivisions.

"within":

Shuffle only within each parent polygon (the region in which the split-line is nested), preserving local spatial structure.

Two shuffling types are available:

"localities":

Shuffle whole localities, preserving each site's assemblage (recommended, since occurrences within a locality are not independent).

"occurrences":

Shuffle individual occurrences across sites (use with caution; may violate within-locality independence).

For each split-line, the function reports the observed performance, the mean and standard deviation of the permuted (null) performances, an empirical one-sided p-value (proportion of permuted values as or more extreme than observed; ties included), and a z-score quantifying departure from the null.

Value

Invisibly returns an object of class nullhespdiv, a list with:

• $stats, a data frame summarizing each split-line with:

  • performance: observed performance.

  • mean.random: mean of null performances.

  • sd.random: standard deviation of null performances.

  • p.val: empirical one-sided p-value (ties included).

  • z.score.random: standardized effect size.

• $null, a matrix or data frame containing all null performance values for every split-line across permutations.

See Also

Other functions for hespdiv results post-processing: cross_comp(), hsa(), hsa_detailed(), hsa_quant(), hsa_sample_constrained(), taxon_effect()

Examples

# if split-line is strongly significant, the choice of parameters should not
# matter. For example (look at p-value, z.score.random, sd.random and
# mean.random):
(nulltest(example_hespdiv, maintain.n = FALSE, shuffle.type = "occurrences"))
(nulltest(example_hespdiv, maintain.n = FALSE, shuffle.type = "localities"))
(nulltest(example_hespdiv, maintain.n = TRUE, shuffle.type = "localities"))

hespdiv documentation built on May 21, 2026, 5:09 p.m.