Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dimitri-justeau/restoptr
R package for ecological restoration planning
https://github.com/dimitri-justeau/restoptr
Last synced: 3 months ago
JSON representation
R package for ecological restoration planning
- Host: GitHub
- URL: https://github.com/dimitri-justeau/restoptr
- Owner: dimitri-justeau
- License: gpl-3.0
- Created: 2021-11-26T06:09:40.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-06T09:36:50.000Z (about 1 year ago)
- Last Synced: 2024-06-11T16:27:52.701Z (5 months ago)
- Language: R
- Homepage: https://dimitri-justeau.github.io/restoptr/
- Size: 61.9 MB
- Stars: 11
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE.md
Awesome Lists containing this project
- open-sustainable-technology - restoptr - Aims to identify priority areas for restoration efforts using optimization algorithms. (Biosphere / Conservation and Restoration)
README
---
output:
rmarkdown::github_document:
html_preview: no
---
```{r, include = FALSE}
knitr::opts_chunk$set(fig.path = "man/figures/README-", fig.align = "center",
fig.height = 4.5, fig.width = 4.5)
```
# restopr 
## Ecological Restoration Planning
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://github.com/dimitri-justeau/restoptr/actions)
[](https://github.com/dimitri-justeau/restoptr/actions)
[](https://github.com/dimitri-justeau/restoptr/actions)
[](https://app.codecov.io/gh/dimitri-justeau/restoptr)
[](https://github.com/dimitri-justeau/restoptr)
[](https://CRAN.R-project.org/package=restoptr)
```{r, include = FALSE}
devtools::load_all()
```
Logo by Camille Salmon
## Overview
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](https://choco-solver.org/) software to perform optimization using constraint programming (CP) techniques (Prud'homme _et al._ 2016).
## Installation
### Package installation
The latest official version of the _restoptr R_ package can be installed from the [Comprehensive R Archive Network (CRAN)](https://cran.r-project.org/) using the following _R_ code.
```{r, eval = FALSE}
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.
```{r, eval = FALSE}
if (!require(remotes)) install.packages("remotes")
remotes::install_github("dimitri-justeau/restoptr")
```
### System dependencies
The packages requires a Java Runtime Environment (JRE), version 8 or higher. Below we provide platform-specific instructions to install it.
#### _Windows_
Please install the latest Java Runtime Environment for Windows (see Oracle JDK, [OpenJDK](https://openjdk.org/install/), or [GraalVM](https://www.graalvm.org/downloads/)). You also need to install [Maven](https://maven.apache.org/). 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.
#### _Ubuntu_
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.
```{bash, eval = FALSE}
sudo apt-get install default-jdk
```
If you want to install a specific JRE version, please follow instructions from Oracle, [OpenJDK](https://openjdk.org/install/), or [GraalVM](https://www.graalvm.org/downloads/).
#### _Linux_
Please follow instructions from Oracle, [OpenJDK](https://openjdk.org/install/), or [GraalVM](https://www.graalvm.org/downloads/).
#### _MacOS_
The easiest way to install the Java libraries is using [HomeBrew](https://brew.sh/). After installing HomeBrew, the Java libraries can be installed using the following system commands.
```{bash, eval = FALSE}
brew install openjdk
```
Please note that you might also need to ensure that the `PATH` environmental variable if configured so that _R_ can access Java.
### Building the Java core library from source (optional)
The package relies on a core Java library called [`restopt`](https://github.com/dimitri-justeau/restopt). This Java library handles the constrained optimization process via the [Choco-solver](https://choco-solver.org/) 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](https://maven.apache.org/) software needs to be installed as well as a Java Development Kit (JDK) (version 8+) is required (e.g., see Oracle JDK, [OpenJDK](https://openjdk.org/install/), or [GraalVM](https://www.graalvm.org/downloads/)). 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.
```{bash, eval = FALSE}
git clone https://github.com/dimitri-justeau/restoptr.git
cd restoptr
git submodule update --init --recursive
git pull --recurse-submodules
```
Next, compile the core Java library with Maven.
```{bash, eval = FALSE}
cd restopt
mvn clean package -DskipTests
```
Next, copy the resulting Java library (.jar) file into `java` directory.
```{bash, eval = FALSE}
cp target/restopt-*.jar ../java/
```
Finally, the package can be installed with the newly compiled Java library using the following _R_ command.
```{r, eval = FALSE}
if (!require(remotes)) install.packages("remotes")
remotes::install_local(".")
```
## Usage
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).
```{r "load_package"}
# 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).
```{r "habitat_data", out.width = "100%", fig.width = 10}
# import data
habitat_data <- rast(
system.file("extdata", "habitat_hi_res.tif", package = "restoptr")
)
# preview data
print(habitat_data)
# 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).
```{r "locked_out_data", out.width = "100%", fig.width = 10}
# import data
locked_out_data <- rast(
system.file("extdata", "locked_out.tif", package = "restoptr")
)
# preview data
print(locked_out_data)
# 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).
```{r "problem"}
# 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)
```
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.
```{r "solution", out.width = "100%", fig.width = 10}
# solve problem to identify priority areas
solution <- solve(problem)
# preview solution
print(solution)
# 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).
```{r "metadata"}
# access information on the solution
## N.B. spatial units are expressed as hectares
get_metadata(solution, area_unit = "ha")
```
This has just been a short taster of the package. For an extended tutorial on using the package, please refer to the vignette.
## Citation
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
## Getting help
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](https://github.com/dimitri-justeau/restoptr/issues/new/choose). We designed the package to make it relatively easy to add new functionality, and would be delighted to hear from you.
## References
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 .