selection_frequency: Calculate selection frequency across solutions

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

Calculate selection frequency across solutions

Description

Calculate how frequently each planning-unit/action assignment is selected across the stored solutions in a solutionset-class object.

Usage

selection_frequency(x)

Arguments

x	A solutionset-class object returned by solve.

Details

Selection frequency is calculated at the planning-unit/action level. This is the canonical decision representation used by this function because it preserves differences between solutions that select the same planning unit but assign different actions.

For each planning-unit/action pair, the frequency is:

f_{ia} = \frac{\sum_{s \in S} x_{ias}} {|S|},

where x_{ias} equals one when planning unit i receives action a in solution s, and zero otherwise.

The result is computed over all stored solutions in the supplied SolutionSet. To calculate frequencies for only a subset of solutions, first use solution_filter or solution_unique.

For simple conservation-planning problems without explicit actions, selected planning units are represented using the canonical action name "conservation".

Selection frequency measures recurrence across the supplied solutions. It should not automatically be interpreted as formal irreplaceability because it depends on the solutions included, their sampling across objective space, and whether duplicate or dominated solutions have been retained.

Value

A data.frame with one row per planning-unit/action pair and the following columns:

• pu: planning-unit identifier;

• action: action identifier or name;

• n_selected: number of stored solutions in which the planning-unit/action pair is selected;

• n_solutions: total number of stored solutions considered;

• frequency: proportion of stored solutions in which the pair is selected.

See Also

selection_similarity, selection_consistency, solution_filter, solution_unique, get_actions, get_planning_units

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)

  # Frequency across all stored solutions
  frequency <- selection_frequency(solutions)
  frequency

  # Restrict the analysis to non-dominated solutions
  if (requireNamespace("moocore", quietly = TRUE)) {
    nondominated_solutions <- solution_filter(
      solutions,
      feasible_only = TRUE,
      nondominated = TRUE
    )

    selection_frequency(nondominated_solutions)
  }

  # Give each distinct decision configuration the same weight
  unique_solutions <- solution_unique(
    solutions,
    by = "decisions"
  )

  unique_frequency <- selection_frequency(
    unique_solutions
  )

  unique_frequency
}

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