deduplicate_h3_selections: Deduplicate multiscale selections across H3 resolutions

In MultiscaleSCP: Multiscale Systematic Conservation Planning Across Nested H3 Grids

Deduplicate multiscale selections across H3 resolutions

Description

Removes redundant planning-unit selections across nested H3 resolutions. Because finer and coarser H3 cells overlap perfectly (parent–child hierarchy), a selection at one resolution makes selections at other resolutions redundant.

This function enforces a consistent hierarchy using one of two strategies:

• "coarser_first" – keep coarser selected cells and drop all selected descendants (finer cells). Useful if coarse-scale representation should dominate.

• "finer_first" – keep finer selected cells and drop selected ancestors (coarser cells). Useful when fine-scale detail should dominate and coarse cells should not “override” them.

Usage

deduplicate_h3_selections(
  s,
  sel_col,
  h3_vec,
  res_vec,
  res_levels,
  nearest_parent_row_of,
  children_by_row,
  mode = c("coarser_first", "finer_first")
)

Arguments

s	An sf or data frame containing at least the selection column (sel_col).
sel_col	Name of the 0/1 column to deduplicate (e.g. "solution_1").
h3_vec	Character vector of H3 addresses (one per PU; same order as s).
res_vec	Integer vector of H3 resolutions (same length/order as h3_vec).
res_levels	Vector of resolutions in hierarchical order (e.g. c(5, 6, 7)).
nearest_parent_row_of	Integer vector where each position gives the row index of the nearest parent cell in s (or NA if none), as returned by build_h3_maps().
children_by_row	List of integer vectors giving, for each PU row, the row indices of all direct children (finer-resolution descendants), as returned by build_h3_maps().
mode	Either "coarser_first" or "finer_first" (default). Controls whether coarse or fine PUs are retained when duplicates occur.

Details

When mode = "finer_first", removing selected coarser cells can reduce the total selected area if only a subset of their descendant cells were selected (i.e., partial coverage of the parent footprint).

The function operates in a single pass, using the precomputed parent/child lists from build_h3_maps(), and produces a new column paste0(sel_col, "_deduplicated").

Value

The input s with an additional column paste0(sel_col, "_deduplicated") containing a clean 0/1 selection.

Examples

# One parent (res7) with two children (res8)
parent <- "872a1072bffffff"
kids   <- c("882a1072b1fffff", "882a1072b3fffff")

h3_vec  <- c(parent, kids)
res_vec <- c(7L, 8L, 8L)

maps <- build_h3_maps(h3_vec, res_vec = res_vec)

s <- data.frame(solution_1 = c(1L, 1L, 1L))

# Keep the coarser cell (drops children)
out_coarse <- deduplicate_h3_selections(
  s, sel_col = "solution_1",
  h3_vec = maps$h3_vec, res_vec = maps$res_vec, res_levels = maps$res_levels,
  nearest_parent_row_of = maps$nearest_parent_row_of,
  children_by_row = maps$children_by_row,
  mode = "coarser_first"
)

# Keep the finer cells (drops parent)
out_fine <- deduplicate_h3_selections(
  s, sel_col = "solution_1",
  h3_vec = maps$h3_vec, res_vec = maps$res_vec, res_levels = maps$res_levels,
  nearest_parent_row_of = maps$nearest_parent_row_of,
  children_by_row = maps$children_by_row,
  mode = "finer_first"
)

out_coarse
out_fine

MultiscaleSCP documentation built on March 30, 2026, 5:08 p.m.