-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
223 lines (163 loc) · 13.2 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
---
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"
)
```
<!--- README.md is generated from README.Rmd. Please edit that file -->
## aoh: Create Area of Habitat Data
[![lifecycle](https://img.shields.io/badge/Lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![R-CMD-check-Ubuntu](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-ubuntu.yaml?branch=master&label=Ubuntu)](https://github.com/prioritizr/aoh/actions)
[![R-CMD-check-Windows](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-windows.yaml?branch=master&label=Windows)](https://github.com/prioritizr/aoh/actions)
[![R-CMD-check-macOS](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-macos.yaml?branch=master&label=macOS)](https://github.com/prioritizr/aoh/actions)
[![Documentation](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/documentation.yaml?branch=master&label=Documentation)](https://github.com/prioritizr/aoh/actions)
[![Coverage Status](https://img.shields.io/codecov/c/github/prioritizr/aoh?label=Coverage)](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 (<https://apiv3.iucnredlist.org/>), 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).