build_multiscale_objective_data: Prepare data for multiscale minimum-set optimization

In MultiscaleSCP: Multiscale Systematic Conservation Planning Across Nested H3 Grids

Prepare data for multiscale minimum-set optimization

Description

Combines the planning-unit hierarchy, costs, and feature amounts into the data used for multiscale minimum-set optimization and solution evaluation.

Usage

build_multiscale_objective_data(
  pu,
  maps,
  cost_col = "area_km2",
  feature_cols,
  native_cols = NULL,
  tol = 1e-06
)

Arguments

pu	A planning-unit object. Its row order must match maps.
maps	A hierarchy object returned by build_h3_maps().
cost_col	Character name of the spatially additive planning-unit cost column.
feature_cols	A character vector or named character vector identifying the multiscale feature columns, typically the output of multiscale_feature_cols().
native_cols	Optional character vector identifying native-resolution feature columns. When supplied, native and atom-based totals are compared as a diagnostic.
tol	Numeric relative tolerance used for hierarchy reconciliation and diagnostic checks.

Details

The prepared data combine cost and feature representation across nested planning-unit resolutions. This allows planning units selected at different resolutions to contribute toward the same feature representation while shared spatial contributions are accounted for once.

The planning-unit row order used to build this object must also be used for the corresponding conservation problem and solution evaluation.

Value

A multiscale_objective_data object for use with add_multiscale_min_set() and eval_multiscale_atom_solution().

See Also

Other multiscale minimum-set: add_multiscale_min_set(), add_multiscale_min_set_objective(), add_multiscale_relative_targets(), build_multiscale_atoms(), build_multiscale_feature_atoms(), eval_multiscale_atom_solution(), load_multiscale_feature(), multiscale_feature_cols()

Examples

# Small hierarchy: a parent and two of its seven children.
# Feature amounts below are already prepared and additive.
pu <- data.frame(
  h3_address = c("872a1072bffffff", "882a1072b1fffff", "882a1072b3fffff"),
  res = c(7L, 8L, 8L), area_km2 = c(14, 2, 2),
  msopt_A = c(3, 1, 2), msopt_B = c(6, 2, 1),
  selected = c(1L, 1L, 0L))
maps <- build_h3_maps(pu, res_levels = c(7L, 8L))
ms_data <- build_multiscale_objective_data(
  pu = pu, maps = maps,
  feature_cols = c(A = "msopt_A", B = "msopt_B"))

result <- eval_multiscale_atom_solution(pu,
  solution_col = "selected", data = ms_data,
  targets = c(A = 2/3, B = 1/2))

result$relative_held
result$target_met

MultiscaleSCP documentation built on Oct. 14, 2026, 5:07 p.m.