https://github.com/prioritizr/aoh
Create Area of Habitat Data
https://github.com/prioritizr/aoh
conservation data ecology gis-data rstats rstats-package
Last synced: about 2 months ago
JSON representation
Create Area of Habitat Data
- Host: GitHub
- URL: https://github.com/prioritizr/aoh
- Owner: prioritizr
- Created: 2021-09-30T22:23:06.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-01-07T02:19:54.000Z (5 months ago)
- Last Synced: 2025-03-28T12:51:15.291Z (2 months ago)
- Topics: conservation, data, ecology, gis-data, rstats, rstats-package
- Language: R
- Homepage: https://prioritizr.github.io/aoh
- Size: 135 MB
- Stars: 11
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
Awesome Lists containing this project
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,
dev = "ragg_png"
)
```
## aoh: Create Area of Habitat Data
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://github.com/prioritizr/aoh/actions)
[](https://github.com/prioritizr/aoh/actions)
[](https://github.com/prioritizr/aoh/actions)
[](https://github.com/prioritizr/aoh/actions)
[](https://app.codecov.io/gh/prioritizr/aoh/branch/master)
```{r, include = FALSE}
# load developmental version of package
devtools::load_all()
# check if being prepared for website
## see https://github.com/r-lib/pkgdown/blob/main/R/pkgdown.R
in_pkgdown <- function() {
identical(Sys.getenv("IN_PKGDOWN"), "true")
}
```
### Overview
Area of Habitat (AOH) maps aim to delineate the spatial distribution of suitable habitat for a species ([Brooks *et al.* 2019](https://doi.org/10.1016/j.tree.2019.06.009)). They are used to assess performance of protected area systems, measure impacts of threats to biodiversity, and identify priorities for conservation actions (e.g., [Rondinini *et al.* 2005](https://doi.org/10.1111/j.1523-1739.2005.00204.x); [Tracewski *et al.* 2016](https://doi.org/10.1111/cobi.12715); [Durán *et al.* 2021](https://doi.org/10.1111/2041-210X.13427)). These maps are generally produced by obtaining geographic range data for a species, and then removing areas that do not contain suitable habitat or occur outside the known elevational limits for the species ([Brooks *et al.* 2019](https://doi.org/10.1016/j.tree.2019.06.009)). To help make these maps accessible, the _aoh R_ package provides routines for automatically creating Area of Habitat data based on the [International Union for Conservation of Nature (IUCN) Red List of Threatened Species](https://www.iucnredlist.org/). After manually downloading species range data from the [IUCN Red List](https://www.iucnredlist.org/resources/spatial-data-download), users can import them (using `read_spp_range_data()`), prepare them and collate additional information for subsequent processing (using `create_spp_info_data()`), and then create Area of Habitat data (using `create_spp_aoh_data()`). Global elevation and habitat classification data ([Jung *et al.* 2020](https://doi.org/10.1038/s41597-020-00599-8); [Lumbierres *et al.* 2021](https://doi.org/10.1111/cobi.13851); [Robinson *et al.* 2014](https://doi.org/10.1016/j.isprsjprs.2013.11.002)) are automatically downloaded, and data on species' habitat preferences and elevational limits are obtained automatically using the [IUCN Red List API](https://apiv3.iucnredlist.org/). Since accessing the IUCN Red List requires a token, users may need to [obtain a token](https://apiv3.iucnredlist.org/) and update their _R_ configuration to recognize the token (see installation instructions below for details).
### Installation
#### Package installation
The [latest developmental version of the _aoh R_ package](https://github.com/prioritizr/aoh) can be installed using the following _R_ code. Please note that it requires the [_sf_](https://CRAN.R-project.org/package=sf), [_terra_](https://CRAN.R-project.org/package=terra), and [_zen4R_](https://CRAN.R-project.org/package=zen4R) _R_ packages, which may require additional software to be installed. If you encounter problems installing these dependencies, please consult their installation instructions.
```{r, eval = FALSE}
if (!require(remotes)) install.packages("remotes")
remotes::install_github("prioritizr/aoh")
```
#### Optional dependencies
The _aoh R_ package can leverage the _prepr R_ package to augment data cleaning procedures. Since the _prepr R_ package is not available on the Comprehensive R Archive Network (CRAN), it is listed as an optional dependency. In some cases, the _prepr R_ package is required to complete the data cleaning procedures (e.g., to fix especially extreme geometry issues) and the _aoh R_ package will throw an error if the package is not available. To install the _prepr R_ package, please use the following _R_ code. Note that the _prepr R_ package has system dependencies that need to be installed before the package itself can be installed (see below for platform-specific instructions).
```{r, eval = FALSE}
if (!require(remotes)) install.packages("remotes")
remotes::install_github("prioritizr/prepr")
```
The package can also leverage the [Geospatial Data Abstraction Library (GDAL)](https://gdal.org/) and [Geographic Resources Analysis Support System (GRASS)](https://grass.osgeo.org/) to help reduce processing time. Although use of these software is optional, they can help improve computational performance when processing data across large spatial extents. Below we provide platform-specific instructions to install dependencies for the _prepr R_ package, GDAL, and GRASS.
##### _Windows_
The [Rtools](https://cran.r-project.org/bin/windows/Rtools/) software needs to be installed to install the _prepr R_ package package. This software provides system requirements from [rwinlib](https://github.com/rwinlib/). Additionally, the easiest way to install GDAL and GRASS is through [OSGeo4W](https://www.osgeo.org/). [Download the OSGeo4W installer](https://trac.osgeo.org/osgeo4w/), select the "Express Install" option, and then follow the prompts to complete the installation. After the installation process has finished, please restart your computer. If the `aoh::is_gdal_calc_available()` function cannot find GDAL, you may also need to update the `PATH` environmental variable so that it contains the folder path for GDAL (default folder path is `C:\OSGeo4W\bin`),
##### _Ubuntu_
For recent versions of Ubuntu (18.04 and later), the libraries are available through official repositories. They can be installed using the following system commands.
```
apt-get -y update
apt-get install -y \
libgdal-dev libgeos-dev libproj-dev gdal-bin grass \
libgmp3-dev libmpfr-dev libudunits2-dev
```
##### _Linux_
For Unix-alikes, `gdal` (>= 3.0.2), `gmp` (>= 4.2.3), `grass` (>= 7.8.7), and `mpfr` (>= 3.0.0) are required.
##### _MacOS_
The easiest way to install the libraries is using [HomeBrew](https://brew.sh/). After installing HomeBrew, the libraries can be installed using the following system commands.
```
brew tap osgeo/osgeo4mac
brew install pkg-config
brew install gdal
brew install osgeo-grass
brew install gmp
brew install mpfr
```
#### Accessing the IUCN Red List API
After installing the _aoh R_ package, you will need to obtain a token for the [IUCN Red List API](https://apiv3.iucnredlist.org/) (if you do not have one already). To do so, please visit the IUCN API website (), click the "Generate a token" link at the top of the web page, and fill out the form to apply for a token. You should then receive a token shortly after completing the form (but not immediately). After receiving a token, please open the `.Renviron` file on your computer (e.g., using `usethis::edit_r_environ()`). Next, please add the following text to the file (replacing the string with the token) and save the file, using your token in place of the string below.
```
IUCN_REDLIST_KEY="your_actual_token_not_this_string"
```
Please restart your R session. You should now be able to access the IUCN Red List API. To verify this, please try running the following _R_ code and -- assuming everything works correctly -- you should the same output below.
```{r, eval = FALSE}
# verify access to IUCN Red List API
is_iucn_rl_api_available()
```
If these instructions did not work, please consult the documentation for the [_rredlist_](https://CRAN.R-project.org/package=rredlist) _R_ package for further details.
### Usage
Here we provide a short example for using the _aoh R_ package. In this example, we will generate Area of Habitat data for the following Iberian species: Pyrenean brook salamander (_Calotriton asper_), Iberian frog (_Rana iberica_), western spadefoot toad (_Pelobates cultripes_), and golden striped salamnader (_Chioglossa lusitanica_). Please note that this example is an abridged version of the tutorial provided in the package vignette, so please consult the package vignette for a more detailed tutorial on using the package. To start off, we will load the package and several other packages to help with data processing and visualization.
```{r, message = FALSE, warning = FALSE}
# load packages
library(aoh)
library(terra)
library(rappdirs)
library(ggplot2)
```
Now we will import range data for the species. Although users would typically obtain range data from the [International Union for Conservation of Nature (IUCN) Red List of Threatened Species](https://www.iucnredlist.org/), here we will use built-in species range data that distributed with the package for convenience. **Please note that these data were not obtained from the IUCN Red List, and were manually generated using occurrence records from the [Global Biodiversity Information Facility](https://www.gbif.org/).**
```{r}
# find file path for data
path <- system.file("extdata", "EXAMPLE_SPECIES.zip", package = "aoh")
# import data
spp_range_data <- read_spp_range_data(path)
# preview data
print(spp_range_data)
```
Next, we will prepare all the range data for generating Area of Habitat data. This procedure -- in addition to repairing any geometry issues in the spatial data -- will obtain information on the species' habitat preferences and elevational limits (via the IUCN Red List of Threatened Species). We also specify a folder to cache the downloaded data so that we won't need to re-download it again during subsequent runs.
```{r, message = FALSE, results = "hide"}
# specify cache directory
cache_dir <- user_data_dir("aoh")
# create cache_dir if needed
if (!file.exists(cache_dir)) {
dir.create(cache_dir, showWarnings = FALSE, recursive = TRUE)
}
# prepare information
spp_info_data <- create_spp_info_data(spp_range_data, cache_dir = cache_dir)
```
We can now generate Area of Habitat data for the species. By default, these data will be generated using elevation data derived from [Robinson *et al.* (2014)](https://doi.org/10.1016/j.isprsjprs.2013.11.002) and habitat data derived from [Lumbierres *et al.* (2021)](https://doi.org/10.1111/cobi.13851). Similar to before, we also specify a folder to cache the downloaded datasets so that we won't need to re-downloaded again during subsequent runs.
```{r, message = FALSE, results = "hide"}
# specify cache directory
cache_dir <- user_data_dir("aoh")
# specify folder to save Area of Habitat data
## although we use a temporary directory here to avoid polluting your
## with examples files, you would normally specify the folder
## on your computer where you want to save data
output_dir <- tempdir()
# generate Area of Habitat data
## note that this function might take a complete because it will need to
## download the global habitat and elevation data that first time you run it.
spp_aoh_data <- create_spp_aoh_data(
spp_info_data, output_dir = output_dir, cache_dir = cache_dir
)
# preview results
print(spp_aoh_data[, c("id_no", "seasonal", "path")])
```
After generating the Area of Habitat data, we can import them.
```{r}
# import the Area of Habitat data
spp_aoh_rasters <- lapply(spp_aoh_data$path, rast)
# preview raster data
print(spp_aoh_rasters)
```
Finally, let's create some maps to compare the range data with the Area of habitat data.
```{r "map", message = FALSE, warning = FALSE, results = "hide", dpi = 200, fig.width = 5.5, fig.height = 4, out.width = ifelse(isTRUE(in_pkgdown()), "60%", "90%")}
# create maps
## N.B. you might need to install the ggmap package
map <-
plot_spp_aoh_data(
spp_aoh_data,
zoom = 6,
maptype = "stamen_toner_background"
) +
scale_fill_viridis_d() +
scale_color_manual(values = c("range" = "red")) +
scale_size_manual(values = c("range" = 0.5)) +
theme(
axis.title = element_blank(),
axis.text = element_text(size = 6),
strip.text = element_text(color = "white"),
strip.background = element_rect(fill = "black", color = "black")
)
# display maps
print(map)
```
### Citation
Please cite the _aoh R_ package and the underlying datasets used to produce Area of Habitat data.
```{r, echo = FALSE, result = "asis", comment = ""}
citation("aoh")
```
## Getting help
Please refer to the [package website](https://prioritizr.github.io/aoh/) for more information. If you have any questions about using the package or suggestions for improving it, please [file an issue at the package's online code repository](https://github.com/prioritizr/aoh/issues).