linkage_distances: Compare objective and decision distances

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

Compare objective and decision distances

Description

Measure separately how far pairs of stored solutions are in objective space and how much their planning-unit/action assignments differ.

Usage

linkage_distances(
  x,
  objectives = NULL,
  pairs = NULL,
  objective_metric = c("euclidean", "manhattan", "chebyshev"),
  decision_metric = c("jaccard", "hamming")
)

Arguments

x	A solutionset-class object returned by solve.
objectives	Optional character vector with two or more unique objective aliases. If NULL, all registered objectives are used.
pairs	Either NULL, or a non-empty data.frame containing numeric positive-integer from_solution and to_solution columns. Output from frontier_neighbors can be supplied directly.
objective_metric	Objective-space distance metric: "euclidean", "manhattan", or "chebyshev".
decision_metric	Decision-space metric: "jaccard" or "hamming".

Details

Objective values are oriented to minimization and normalized using the solutions retained in the supplied SolutionSet. Decision distances are always calculated on the complete planning-unit/action assignment space represented by the supplied solutions.

If pairs = NULL, all unordered pairs are generated and oriented from worse to better on the first selected objective. If pairs is supplied, its from_solution and to_solution direction is preserved. Distances are symmetric, but signed objective changes and action additions or removals depend on pair direction.

No combined linkage score is calculated.

Value

A data.frame with one row per directed pair, including objective_distance, decision_similarity, decision_distance, decision-change counts, and objective-specific from/to values, changes, and improvements.

See Also

frontier_neighbors, frontier_distances, selection_similarity, linkage_transition

Other Objective–decision linkage: linkage_contrasts(), 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")
  )

  head(linkage)

  neighbors <- frontier_neighbors(
    solutions,
    objectives = c("cost", "benefit")
  )

  linkage_distances(
    solutions,
    objectives = c("cost", "benefit"),
    pairs = neighbors
  )
}

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