linkage_contrasts: Select informative solution contrasts

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

Select informative solution contrasts

Description

Rank pairwise linkage results to identify solution pairs that are especially informative in objective space, decision space, or their relationship.

Usage

linkage_contrasts(
  x,
  type = c("objective_similar", "decision_similar", "high_turnover",
    "high_reconfiguration", "low_reconfiguration", "objective_tie"),
  n = 3L
)

Arguments

x	A data.frame returned by linkage_distances or linkage_turnover.
type	Contrast to rank: "objective_similar", "decision_similar", "high_turnover", "high_reconfiguration", "low_reconfiguration", or "objective_tie".
n	Number of contrasts to return.

Details

"objective_similar" ranks pairs by increasing objective distance and uses larger decision distance as a secondary criterion. Conversely, "decision_similar" ranks pairs by increasing decision distance and then decreasing objective distance. "high_turnover" ranks pairs by decreasing decision distance.

The "high_reconfiguration" and "low_reconfiguration" types require a numeric reconfiguration_rate column, as returned by linkage_turnover. Rows with an undefined reconfiguration_rate are excluded from these rankings.

"objective_tie" returns objective-equivalent pairs with non-zero decision distance, ranked from largest to smallest spatial difference. This type requires the logical objective_tie column returned by linkage_turnover. The numerical tolerance used to identify objective ties is therefore controlled only by linkage_turnover().

from_solution and to_solution must contain positive integer solution ids. Numeric values such as 1 are accepted when they are integer-valued and are returned as integers.

Value

The first n ranked rows. The columns in x are preserved, with contrast_rank and contrast_type prepended to identify the rank and contrast criterion used.

See Also

linkage_distances, linkage_turnover

Other Objective–decision linkage: linkage_distances(), linkage_transition(), linkage_turnover()

Examples

# Load a complete simulated multi-action 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 = 5),
    normalize_weights = TRUE
  )

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

  linkage <- linkage_distances(
    solutions,
    objectives = c("cost", "benefit")
  )

  linkage_contrasts(
    linkage,
    type = "objective_similar",
    n = 3
  )

  turnover <- linkage_turnover(
    solutions,
    objectives = c("cost", "benefit")
  )

  linkage_contrasts(
    turnover,
    type = "high_reconfiguration",
    n = 3
  )
}

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