linkage_transition: Describe the transition between two solutions

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

Describe the transition between two solutions

Description

Explain the objective and spatial changes required to transform one stored solution into another.

Usage

linkage_transition(x, from, to, objectives = NULL)

Arguments

x	A solutionset-class object returned by solve.
from	A single numeric positive-integer id identifying the starting stored solution.
to	A single numeric positive-integer id identifying the destination stored solution.
objectives	Optional character vector with one or more objective aliases. If NULL, all registered objectives are reported.

Details

The transition is directional. Reversing from and to reverses signed objective changes, additions and removals, and planning-unit activations and deactivations. Canonical planning-unit states are obtained from get_solution_states.

The complete landscape is always returned in transitions, including planning units whose state is unchanged. To keep the action-level output compact, actions contains assignments selected in at least one of the two solutions; added, removed, and retained actions remain explicit.

Value

An object of class multiscape_linkage_transition containing:

• summary: the directed solution ids and transition counts;

• objectives: objective values and signed changes;

• transitions: one row per planning unit in the complete landscape, including unchanged units;

• actions: action assignments selected in either solution;

• state_matrix: counts of planning-unit state transitions.

See Also

get_solution_states, linkage_distances, frontier_neighbors

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

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

  transition <- linkage_transition(
    solutions,
    from = neighbors$from_solution[1],
    to = neighbors$to_solution[1],
    objectives = c("cost", "benefit")
  )

  transition$summary
  transition$objectives

  transition$transitions[
    transition$transitions$changed,
    ,
    drop = FALSE
  ]
}

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