### Add group targets example setup

Source: https://prioritizr.net/reference/add_group_targets.html

Initial setup for using group targets, including setting a seed and loading simulation data.

```r
# set seed for reproducibility
set.seed(500)

# load data
sim_complex_pu_raster <- get_sim_complex_pu_raster()
sim_complex_features <- get_sim_complex_features()
sim_pu_polygons <- get_sim_pu_polygons()
```

--------------------------------

### Accessing Gurobi Installation Guide

Source: https://prioritizr.net/reference/add_gurobi_solver.html

Use this command to open the Gurobi installation guide vignette within R.

```R
vignette("gurobi_installation_guide", package = "prioritizr")
```

--------------------------------

### Examples of add_extra_portfolio

Source: https://prioritizr.net/reference/add_extra_portfolio.html

Examples demonstrating how to use add_extra_portfolio with both single-zone and multi-zone conservation planning problems.

```R
# set seed for reproducibility
set.seed(600)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with a portfolio for extra solutions
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_extra_portfolio() %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem and generate portfolio
s1 <- solve(p1)

# convert portfolio into a multi-layer raster object
s1 <- terra::rast(s1)

# print number of solutions found
print(terra::nlyr(s1))
#> [1] 10

# plot solutions
plot(s1, axes = FALSE)


# create multi-zone problem with a portfolio for extra solutions
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(matrix(runif(15, 0.1, 0.2), nrow = 5, ncol = 3)) %>%
  add_extra_portfolio() %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem and generate portfolio
s2 <- solve(p2)

# convert each solution in the portfolio into a single category layer
s2 <- terra::rast(lapply(s2, category_layer))

# print number of solutions found
print(terra::nlyr(s2))
#> [1] 10

# plot solutions in portfolio
plot(s2, axes = FALSE)
```

--------------------------------

### add_min_set_objective examples

Source: https://prioritizr.net/reference/add_min_set_objective.html

Examples demonstrating how to use add_min_set_objective for both single-zone and multi-zone conservation problems.

```R
# set seed for reproducibility
set.seed(500)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with minimum set objective
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create multi-zone problem with minimum set objective
targets_matrix <- matrix(rpois(15, 1), nrow = 5, ncol = 3)

p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_absolute_targets(targets_matrix) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s2 <- solve(p2)

# plot solution
plot(category_layer(s2), main = "solution", axes = FALSE)
```

--------------------------------

### Example: Solving a problem with add_lpsymphony_solver

Source: https://prioritizr.net/reference/add_lsymphony_solver.html

A complete example demonstrating how to create a conservation planning problem, add the SYMPHONY solver, and generate a solution.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create problem
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_proportion_decisions() %>%
  add_lpsymphony_solver(time_limit = 5, verbose = FALSE)

# generate solution
s <- solve(p)

# plot solution
plot(s, main = "solution", axes = FALSE)
```

--------------------------------

### Check if examples should be run

Source: https://prioritizr.net/reference/do_run_example.html

Determines if the session is suitable for executing long-running examples by returning a logical value.

```R
do_run_example()
```

--------------------------------

### add_default_solver example

Source: https://prioritizr.net/reference/add_default_solver.html

An example demonstrating how to create a conservation planning problem, add the default solver with specific parameters, and solve the problem.

```R
# set seed for reproducibility
set.seed(600)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create minimal problem with default portfolio
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_binary_decisions() %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem
s <- solve(p)

# plot solution
plot(s)
```

--------------------------------

### Example usage of do_run_example

Source: https://prioritizr.net/reference/do_run_example.html

Demonstrates the usage of do_run_example and its typical output.

```R
# should examples be run in current environment?
do_run_example()
#> [1] TRUE
```

--------------------------------

### Examples of as_per_km2 and as_km2

Source: https://prioritizr.net/reference/as_per_km2.html

Examples demonstrating unit conversion to density per km2 using as_per_km2 and area conversion using as_km2.

```R
as_per_km2(5, "km2")
#> [1] 5
as_per_km2(5, "acres")
#> [1] 1235.522
as_per_km2(c(5, 10), "ha")
#> [1]  500 1000
as_km2(c(5, 10), c("ha", "acres"))
#> [1] 0.05000000 0.04046873
```

--------------------------------

### Install and load required packages

Source: https://prioritizr.net/

Commands to install and load the necessary R packages for the prioritizr workflow.

```R
# to install packages for this example, please use:
# install.packages(c("prioritizr", "prioritizrdata"))

# load packages
library(prioritizr)
library(prioritizrdata)
library(terra)
```

--------------------------------

### number_of_zones examples

Source: https://prioritizr.net/reference/number_of_zones.html

Examples demonstrating how to extract the number of zones from feature objects, conservation problems, and multi-problems.

```R
# load data
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# print number of zones in a Zones object
print(number_of_zones(sim_zones_features))
#> [1] 3
# create problem with multiple zones
p <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(matrix(0.2, ncol = 3, nrow = 5)) %>%
  add_binary_decisions()

# print number of zones in the problem
print(number_of_zones(p))
#> [1] 3

# create two example problems
mp <-
  multi_problem(
    obj1 =
      problem(sim_zones_pu_raster, sim_zones_features) %>%
      add_min_set_objective() %>%
      add_relative_targets(matrix(0.2, ncol = 3, nrow = 5)) %>%
      add_binary_decisions(),
    obj2 =
      problem(sim_zones_pu_raster, sim_zones_features) %>%
      add_min_set_objective() %>%
      add_relative_targets(matrix(0.1, ncol = 3, nrow = 5)) %>%
      add_binary_decisions()
  )

# print number of zones
print(number_of_zones(mp))
#> [1] 3
```

--------------------------------

### Solving Problems with Gurobi Solver

Source: https://prioritizr.net/reference/add_gurobi_solver.html

This example demonstrates creating a conservation planning problem, solving it with the Gurobi solver, and using that solution as a starting point for a subsequent problem with boundary penalties.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create problem
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_gurobi_solver(gap = 0, verbose = FALSE)

# generate solution
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create a similar problem with boundary length penalties and
# specify the solution from the previous run as a starting solution
p2 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_boundary_penalties(10) %>%
  add_binary_decisions() %>%
  add_gurobi_solver(gap = 0, start_solution = s1, verbose = FALSE)

# generate solution
s2 <- solve(p2)

# plot solution
plot(s2, main = "solution with boundary penalties", axes = FALSE)
```

--------------------------------

### do_run_example()

Source: https://prioritizr.net/reference/do_run_example.html

Determines if the session is suitable for executing long-running examples.

```APIDOC
## do_run_example()

### Description
Determine if the session is suitable for executing long-running examples. This function returns TRUE if the session is interactive, or if it is not currently being used for package checks or building documentation.

### Usage
```R
do_run_example()
```

### Value
- **logical** - Returns TRUE if examples should be run, FALSE otherwise.
```

--------------------------------

### Compile a conservation problem example

Source: https://prioritizr.net/reference/compile.html

Example demonstrating how to build a conservation problem and compile it into an optimization problem.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# build minimal conservation problem
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1)

# compile the conservation problem into an optimization problem
o <- compile(p)

# print the optimization problem
print(o)
#> An optimization problem (<OptimizationProblem>)
#> • model sense: min
#> • dimensions:  5, 90, 450 (rows, columns, cells)
#> • variables:   90 (B)
```

--------------------------------

### Install developmental prioritizr version from GitHub

Source: https://prioritizr.net/

Install the development version directly from the GitHub repository using the remotes package.

```R
if (!require(remotes)) install.packages("remotes")
remotes::install_github("prioritizr/prioritizr")
```

--------------------------------

### add_min_shortfall_objective examples

Source: https://prioritizr.net/reference/add_min_shortfall_objective.html

Examples demonstrating the use of add_min_shortfall_objective for single-zone and multi-zone problems with different budget configurations.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create problem with minimum shortfall objective
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_shortfall_objective(1800) %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create multi-zone problem with minimum shortfall objective,
# with 10% representation targets for each feature, and set
# a budget such that the total maximum expenditure in all zones
# cannot exceed 3000
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_shortfall_objective(3000) %>%
  add_relative_targets(matrix(0.1, ncol = 3, nrow = 5)) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s2 <- solve(p2)

# plot solution
plot(category_layer(s2), main = "solution", axes = FALSE)


# create multi-zone problem with minimum shortfall objective,
# with 10% representation targets for each feature, and set
# separate budgets for each management zone
p3 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_shortfall_objective(c(3000, 3000, 3000)) %>%
  add_relative_targets(matrix(0.1, ncol = 3, nrow = 5)) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s3 <- solve(p3)

# plot solution
plot(category_layer(s3), main = "solution", axes = FALSE)
```

--------------------------------

### Simulate data example

Source: https://prioritizr.net/reference/simulate_data.html

Example demonstrating how to create a template raster and simulate spatially auto-correlated data using a Gaussian field.

```R
# create raster
r <- terra::rast(
  ncols = 10, nrows = 10, xmin = 0, xmax = 1, ymin = 0, ymax = 1, vals = 1
)

# simulate data using a Gaussian field
x <- simulate_data(r, n = 1, scale = 0.2)

# plot simulated data
plot(x, main = "simulated data", axes = FALSE)
```

--------------------------------

### Convert Marxan boundary data example

Source: https://prioritizr.net/reference/marxan_boundary_data_to_matrix.html

Example demonstrating the creation of planning unit data, manual creation of Marxan boundary data, and conversion to a sparse matrix format compatible with prioritizr.

```R
# create example planning unit layer
pu_data <-
  matrix(1:3, nrow = 1) %>%
  terra::rast() %>%
  setNames("id") %>%
  terra::as.polygons() %>%
  sf::st_as_sf()

# plot planning units
plot(pu_data)


# manually create Marxan boundary data for these planning units following
# the Marxan boundary data format specification
bldf <- data.frame(
  id1 = c(1, 2, 3, 1, 2),
  id2 =c(1, 2, 3, 2, 3),
  boundary = c(3, 2, 3, 1, 1)
)

# print data
print(bldf)
#>   id1 id2 boundary
#> 1   1   1        3
#> 2   2   2        2
#> 3   3   3        3
#> 4   1   2        1
#> 5   2   3        1

# convert to boundary matrix format for use in prioritizr
m1 <- marxan_boundary_data_to_matrix(NULL, bldf)

# print converted matrix
## we can see that the values in bldf and m1 are different,
## this is because Marxan and prioritizr use different formats
## for storing boundary information
print(m1)
#> 3 x 3 sparse Matrix of class "dsCMatrix"
#>           
#> [1,] 4 1 .
#> [2,] 1 4 1
#> [3,] . 1 4

# automatically create boundary data for use in prioritizr,
# by using the boundary_matrix() function
m2 <- boundary_matrix(pu_data)

# print matrix
## we can see that the values in m1 and m2 are exactly the same,
## this is because marxan_boundary_data_to_matrix() automatically
## converts Marxan data to the same format as boundary_matrix()
print(m2)
#> 3 x 3 sparse Matrix of class "dsCMatrix"
#>           
#> [1,] 4 1 .
#> [2,] 1 4 1
#> [3,] . 1 4
```

--------------------------------

### Example: Specifying targets based on minima

Source: https://prioritizr.net/reference/spec_min_targets.html

This example demonstrates creating a conservation problem and applying spec_min_targets to combine multiple target setting methods (relative, Jung et al., and Polak et al.) to determine the final targets.

```R
# set seed for reproducibility
set.seed(500)

# load data
sim_complex_pu_raster <- get_sim_complex_pu_raster()
sim_complex_features <- get_sim_complex_features()

# create base problem
p0 <-
  problem(sim_complex_pu_raster, sim_complex_features) %>%
  add_min_set_objective() %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# create problem with 20% targets
p1 <-
  p0 %>%
  add_auto_targets(method = spec_relative_targets(0.2))

# create problem with Jung et al. (2021) targets
p2 <-
  p0 %>%
  add_auto_targets(method = spec_jung_targets())

# create problem with Polak et al. (2015) targets
p3 <-
  p0 %>%
  add_auto_targets(method = spec_polak_targets())

# create problem with targets based on the minimum of 20% targets,
# Jung et al. (2021) targets, and Polak et al. (2015) targets
# for each feature (separately)
p4 <-
  p0 %>%
  add_auto_targets(
    method = spec_min_targets(
      spec_relative_targets(0.2),
      spec_jung_targets(),
      spec_polak_targets()
    )
  )

# solve problems
s <- c(solve(p1), solve(p2), solve(p3), solve(p4))
names(s) <- c("20% targets", "Jung targets", "Polak targets", "min targets")

# plot solutions
plot(s, axes = FALSE)
```

--------------------------------

### Setup and Raster Data Problem

Source: https://prioritizr.net/reference/eval_n_summary.html

Initializes the environment with sample data and builds a conservation problem using raster data.

```R
set.seed(500)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_pu_polygons <- get_sim_pu_polygons()
sim_features <- get_sim_features()
sim_zones_pu_polygons <- get_sim_zones_pu_polygons()
sim_zones_features <- get_sim_zones_features()

# build minimal conservation problem with raster data
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve the problem
s1 <- solve(p1)

# print solution
print(s1)
#> class       : SpatRaster
#> size        : 10, 10, 1  (nrow, ncol, nlyr)
#> resolution  : 0.1, 0.1  (x, y)
#> extent      : 0, 1, 0, 1  (xmin, xmax, ymin, ymax)
#> coord. ref. : WGS 84 / Pseudo-Mercator (EPSG:3857)
#> source(s)   : memory
#> varname     : sim_pu_raster
#> name        : layer
#> min value   :     0
#> max value   :     1

# plot solution
plot(s1, main = "solution", axes = FALSE)
```

--------------------------------

### Add Gurobi solver to a conservation problem

Source: https://prioritizr.net/reference/solvers.html

This example demonstrates how to add the Gurobi solver to a conservation planning problem if the gurobi package is installed.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create basic problem
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_proportion_decisions()

# create vector to store plot names
n <- c()

# create empty list to store solutions
s <- c()

# if gurobi is installed: create problem with added gurobi solver
if (require("gurobi")) {
  p1 <- p %>% add_gurobi_solver(verbose = FALSE)
  n <- c(n, "gurobi")
  s <- c(s, solve(p1))
}
```

--------------------------------

### Add CPLEX solver to a conservation problem

Source: https://prioritizr.net/reference/solvers.html

This example demonstrates how to add the IBM CPLEX solver to a conservation planning problem if the cplexAPI package is installed.

```R
# if cplexAPI is installed: create problem with added CPLEX solver
if (require("cplexAPI")) {
  p2 <- p %>% add_cplex_solver(verbose = FALSE)
  n <- c(n, "CPLEX")
  s <- c(s, solve(p2))
}
```

--------------------------------

### Use CBC solver with and without start_solution

Source: https://prioritizr.net/reference/add_cbc_solver.html

Demonstrates creating a problem with the CBC solver and using a previous solution as a starting point for a new problem with boundary penalties.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create problem
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_cbc_solver(gap = 0, verbose = FALSE)

# generate solution %>%
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create a similar problem with boundary length penalties and
# specify the solution from the previous run as a starting solution
p2 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_boundary_penalties(10) %>%
  add_binary_decisions() %>%
  add_cbc_solver(gap = 0, start_solution = s1, verbose = FALSE)

# generate solution
s2 <- solve(p2)

# plot solution
plot(s2, main = "solution with boundary penalties", axes = FALSE)
```

--------------------------------

### Install Gurobi R package on Windows

Source: https://prioritizr.net/articles/gurobi_installation_guide.html

Install the Gurobi R package from the local zip file provided in the Gurobi installation directory.

```r
install.packages("c:/gurobi800/win64/R/gurobi_8.0-0.zip", repos = NULL)
```

--------------------------------

### Create an optimization problem

Source: https://prioritizr.net/reference/optimization_problem.html

Demonstrates how to initialize an empty optimization problem and how to construct a fully formulated one using a list of parameters.

```R
optimization_problem(x = NULL)
```

```R
# create new empty object
x1 <- optimization_problem()

# print new empty object
print(x1)
#> An optimization problem (<OptimizationProblem>)
#> • model sense: missing
#> • dimensions:  0, 0, 0 (rows, columns, cells)
#> • variables:   none

# create list with optimization problem
l <- list(
  modelsense = "min",
  number_of_features = 2,
  number_of_planning_units = 3,
  number_of_zones = 1,
  A_i = c(0L, 1L, 0L, 1L, 0L, 1L),
  A_j = c(0L, 0L, 1L, 1L, 2L, 2L),
  A_x = c(2, 10, 1, 10, 1, 10),
  obj = c(1, 2, 2),
  lb = c(0, 1, 0),
  ub = c(0, 1, 1),
  rhs = c(2, 10),
  compressed_formulation = TRUE,
  sense = c(">=", ">="),
  vtype = c("B", "B", "B"),
  row_ids = c("spp_target", "spp_target"),
  col_ids = c("pu", "pu", "pu")
)

# create fully formulated object based on lists
x2 <- optimization_problem(l)

# print fully formulated object
print(x2)
#> An optimization problem (<OptimizationProblem>)
#> • model sense: min
#> • dimensions:  2, 3, 6 (rows, columns, cells)
#> • variables:   3 (B)
```

--------------------------------

### Installation of lpsymphony

Source: https://prioritizr.net/reference/add_lsymphony_solver.html

Commands to install the lpsymphony package from Bioconductor using the remotes package.

```R
if (!require(remotes)) install.packages("remotes")
remotes::install_bioc("lpsymphony")
```

--------------------------------

### Create multi-zone maximum cover problem

Source: https://prioritizr.net/reference/add_max_cover_objective.html

This example demonstrates setting up a multi-zone problem with a single budget of 800 for all zones using binary feature data.

```R
# threshold the multi-zone feature data to generate binary biodiversity data
sim_binary_features_zones <- sim_zones_features
for (z in seq_len(number_of_zones(sim_zones_features))) {
  thresholds <- terra::global(
    sim_zones_features[[z]], fun = quantile, probs = 0.5, na.rm = TRUE
  )
  for (i in seq_len(number_of_features(sim_zones_features))) {
    sim_binary_features_zones[[z]][[i]] <- terra::as.int(
      sim_zones_features[[z]][[i]] > thresholds[[1]][[i]]
    )
  }
}

# create multi-zone problem with maximum cover objective that
# has a single budget for all zones
p2 <-
  problem(sim_zones_pu_raster, sim_binary_features_zones) %>%
  add_max_cover_objective(800) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)
```

--------------------------------

### Install HiGHS solver

Source: https://prioritizr.net/

Install the HiGHS solver package from CRAN to enable optimization algorithms.

```R
# if needed, install HiGHS solver
install.packages("highs", repos = "https://cran.rstudio.com/")
```

--------------------------------

### Create and solve a single-zone problem with add_cuts_portfolio

Source: https://prioritizr.net/reference/add_cuts_portfolio.html

This example demonstrates setting up a minimal conservation problem, adding a cuts portfolio to generate 10 solutions within 20% of optimality, and visualizing the results.

```r
set.seed(500)

sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.2) %>%
  add_cuts_portfolio(10) %>%
  add_default_solver(gap = 0.2, verbose = FALSE)

s1 <- solve(p1)
#> Generating solutions ■■■■■■■■■■                       | 3/10 |  30% | ETA: 3s
#> Generating solutions ■■■■■■■■■■■■■■■■                 | 5/10 |  50% | ETA: 2s
#> Generating solutions ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  | 10/10 | 100% | ETA: 0s

s1 <- terra::rast(s1)

plot(s1, axes = FALSE)
```

--------------------------------

### Install cplexAPI package

Source: https://prioritizr.net/reference/add_cplex_solver.html

Use the remotes package to install cplexAPI from its GitHub repository, as it is not available on CRAN.

```r
if (!require(remotes)) install.packages("remotes")
remotes::install_github("cran/cplexAPI")
```

--------------------------------

### Install slam R package

Source: https://prioritizr.net/articles/gurobi_installation_guide.html

Install the slam package from CRAN, which is a dependency for the Gurobi R package.

```r
install.packages("slam", repos = "https://cloud.r-project.org")
```

--------------------------------

### Example: Creating a problem with a default portfolio

Source: https://prioritizr.net/reference/add_default_portfolio.html

Demonstrates how to create a minimal conservation planning problem, add a default portfolio, and solve it.

```R
# set seed for reproducibility
set.seed(600)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create minimal problem with default portfolio
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_default_portfolio() %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem
s <- solve(p)

# plot solution
plot(s)
```

--------------------------------

### Simulate cost data example

Source: https://prioritizr.net/reference/simulate_cost.html

Demonstrates creating a template raster and generating simulated cost data from it, followed by plotting the result.

```R
# create raster
r <- terra::rast(
  ncols = 10, nrows = 10, xmin = 0, xmax = 1, ymin = 0, ymax = 1, vals = 1
)

# simulate data
cost <- simulate_cost(r)

# plot simulated species
plot(cost, main = "simulated cost data", axes = FALSE)
```

--------------------------------

### loglinear_interpolation examples

Source: https://prioritizr.net/reference/loglinear_interpolation.html

Examples demonstrating interpolation of values, calculation of species representation targets, and plotting results.

```R
# create series of x-values
x <- seq(0, 1000)

# interpolate y-values for the x-values given the two reference points:
# (200, 100) and (900, 15)
y <- loglinear_interpolation(x, 200, 100, 900, 15)

# plot the interpolated values
plot(y ~ x)

# add the reference points to the plot (shown in red)
points(x = c(200, 900), y = c(100, 15), pch = 18, col = "red", cex = 2)


# this function can also be used to calculate representation targets
# following Rodrigues et al. (2014). For example, let's say that
# we had a set of species we were interested in calculating representation
# targets for and we had information on their range sizes (in km^2).
spp_range_size_km2 <- seq(0.01, 15000000, by = 100)

# we can now use this function to calculate representation targets
# (expressed as a percentage of the species' range sizes) using
# the thresholds and cap sizes reported by Rodrigues et al. 2014
spp_target_percentage_rodrigues <- loglinear_interpolation(
    x = spp_range_size_km2,
    coordinate_one_x = 1000,
    coordinate_one_y = 1,
    coordinate_two_x = 250000,
    coordinate_two_y = 0.1
) * 100

# it is also common to apply a cap to the representation targets,
# so let's apply the cap these targets following Butchart et al. (2015)
spp_target_percentage_butchart <- ifelse(
  spp_range_size_km2 >= 10000000,
  (1000000 / spp_range_size_km2) * 100,
  spp_target_percentage_rodrigues
)

# plot species range sizes and representation targets
plot(
  spp_target_percentage_butchart ~ spp_range_size_km2,
  xlab = "Range size km^2" , ylab = "Representation target (%)", type = "l"
)


# plot species range sizes and representation targets on a log10 scale
plot(
  spp_target_percentage_butchart ~ log10(spp_range_size_km2),
  xlab = "Range size km^2" , ylab = "Representation target (%)",
  type = "l", xaxt = "n"
)
axis(
  1, pretty(log10(spp_range_size_km2)),
  10^pretty(log10(spp_range_size_km2))
)
```

--------------------------------

### Example: Top portfolio for a multi-zone problem

Source: https://prioritizr.net/reference/add_top_portfolio.html

Demonstrates creating a multi-zone problem with a portfolio for the top 5 solutions, solving it, and plotting the results.

```R
# create multi-zone problem with a portfolio for the top 5 solutions
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(matrix(runif(15, 0.1, 0.2), nrow = 5, ncol = 3)) %>%
  add_top_portfolio(number_solutions = 5) %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem and generate portfolio
s2 <- solve(p2)

# convert each solution in the portfolio into a single category layer
s2 <- terra::rast(lapply(s2, category_layer))

# print number of solutions found
print(terra::nlyr(s2))
#> [1] 5

# plot solutions in portfolio
plot(s2, axes = FALSE)
```

--------------------------------

### simulate_species example

Source: https://prioritizr.net/reference/simulate_species.html

Demonstrates creating a template raster and simulating distributions for 4 species, followed by plotting the results.

```R
# create raster
r <- terra::rast(
  ncols = 10, nrows = 10, xmin = 0, xmax = 1, ymin = 0, ymax = 1, vals = 1
)

# simulate data for 4 species
spp <- simulate_species(r, 4)

# plot simulated species
plot(spp, main = "simulated species distributions", axes = FALSE)
```

--------------------------------

### Examples of add_binary_decisions

Source: https://prioritizr.net/reference/add_binary_decisions.html

Demonstrates creating a minimal problem with binary decisions and a multi-zone conservation problem using binary decisions.

```R
# set seed for reproducibility
set.seed(500)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with binary decisions
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create a matrix with targets for a multi-zone conservation problem
targs <- matrix(runif(15, 0.1, 0.2), nrow = 5, ncol = 3)

# build multi-zone conservation problem with binary decisions
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(targs)  %>
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve the problem
s2 <- solve(p2)

# print solution
print(s2)
#> class       : SpatRaster
#> size        : 10, 10, 3  (nrow, ncol, nlyr)
#> resolution  : 0.1, 0.1  (x, y)
#> extent      : 0, 1, 0, 1  (xmin, xmax, ymin, ymax)
#> coord. ref. : WGS 84 / Pseudo-Mercator (EPSG:3857)
#> source(s)   : memory
#> varnames    : sim_zones_pu_raster
#>               sim_zones_pu_raster
#>               sim_zones_pu_raster
#> names       : zone_1, zone_2, zone_3
#> min values  :      0,      0,      0
#> max values  :      1,      1,      1

# plot solution
plot(category_layer(s2), main = "solution", axes = FALSE)
```

--------------------------------

### Verify Gurobi installation on Linux and MacOS

Source: https://prioritizr.net/articles/gurobi_installation_guide.html

Run the gurobi_cl command to verify that Gurobi is correctly installed and licensed.

```bash
gurobi_cl /opt/gurobi800/linux64/examples/data/coins.lp
```

--------------------------------

### Example: Top portfolio for a single-zone problem

Source: https://prioritizr.net/reference/add_top_portfolio.html

Demonstrates creating a minimal problem with a portfolio for the top 5 solutions, solving it, and plotting the results.

```R
# set seed for reproducibility
set.seed(600)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with a portfolio for the top 5 solutions
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_top_portfolio(number_solutions = 5) %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem and generate portfolio
s1 <- solve(p1)

# convert portfolio into a multi-layer raster
s1 <- terra::rast(s1)

# print number of solutions found
print(terra::nlyr(s1))
#> [1] 5

# plot solutions
plot(s1, axes = FALSE)
```

--------------------------------

### Examples of add_min_largest_shortfall_objective

Source: https://prioritizr.net/reference/add_min_largest_shortfall_objective.html

Examples demonstrating the use of the objective in single-zone and multi-zone conservation problems with various budget configurations.

```R
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create problem with minimum largest shortfall objective
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_largest_shortfall_objective(1800) %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution", axes = FALSE)


# create multi-zone problem with minimum largest shortfall objective,
# with 10% representation targets for each feature, and set
# a budget such that the total maximum expenditure in all zones
# cannot exceed 1800
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_largest_shortfall_objective(1800) %>%
  add_relative_targets(matrix(0.1, ncol = 3, nrow = 5)) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s2 <- solve(p2)

# plot solution
plot(category_layer(s2), main = "solution", axes = FALSE)


# create multi-zone problem with minimum largest shortfall objective,
# with 10% representation targets for each feature, and set
# separate budgets of 1800 for each management zone
p3 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_largest_shortfall_objective(c(1800, 1800, 1800)) %>%
  add_relative_targets(matrix(0.1, ncol = 3, nrow = 5)) %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# solve problem
s3 <- solve(p3)

# plot solution
plot(category_layer(s3), main = "solution", axes = FALSE)
```

--------------------------------

### Load required packages

Source: https://prioritizr.net/articles/management_zones_tutorial.html

Initializes the environment by loading the prioritizr and terra packages.

```R
# load packages
library(prioritizr)
library(terra)
```

--------------------------------

### Install rcbc package

Source: https://prioritizr.net/reference/add_cbc_solver.html

The rcbc package is required for the CBC solver and must be installed from GitHub using the remotes package.

```R
if (!require(remotes)) install.packages("remotes")
remotes::install_github("dirkschumacher/rcbc")
```

--------------------------------

### Examples of add_shuffle_portfolio

Source: https://prioritizr.net/reference/add_shuffle_portfolio.html

Demonstrates creating a minimal problem and a multi-zone conservation problem using the shuffle portfolio strategy.

```R
# set seed for reproducibility
set.seed(500)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
sim_zones_pu_raster <- get_sim_zones_pu_raster()
sim_zones_features <- get_sim_zones_features()

# create minimal problem with shuffle portfolio
p1 <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.2) %>%
  add_shuffle_portfolio(10) %>%
  add_default_solver(gap = 0.2, verbose = FALSE)

# solve problem and generate 10 solutions within 20% of optimality
s1 <- solve(p1)
#> Generating solutions ■■■■■■■■■■                       | 3/10 |  30% | ETA: 3s
#> Generating solutions ■■■■■■■■■■■■■■■■■■■■■■■■■■■■     | 9/10 |  90% | ETA: 0s
#> Generating solutions ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  | 10/10 | 100% | ETA: 0s

# convert portfolio into a multi-layer raster
s1 <- terra::rast(s1)

# print number of solutions found
print(terra::nlyr(s1))
#> [1] 10

# plot solutions in portfolio
plot(s1, axes = FALSE)


# build multi-zone conservation problem with shuffle portfolio
p2 <-
  problem(sim_zones_pu_raster, sim_zones_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(matrix(runif(15, 0.1, 0.2), nrow = 5, ncol = 3)) %>%
  add_binary_decisions() %>%
  add_shuffle_portfolio(10) %>%
  add_default_solver(gap = 0.2, verbose = FALSE)

# solve the problem
s2 <- solve(p2)
#> Generating solutions ■■■■■■■■■■■■■■■■■■■              | 6/10 |  60% | ETA: 2s
#> Generating solutions ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  | 10/10 | 100% | ETA: 0s

# convert each solution in the portfolio into a single category layer
s2 <- terra::rast(lapply(s2, category_layer))

# print number of solutions found
print(terra::nlyr(s2))
#> [1] 10

# plot solutions in portfolio
plot(s2, axes = FALSE)
```

--------------------------------

### spec_area_targets examples

Source: https://prioritizr.net/reference/spec_area_targets.html

Examples demonstrating how to set constant area targets for all features and varying area targets for each feature individually.

```R
# set seed for reproducibility
set.seed(500)

# load data
sim_complex_pu_raster <- get_sim_complex_pu_raster()
sim_complex_features <- get_sim_complex_features()

# create base problem
p0 <-
  problem(sim_complex_pu_raster, sim_complex_features) %>%
  add_min_set_objective() %>%
  add_binary_decisions() %>%
  add_default_solver(verbose = FALSE)

# create problem with targets of 50 km^2 for each feature
p1 <-
  p0 %>%
  add_auto_targets(
    method = spec_area_targets(targets = 50, area_units = "km^2")
  )

# solve problem
s1 <- solve(p1)

# plot solution
plot(s1, main = "solution based on constant targets", axes = FALSE)


# targets can also be specified for each feature separately.
# to demonstrate this, we will set a target value for each
# feature based on a random number between 5000 and 30000 hectares
target_values <- runif(terra::nlyr(sim_complex_features), 5000, 30000)

# create problem with targets defined separately for each feature
p2 <-
  p0 %>%
  add_auto_targets(
    method = spec_area_targets(targets = target_values, area_units = "ha")
  )

# solve problem
s2 <- solve(p2)

# plot solution
plot(s2, main = "solution based on varying targets", axes = FALSE)
```

--------------------------------

### Examples of as_km2 conversions

Source: https://prioritizr.net/reference/as_km2.html

Examples demonstrating conversion from various units like km2, acres, and hectares to square kilometers.

```R
as_km2(5, "km2")
#> [1] 5
as_km2(5, "acres")
#> [1] 0.02023436
as_km2(c(5, 10), "ha")
#> [1] 0.05 0.10
as_km2(c(5, 10), c("ha", "acres"))
#> [1] 0.05000000 0.04046873
```

--------------------------------

### Example: Adding a single portfolio to a problem

Source: https://prioritizr.net/reference/add_single_portfolio.html

Demonstrates creating a minimal conservation planning problem, adding a single portfolio, and solving it.

```R
# set seed for reproducibility
set.seed(600)

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create minimal problem with default portfolio
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.05) %>%
  add_single_portfolio() %>%
  add_default_solver(gap = 0, verbose = FALSE)

# solve problem
s <- solve(p)

# plot solution
plot(s)
```