Get target achievement summary from a solution set

Extract a user-facing target-achievement table from a solutionset-class object returned by solve.

The returned table summarizes, for each stored target, the target level, the achieved value, the gap between achieved and required values, and whether the target was met in each run.

Usage

get_targets(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 runs are returned when available.
...: Deprecated arguments kept for backwards compatibility. Currently supports run and solution_id, which are redirected to solution.

Value

A simplified data.frame target summary, or NULL if the result does not contain targets. Typical columns include feature, feature_name, target_level, total_available, target, achieved, gap, and met.

Details

Targets are optional in multiscape. If the result object does not contain a targets summary table at x$summary$targets, this function returns NULL without error.

This function reads the stored targets summary and returns a simplified user-facing table. If the summary contains achieved and target_value, target satisfaction is evaluated as follows.

For lower-bound targets: $$ \mathrm{met} = (\mathrm{achieved} \ge \mathrm{target}), $$

and for upper-bound targets: $$ \mathrm{met} = (\mathrm{achieved} \le \mathrm{target}). $$

The interpretation of the target direction is taken from the sense column when available:

"ge", ">=", or "min" are treated as lower-bound targets;
"le", "<=", or "max" are treated as upper-bound targets;
if sense is missing, the target is treated as a lower bound by default.

The returned table is simplified and renames some internal fields for readability:

target_raw is returned as target_level;
basis_total is returned as total_available;
target_value is returned as target.

If solution is provided, only rows belonging to that solution are returned. If the result contains a run_id column but only a single solution is present and solution was not requested explicitly, the solution_id column is removed for convenience.

The gap column is expected to be part of the stored summary. When present, it typically represents: $$ \mathrm{gap} = \mathrm{achieved} - \mathrm{target}. $$

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$effects,
    effect_type = "delta"
  ) |>
  add_constraint_targets_relative(0.05) |>
  add_objective_min_cost(alias = "cost", include_pu_cost = FALSE) |>
  add_objective_max_benefit(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)

  # Target requirements and achieved amounts
  get_targets(solutions)

  # Target achievement for one run
  solution_ids <- get_runs(solutions)$solution_id

  get_targets(
    solutions,
    solution = solution_ids[1]
  )
}
#>   solution_id feature feature_name target_level total_available    target
#> 1           1       1     woodland         0.05        14.08761 0.7043806
#> 2           1       2     riparian         0.05        13.44903 0.6724515
#>    achieved       gap  met
#> 1 0.9232126 0.2188321 TRUE
#> 2 1.3000697 0.6276182 TRUE