{"id":26188330,"url":"https://github.com/prioritizr/aoh","last_synced_at":"2025-04-15T01:01:27.935Z","repository":{"id":49832883,"uuid":"412246032","full_name":"prioritizr/aoh","owner":"prioritizr","description":"Create Area of Habitat Data","archived":false,"fork":false,"pushed_at":"2025-01-07T02:19:54.000Z","size":142076,"stargazers_count":11,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T12:51:15.291Z","etag":null,"topics":["conservation","data","ecology","gis-data","rstats","rstats-package"],"latest_commit_sha":null,"homepage":"https://prioritizr.github.io/aoh","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prioritizr.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-30T22:23:06.000Z","updated_at":"2025-01-10T14:56:45.000Z","dependencies_parsed_at":"2023-02-08T16:31:49.570Z","dependency_job_id":"c5450aac-e76b-46ac-a427-cf5ef6ee5906","html_url":"https://github.com/prioritizr/aoh","commit_stats":{"total_commits":277,"total_committers":2,"mean_commits":138.5,"dds":"0.0072202166064981865","last_synced_commit":"34ae0912028581d6cf3d2b4e1fd68f81bc095f18"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prioritizr%2Faoh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prioritizr%2Faoh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prioritizr%2Faoh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prioritizr%2Faoh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prioritizr","download_url":"https://codeload.github.com/prioritizr/aoh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248986309,"owners_count":21194025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conservation","data","ecology","gis-data","rstats","rstats-package"],"created_at":"2025-03-11T23:58:07.228Z","updated_at":"2025-04-15T01:01:27.891Z","avatar_url":"https://github.com/prioritizr.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput:\n  rmarkdown::github_document:\n    html_preview: no\n---\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  fig.path = \"man/figures/README-\",\n  fig.align = \"center\",\n  fig.height = 4.5,\n  fig.width = 4.5,\n  dev = \"ragg_png\"\n)\n```\n\n\u003c!--- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n## aoh: Create Area of Habitat Data\n\n[![lifecycle](https://img.shields.io/badge/Lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)\n[![R-CMD-check-Ubuntu](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-ubuntu.yaml?branch=master\u0026label=Ubuntu)](https://github.com/prioritizr/aoh/actions)\n[![R-CMD-check-Windows](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-windows.yaml?branch=master\u0026label=Windows)](https://github.com/prioritizr/aoh/actions)\n[![R-CMD-check-macOS](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/R-CMD-check-macos.yaml?branch=master\u0026label=macOS)](https://github.com/prioritizr/aoh/actions)\n[![Documentation](https://img.shields.io/github/actions/workflow/status/prioritizr/aoh/documentation.yaml?branch=master\u0026label=Documentation)](https://github.com/prioritizr/aoh/actions)\n[![Coverage Status](https://img.shields.io/codecov/c/github/prioritizr/aoh?label=Coverage)](https://app.codecov.io/gh/prioritizr/aoh/branch/master)\n\n```{r, include = FALSE}\n# load developmental version of package\ndevtools::load_all()\n\n# check if being prepared for website\n## see https://github.com/r-lib/pkgdown/blob/main/R/pkgdown.R\nin_pkgdown \u003c- function() {\n  identical(Sys.getenv(\"IN_PKGDOWN\"), \"true\")\n}\n```\n\n### Overview\n\nArea 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).\n\n### Installation\n\n#### Package installation\n\nThe [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.\n\n```{r, eval = FALSE}\nif (!require(remotes)) install.packages(\"remotes\")\nremotes::install_github(\"prioritizr/aoh\")\n```\n\n#### Optional dependencies\n\nThe _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).\n\n```{r, eval = FALSE}\nif (!require(remotes)) install.packages(\"remotes\")\nremotes::install_github(\"prioritizr/prepr\")\n```\n\nThe 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.\n\n##### _Windows_\n\nThe [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`),\n\n##### _Ubuntu_\n\nFor recent versions of Ubuntu (18.04 and later), the libraries are available through official repositories. They can be installed using the following system commands.\n\n```\napt-get -y update\napt-get install -y \\\n  libgdal-dev libgeos-dev libproj-dev gdal-bin grass \\\n  libgmp3-dev libmpfr-dev libudunits2-dev\n```\n\n##### _Linux_\n\nFor Unix-alikes, `gdal` (\u003e= 3.0.2), `gmp` (\u003e= 4.2.3), `grass` (\u003e= 7.8.7), and `mpfr` (\u003e= 3.0.0) are required.\n\n##### _MacOS_\n\nThe 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.\n\n```\nbrew tap osgeo/osgeo4mac\nbrew install pkg-config\nbrew install gdal\nbrew install osgeo-grass\nbrew install gmp\nbrew install mpfr\n```\n\n#### Accessing the IUCN Red List API\n\nAfter 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 (\u003chttps://apiv3.iucnredlist.org/\u003e), 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.\n\n```\nIUCN_REDLIST_KEY=\"your_actual_token_not_this_string\"\n```\n\nPlease 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.\n\n```{r, eval = FALSE}\n# verify access to IUCN Red List API\nis_iucn_rl_api_available()\n```\n\nIf these instructions did not work, please consult the documentation for the [_rredlist_](https://CRAN.R-project.org/package=rredlist) _R_ package for further details.\n\n\n### Usage\n\nHere 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.\n\n```{r, message = FALSE, warning = FALSE}\n# load packages\nlibrary(aoh)\nlibrary(terra)\nlibrary(rappdirs)\nlibrary(ggplot2)\n```\n\nNow 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/).**\n\n```{r}\n# find file path for data\npath \u003c- system.file(\"extdata\", \"EXAMPLE_SPECIES.zip\", package = \"aoh\")\n\n# import data\nspp_range_data \u003c- read_spp_range_data(path)\n\n# preview data\nprint(spp_range_data)\n```\n\nNext, 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.\n\n```{r, message = FALSE, results = \"hide\"}\n# specify cache directory\ncache_dir \u003c- user_data_dir(\"aoh\")\n\n# create cache_dir if needed\nif (!file.exists(cache_dir)) {\n  dir.create(cache_dir, showWarnings = FALSE, recursive = TRUE)\n}\n\n# prepare information\nspp_info_data \u003c- create_spp_info_data(spp_range_data, cache_dir = cache_dir)\n```\n\nWe 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.\n\n```{r, message = FALSE, results = \"hide\"}\n# specify cache directory\ncache_dir \u003c- user_data_dir(\"aoh\")\n\n# specify folder to save Area of Habitat data\n## although we use a temporary directory here to avoid polluting your\n## with examples files, you would normally specify the folder\n## on your computer where you want to save data\noutput_dir \u003c- tempdir()\n\n# generate Area of Habitat data\n## note that this function might take a complete because it will need to\n## download the global habitat and elevation data that first time you run it.\nspp_aoh_data \u003c- create_spp_aoh_data(\n  spp_info_data, output_dir = output_dir, cache_dir = cache_dir\n)\n\n# preview results\nprint(spp_aoh_data[, c(\"id_no\", \"seasonal\", \"path\")])\n```\n\nAfter generating the Area of Habitat data, we can import them.\n\n```{r}\n# import the Area of Habitat data\nspp_aoh_rasters \u003c- lapply(spp_aoh_data$path, rast)\n\n# preview raster data\nprint(spp_aoh_rasters)\n```\n\nFinally, let's create some maps to compare the range data with the Area of habitat data.\n\n```{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%\")}\n# create maps\n## N.B. you might need to install the ggmap package\nmap \u003c-\n  plot_spp_aoh_data(\n    spp_aoh_data,\n    zoom = 6,\n    maptype = \"stamen_toner_background\"\n  ) +\n  scale_fill_viridis_d() +\n  scale_color_manual(values = c(\"range\" = \"red\")) +\n  scale_size_manual(values = c(\"range\" = 0.5)) +\n  theme(\n    axis.title = element_blank(),\n    axis.text = element_text(size = 6),\n    strip.text = element_text(color = \"white\"),\n    strip.background = element_rect(fill = \"black\", color = \"black\")\n  )\n\n# display maps\nprint(map)\n```\n\n### Citation\n\nPlease cite the _aoh R_ package and the underlying datasets used to produce Area of Habitat data.\n\n```{r, echo  = FALSE, result = \"asis\", comment = \"\"}\ncitation(\"aoh\")\n```\n\n## Getting help\n\nPlease 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprioritizr%2Faoh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprioritizr%2Faoh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprioritizr%2Faoh/lists"}