get_planning_units: Get planning-unit results from a solution set

In multiscape: Multi-Action, Multi-Objective Spatial Planning

Get planning-unit results from a solution set

Description

Extract the planning-unit summary table from a solutionset-class object returned by solve.

The returned table summarizes solution values at the planning-unit level and typically includes a selected indicator showing whether each planning unit is selected in a solution.

Usage

get_planning_units(x, solution = NULL, ...)

Arguments

x	A solutionset-class object returned by solve.
solution	Optional positive integer giving the solution id to extract. If NULL, all solutions are returned when available.
...	Deprecated arguments kept for backwards compatibility. Currently supports run and solution_id, which are redirected to solution.

Details

This function reads the planning-unit summary stored in x$summary$pu. It does not reconstruct the table from the raw decision vector; it simply returns the stored summary after optional run filtering.

Let w_i denote the planning-unit selection variable for planning unit i. In standard multiscape workflows, the selected column is the user-facing representation of that planning-unit decision, typically coded as 0 or 1.

If solution is provided, only rows belonging to that solution are returned. This requires the summary table to contain a solution_id column.

To return only selected planning units, filter the returned table using selected == 1.

Value

A data.frame containing the stored planning-unit summary. Typical columns include planning-unit identifiers, optional labels, and a selected indicator.

See Also

get_actions, get_features, get_targets

Examples

# Load a complete simulated planning problem.
example_data <- load_sim_multiaction()

problem <- create_problem(
  pu = example_data$planning_units,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  ) |>
  add_effects(
    example_data$effect_assumptions
  ) |>
  add_constraint_targets_relative(0.05) |>
  add_objective_min_cost(alias = "cost", include_pu_cost = FALSE) |>
  add_objective_max_effect(alias = "benefit") |>
  set_method_weighted_sum(
    aliases = c("cost", "benefit"),
    runs = set_runs_grid(n = 3),
    normalize_weights = TRUE
  )

if (requireNamespace("rcbc", quietly = TRUE)) {
  problem <- set_solver_cbc(
    problem,
    verbose = FALSE
  )

  solutions <- solve(problem)

  # Planning-unit results for all stored runs
  get_planning_units(solutions)

  # Return only selected planning units
  selected_pu <- get_planning_units(solutions)
  selected_pu <- selected_pu[selected_pu$selected == 1L, , drop = FALSE]
  selected_pu

  # Extract one run using its solution_id
  solution_ids <- get_runs(solutions)$solution_id

  get_planning_units(
    solutions,
    solution = solution_ids[1]
  )
}

multiscape documentation built on Oct. 12, 2026, 5:08 p.m.