Restoration optimization problem — restopt

Create a new restoration optimization problem (RestoptProblem) using data that describe the spatial distribution of existing habitat (potentially at high resolution), and parameters to derive a downsampled existing habitat raster, suitable for a tractable optimization, and a restorable habitat raster. Constraints can be added to a restopt problem using add_****_constraint() functions, and an optimization objective can be set using set_****_objective() functions.

Usage

restopt_problem(
  existing_habitat,
  habitat_threshold = 1,
  aggregation_factor = 1
)

Arguments

existing_habitat: terra::rast() Raster object containing binary values that indicate if each planning unit contains habitat or not. Cells with the value 1 must correspond to existing habitat. Cells with the value 0 must correspond to degraded (or simply non-habitat) areas. Finally, NA (or NO_DATA) cells are considered to be outside of the landscape. This raster can have a high resolution, the aggregation_factor and the habitat_threshold parameters, described below, will be used to down sample the habitat raster to a tractable resolution for the optimization engine, and automatically derive the restorable habitat raster.
habitat_threshold: numeric number between 0 and 1, which corresponds to the minimum proportion of habitat that must be present within an aggregated pixel to consider it as an habitat pixel.
aggregation_factor: integer Integer greater than 1, which corresponds to the aggregation factor for down sampling the data. For example, if aggregation_factor = 2, aggregated pixel will contain 4 original pixel. See terra::aggregate() for more details.

Value

A new restoration problem (RestoptProblem) object.

None.

Details

This function creates the base restoration optimization problem object, that can be further extended with constraints and optimization objectives. One input rasters is necessary to instantiate a restopt problem: the existing_habitat raster (potentially with high resolution). This raster must contains data about where are habitat areas (raster value 1), non-habitat areas (raster value 0), and areas that must not be considered during the solving procedure (NA or NO_DATA). The aggregation_factor parameter is used to down sample the existing_habitat to a resolution that will be tractable for the optimization engine, and the habitat_threshold parameter indicates the minimum proportion of habitat required in aggregated habitat pixels to consider them as habitat. Note that An aggregated pixel will contain at most aggregation_factor^2 pixels from the input habitat raster (cell_area raster in this function outputs). If an aggregated pixel is close to the spatial boundaries of the problem (i.e. NA cells), it can contain less than aggregation_factor^2 fine grained pixel. You can get the results of this preprocessing phase using the following methods: get_original_habitat() (original habitat), get_existing_habitat() (aggregated habitat), get_cell_area() (number of pixels in each aggregated cells), and get_restorable_area() (amount of restorable area -- in number of original raster pixels).

Examples

# \donttest{
# load data
habitat_data <- rast(
  system.file("extdata", "habitat_hi_res.tif", package = "restoptr")
)

# create problem
p <- restopt_problem(
       existing_habitat = habitat_data,
       aggregation_factor = 4,
       habitat_threshold = 0.7
)

# Plot down sampled data
plot(c(p$data$existing_habitat, p$data$restorable_habitat))


# print problem
print(p)
#> ----------------------------------------------------------------- 
#>                          Restopt                          
#> ----------------------------------------------------------------- 
#> original habitat:     habitat_hi_res.tif 
#> aggregation factor:   4 
#> habitat threshold:    0.7 
#> existing habitat:     in memory 
#> restorable habitat:   in memory 
#> ----------------------------------------------------------------- 
#> objective:            No optimization objective 
#> ----------------------------------------------------------------- 
#> constraints:         none defined 
#> ----------------------------------------------------------------- 
#> settings: 
#>   - precision = 4
#>   - time_limit = 0
#>   - nb_solutions = 1
#>   - optimality_gap = 0
#>   - solution_name_prefix = Solution  
#> ----------------------------------------------------------------- 
# }