Logo by Camille Salmon
The restoptr R package provides a flexible framework for
ecological restoration planning. It aims to identify priority areas for
restoration efforts using optimization algorithms (based on
Justeau-Allaire et al. 2021). Priority areas can be identified
by maximizing landscape indices, such as the effective mesh size (Jaeger
2000), or the integral index of connectivity (Pascual-Hortal & Saura
2006). Additionally, constraints can be used to ensure that priority
areas exhibit particular characteristics (e.g., ensure that particular
places are not selected for restoration, ensure that priority areas form
a single contiguous network). Furthermore, multiple near-optimal
solutions can be generated to explore multiple options in restoration
planning. The package leverages the Choco-solver software to perform
optimization using constraint programming (CP) techniques (Prud’homme
et al. 2016).
The latest official version of the restoptr R package can be installed from the Comprehensive R Archive Network (CRAN) using the following R code.
install.packages("restoptr", repos = "https://cran.rstudio.com/")Alternatively, the latest developmental version can be installed using the following R code. Please note that while developmental versions may contain additional features not present in the official version, they may also contain coding errors.
if (!require(remotes)) install.packages("remotes")
remotes::install_github("dimitri-justeau/restoptr")The packages requires a Java Runtime Environment (JRE), version 8 or higher. Below we provide platform-specific instructions to install it.
Please install the latest Java Runtime Environment for Windows (see
Oracle JDK, OpenJDK, or GraalVM). You also need to
install Maven. After downloading
the file, please run installer to install Java on your system. You will
also need to ensure that the PATH environmental variable if
configured so that R can access Java. restoptr relies
on rJava for the communication between R and
Java. If you have any trouble during the installation of
restopt due to rJava, please refer to rJava’s
documentation: https://rforge.net/rJava/index.html.
For recent versions of Ubuntu (18.04 and later), the Java libraries are available through official repositories. They can be installed using the following system commands.
sudo apt-get install default-jdkIf you want to install a specific JRE version, please follow instructions from Oracle, OpenJDK, or GraalVM.
Please follow instructions from Oracle, OpenJDK, or GraalVM.
The easiest way to install the Java libraries is using HomeBrew. After installing HomeBrew, the Java libraries can be installed using the following system commands.
brew install openjdkPlease note that you might also need to ensure that the
PATH environmental variable if configured so that
R can access Java.
The package relies on a core Java library called restopt.
This Java library handles the constrained optimization process via the
Choco-solver software. Although
this library is automatically included with the package, it can be
manually compile from source if needed. Please note that this
step is entirely optional, and is not needed to install the
package. To compile the Java library, a the Maven software needs to be
installed as well as a Java Development Kit (JDK) (version 8+) is
required (e.g., see Oracle JDK, OpenJDK, or GraalVM). After installing
these dependencies, the following procedures can be used to compile the
Java library and it along with the package.
First clone the repository and update the source code.
git clone https://github.com/dimitri-justeau/restoptr.git
cd restoptr
git submodule update --init --recursive
git pull --recurse-submodulesNext, compile the core Java library with Maven.
cd restopt
mvn clean package -DskipTestsNext, copy the resulting Java library (.jar) file into
java directory.
cp target/restopt-*.jar ../java/Finally, the package can be installed with the newly compiled Java library using the following R command.
if (!require(remotes)) install.packages("remotes")
remotes::install_local(".")Here we will provide a short tutorial on using the restoptr R package to identify priority areas for restoration. As part of this tutorial, we will use an example dataset that is distributed with the package (obtained from Justeau-Allaire et al. 2021). This example dataset contains data for prioritizing forest restoration efforts within a protected area in New Caledonia. We will begin the tutorial by loading the package. If you haven’t already, please install the package (see above for installation instructions).
# load package
library(restoptr)To identify priorities for restoration, we require information on the
location of places that do and do not currently contain suitable
habitat. We will now import data to describe which places within the
protected area contain forest habitat (imported as the
habitat_data object). Specifically, this object is a
spatial grid (i.e., raster layer). Each grid cell corresponds to a
candidate place for restoration (termed planning unit), and their values
indicate the absence or presence of forest within each planning unit
(using values of zero and one, respectively).
# import data
habitat_data <- rast(
system.file("extdata", "habitat_hi_res.tif", package = "restoptr")
)
# preview data
print(habitat_data)## class : SpatRaster
## dimensions : 1867, 2713, 1 (nrow, ncol, nlyr)
## resolution : 27.9487, 29.74339 (x, y)
## extent : 419768.2, 495593.1, 227538.9, 283069.8 (xmin, xmax, ymin, ymax)
## coord. ref. : RGNC91-93 / Lambert New Caledonia (EPSG:3163)
## source : habitat_hi_res.tif
## name : habitat_hi_res# visualize data
plot(habitat_data, plg = list(x = "topright"))
Restoration efforts are often limited in terms of the places where
they can be implemented. For example, restoration efforts may not be
feasible in dense cities. In our example, some places are not feasible
for restoration because they cannot be accessed by existing tracks
within the protected area. We will now import data to describe which
places are not feasible for restoration (imported as the
locked_out_data object). This object – similar to the
habitat data – is a spatial grid. The grid cell values in this object
indicate which planning units should be considered available for
restoration or not (using values of zero and one, respectively).
# import data
locked_out_data <- rast(
system.file("extdata", "locked_out.tif", package = "restoptr")
)
# preview data
print(locked_out_data)## class : SpatRaster
## dimensions : 1867, 2713, 1 (nrow, ncol, nlyr)
## resolution : 27.9487, 29.74339 (x, y)
## extent : 419768.2, 495593.1, 227538.9, 283069.8 (xmin, xmax, ymin, ymax)
## coord. ref. : RGNC91-93 / Lambert New Caledonia (EPSG:3163)
## source : locked_out.tif
## name : layer
## min value : 1
## max value : 1# visualize data
plot(locked_out_data, plg = list(x = "topright"))
We now will build a restoration optimization problem (stored in the
problem object). This object will specify all the data,
settings, and optimization criteria for identifying priority areas.
Specifically, we will initialize the problem with the
habitat_data object to specify which planning units already
contain suitable habitat (with the restopt_problem()
function). To reduce run time, we will also initialize it with
parameters to aggregate the spatial data (i.e.,
aggregation_factor and habitat_threshold).
Next, we will specify that the objective function for the optimization
process is to maximize connectivity based on the effective mesh size
metric (with the set_max_mesh_objective() function). We
will then specify constraints to ensure that the priority areas exhibit
particular characteristics. These constraints will be used to ensure
that (i) certain planning units are not selected for restoration (with
the add_locked_out_constraint() function), (ii) the total
amount of restored area should range between 90 and 220 ha (with the
add_restorable_constraint() function), and (iii) limit the
spatial extent of the priority areas to be within 2.4 km (with the
add_compactness_constraint() function).
# build restoration optimization problem
problem <-
## initialize problem with habitat data
restopt_problem(
existing_habitat = habitat_data,
aggregation_factor = 16,
habitat_threshold = 0.7
) %>%
## set objective function is to maximize effective mesh size
set_max_mesh_objective() %>%
## add constraint to ensure that certain places are not selected
add_locked_out_constraint(locked_out_data) %>%
## add constraint to limit total amount of restored area
add_restorable_constraint(90, 220, unit = "ha") %>%
## add constraint to limit spatial extent of priority areas
add_compactness_constraint(2.4, unit = "km")
# preview problem
print(problem)## -----------------------------------------------------------------
## Restopt
## -----------------------------------------------------------------
## original habitat: habitat_hi_res.tif
## aggregation factor: 16
## habitat threshold: 0.7
## existing habitat: in memory
## restorable habitat: in memory
## -----------------------------------------------------------------
## objective: Maximize effective mesh size
## -----------------------------------------------------------------
## constraints:
## - locked out (data = in memory)
## - restorable (min_restore = 90, max_restore = 220, min_proportion = 1, unit = ha)
## - compactness (max_diameter = 2.4, unit = km)
## -----------------------------------------------------------------
## settings:
## - precision = 4
## - time_limit = 0
## - nb_solutions = 1
## - optimality_gap = 0
## - solution_name_prefix = Solution
## -----------------------------------------------------------------After building the problem, we can solve it to identify priority
areas for restoration (with the solve() function). The
solution is a raster layer containing values that indicate if planning
units: (0) were locked out, (1) do not contain
existing habitat, (2) contain existing habitat, or
(3) selected as a priority area for restoration.
# solve problem to identify priority areas
solution <- solve(problem)## Good news: the solver found 1 solution statisfying the constraints that was proven optimal ! (solving time = 0.97 s)# preview solution
print(solution)## class : RestoptSolution
## dimensions : 117, 170, 1 (nrow, ncol, nlyr)
## resolution : 447.1792, 475.8943 (x, y)
## extent : 419768.2, 495788.7, 227390.1, 283069.8 (xmin, xmax, ymin, ymax)
## coord. ref. : RGNC91-93 / Lambert New Caledonia (EPSG:3163)
## source(s) : memory
## categories : label
## name : Solution 1
## min value : Locked out
## max value : Restoration# visualize solution
plot(
solution,
main = "Solution",
col = c("#E5E5E5", "#fff1d6", "#b2df8a", "#1f78b4"),
plg = list(x = "topright")
)
Finally, we can access additional information on the solution (with
the get_metadata() function).
# access information on the solution
## N.B. spatial units are expressed as hectares
get_metadata(solution, area_unit = "ha")## min_restore total_restorable nb_planning_units nb_components diameter
## 1 219.3772 [ha] 219.3772 [ha] 15 3 2280.175 [m]
## optimality_proven search_state solving_time mesh_initial mesh
## 1 TRUE TERMINATED 0.944 13667.84 [ha] 14232.66 [ha]
## mesh_best
## 1 14232.66 [ha]This has just been a short taster of the package. For an extended tutorial on using the package, please refer to the vignette.
Please cite the restoptr R package when using it in publications.
Justeau‐Allaire, D., Hanson, J. O., Lannuzel, G., Vismara, P., Lorca, X., & Birnbaum, P. (2023). restoptr: an R package for ecological restoration planning. Restoration Ecology, e13910. https://doi.org/10.1111/rec.13910
If you have any questions about using the package, suggestions for improvements, or if you detect a bug, please open an issue in online code repository. We designed the package to make it relatively easy to add new functionality, and would be delighted to hear from you.
Jaeger, J. A. G. (2000). Landscape division, splitting index, and effective mesh size: New measures of landscape fragmentation. Landscape Ecology, 15(2), 115-‑130.
Justeau-Allaire, D., Vieilledent, G., Rinck, N., Vismara, P., Lorca, X., & Birnbaum, P. (2021). Constrained optimization of landscape indices in conservation planning to support ecological restoration in New Caledonia. Journal of Applied Ecology, 58(4), 744‑-754.
Pascual-Hortal, L., & Saura, S. (2006). Comparison and development of new graph-based landscape connectivity indices: Towards the priorization of habitat patches and corridors for conservation. Landscape Ecology, 21(7), 959-‑967.
Prud’homme, C., Fages, J.-G., & Lorca, X. (2016). Choco Solver Documentation. {TASC, INRIA Rennes, LINA CNRS UMR 6241, COSLING S.A.S. Available at https://choco-solver.org/.