Prepare Data to Plot Selection Frequency of Planning Units — splnr_get

splnr_get_selFreq() calculates how many times each Planning Unit is selected across an array of prioritizr solutions. This "selection frequency" can be derived from either a list of individual solutions or a prioritizr portfolio object.

Usage

splnr_get_selFreq(solnMany, type = "portfolio")

Arguments

solnMany: A list of prioritizr solutions (if type = "list") or a single sf object representing a prioritizr portfolio of solutions (if type = "portfolio"). Each individual solution must contain a column named solution_1.
type: A character string indicating the input type: "portfolio" (for a single sf object with multiple solution columns) or "list" (for a list of single-solution sf objects). Defaults to "portfolio".

Value

An sf object (selFreq) containing a column named selFreq. This column is a factor representing the selection frequency (sum of selected occurrences across all solutions) for each Planning Unit.

Details

Understanding selection frequency is crucial for identifying robust conservation areas—those that are consistently chosen across multiple planning scenarios or alternative optimal solutions.

The function supports two types of input:

"portfolio": If solnMany is a single sf object representing a portfolio of solutions (e.g., generated by prioritizr::add_cuts_portfolio()). In this case, the function assumes columns starting with "solution_" represent individual solutions within the portfolio.
"list": If solnMany is a list where each element is an sf object representing a single prioritizr solution (each with a "solution_1" column).

For both types, the function sums the binary solution values (0 or 1) across all solutions for each Planning Unit. The result is converted to a factor to represent discrete frequency levels.

The output sf object can then be passed to splnr_plot_selectionFreq() for visualization as a heatmap.

Examples

if (FALSE) { # \dontrun{
# Assuming 'dat_species_bin' is an existing sf object in your package.

# Create a base prioritizr problem.
dat_problem <- prioritizr::problem(
  dat_species_bin %>% dplyr::mutate(Cost = runif(n = dim(.)[[1]])),
  features = c("Spp1", "Spp2", "Spp3", "Spp4", "Spp5"),
  cost_column = "Cost"
) %>%
  prioritizr::add_min_set_objective() %>%
  prioritizr::add_relative_targets(0.3) %>%
  prioritizr::add_binary_decisions() %>%
  prioritizr::add_default_solver(verbose = FALSE)

# --- Example 1: Using a portfolio of solutions ---
# Create a conservation problem that contains a portfolio of solutions (e.g., 5 solutions).
dat_soln_portfolio <- dat_problem %>%
  prioritizr::add_cuts_portfolio(number_solutions = 5) %>%
  prioritizr::solve.ConservationProblem()

# Calculate selection frequency from the portfolio.
selFreq_portfolio <- splnr_get_selFreq(solnMany = dat_soln_portfolio, type = "portfolio")
print(head(selFreq_portfolio))
# You can then plot this: splnr_plot_selectionFreq(selFreq_portfolio)

# --- Example 2: Using a list of individual solutions ---
# Solve the problem multiple times to get different solutions (e.g., by randomizing costs)
dat_soln_list <- list(
  dat_problem %>% prioritizr::solve.ConservationProblem(),
  dat_problem %>%
    dplyr::mutate(Cost = runif(n = dim(.)[[1]])) %>% # Vary cost for a different solution
    prioritizr::solve.ConservationProblem(),
  dat_problem %>%
    dplyr::mutate(Cost = runif(n = dim(.)[[1]])) %>% # Another different solution
    prioritizr::solve.ConservationProblem()
)

# Calculate selection frequency from the list of solutions.
selFreq_list <- splnr_get_selFreq(solnMany = dat_soln_list, type = "list")
print(head(selFreq_list))
# You can then plot this: splnr_plot_selectionFreq(selFreq_list)
} # }