group_effect: Investigate Group Effects on Split-Line Performance

In hespdiv: Hierarchical Spatial Data Subdivision into Topologically Contiguous Units

Investigate Group Effects on Split-Line Performance

Description

For every level of group, the function:

1. subsets data and xy.dat to the focal group's observations;

2. recomputes split-line performance using compare.f and generalize.f;

3. runs two contribution assessments:

   • group-removal: removes the group's observations and recomputes performance;

   • group-permutation (locality-block shuffle): shuffles intact within-locality assemblages of the focal group among the set of localities where the group occurs within the split’s parent polygons (non-group observations fixed).

4. optionally re-plots the object for that group via plot_hespdiv (with a group-specific subtitle).

Usage

group_effect(obj, group, perm.n = 999, maxdif = NULL, plot = TRUE, ...)

Arguments

obj	A hespdiv object.
group	A factor (or coercible to factor) giving the group label for each observation (row) in obj$call.info$Call_ARGS$xy.dat.
perm.n	Integer (>0). Number of permutations in the locality-block permutation test. Default 999.
maxdif	Numeric. The performance value representing a maximal between-polygons difference for the chosen metric. If NULL and the metric is one of c("pielou","morisita","sorensen","horn.morisita"), maxdif is set automatically. Otherwise, it must be provided.
plot	Logical. If TRUE (default), stores a plot_hespdiv output per group with performance = TRUE and a group-specific subtitle.
...	Additional arguments passed to plot_hespdiv. Note that obj, performance, and subtitle are set internally.

Details

Re-evaluates split-line performance within each level of a grouping factor and tests how much each group influences the detected split-lines in a hespdiv object.

Within-group recomputation (agreement). For each split, the group's observations are partitioned by the two child polygons and performance is recomputed as compare.f(generalize.f(pol1), generalize.f(pol2)). If the group's points fall on only one side, within$est is set to maxdif; if absent from both sides, it is NA.

Elimination test. All observations of the focal group are removed from both polygons and performance is recomputed on the remaining data. If the group's points fall on only one side, elim$est is computed normally; if absent from both sides, it is NA (if desired, you could identify these cases afterwards from n_per_pol, changing to baseline performance and zero delta).

Permutation test (locality-block shuffle). Localities are defined by identical coordinate pairs among the focal group's occurrences. For each permutation, whole localities (blocks) are reassigned via a one-to-one mapping within the split’s parent polygons. For speed, polygon membership of unique locality coordinates is precomputed once per split and then locality memberships are shuffled in each permutation. If the group's points fall on only one side, perm$est is set to NA; if absent from both sides, it is also NA.

Baseline and deltas. The baseline vector is baseline <- obj$split.stats$performance. Let maximize <- obj$call.info$Call_ARGS$maximize. Deltas are defined so that positive values always indicate a positive contributor (removal/permutation worsens performance):

• if maximize == FALSE (lower is better; e.g. similarity): delta = est - baseline;

• if maximize == TRUE (higher is better; e.g. distance): delta = baseline - est.

Value

A list of class "group_effect" with elements:

• within = list(est, delta) where est and delta are [n_splits x n_groups] matrices;

• elim = list(est, delta) as above (group removed);

• perm = list(est, delta) where each is a nested list [[split]][[group]] of numeric vectors (length perm.n). If permutations are uninformative (e.g., one-sided/absent), the corresponding entries are NA;

• baseline: the original performance vector;

• n_per_pol: data.frame with columns split.id, group, pol.id, n;

• plots: list of plot_hespdiv outputs by group (or NULL if plot = FALSE).

Notes

• Localities are defined by exact duplicate coordinate pairs among the group's observations (harmonise coordinates upstream if needed).

• The locality-block permutation preserves the number of group-present localities per polygon; only identities of the locality blocks are shuffled. The number of group occurrences per side can vary if block sizes differ.

See Also

plot_hespdiv

Examples

data <- example_hespdiv$call.info$Call_ARGS$data
# See the hespdiv() example; lowercase letters represent widespread taxa:
endemic_l <- !data %in% letters[1:5]
group <- factor(ifelse(endemic_l, "endemic", "widespread"))

gr_ef <- group_effect(obj = example_hespdiv, group = group, plot = FALSE)

barplot(
  gr_ef$within$est,
  main = "Split-line similarity within each group",
  ylab = "Performance"
)

barplot(
  gr_ef$within$delta,
  main = "Group contribution to similarity within each group",
  ylab = "Contribution"
)
abline(h = 0)

barplot(
  gr_ef$elim$est,
  main = "Split-line similarity with group eliminated",
  ylab = "Performance"
)

barplot(
  gr_ef$elim$delta,
  main = "Group contribution to similarity with group eliminated",
  ylab = "Contribution"
)
abline(h = 0)

boxplot(
  gr_ef$perm$est$`1`,
  main = "Split-line similarity with group spatially permuted",
  ylab = "Performance"
)

boxplot(
  gr_ef$perm$delta$`1`,
  main = "Group contribution to similarity with group spatially permuted",
  ylab = "Contribution"
)
abline(h = 0)

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