From f912e9b1944080905a6303d3c1234571c4601262 Mon Sep 17 00:00:00 2001 From: William Gearty Date: Mon, 30 Sep 2024 13:59:44 -0400 Subject: [PATCH] Update vignette --- .Rbuildignore | 5 +- .gitignore | 2 + DESCRIPTION | 4 +- vignettes/.gitignore | 1 - vignettes/precompile.R | 30 +++++ vignettes/rredlist.Rmd | 211 +++++++++++++++++++--------------- vignettes/rredlist.Rmd.og | 153 ------------------------ vignettes/source/rredlist.Rmd | 166 ++++++++++++++++++++++++++ 8 files changed, 321 insertions(+), 251 deletions(-) create mode 100644 vignettes/precompile.R delete mode 100644 vignettes/rredlist.Rmd.og create mode 100644 vignettes/source/rredlist.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index ebfb5a5..366da15 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -12,5 +12,8 @@ man-roxygen Makefile ^codemeta\.json$ ^LICENSE\.md$ -vignettes/rredlist.Rmd +vignettes/precompile.R +vignettes/source/rredlist.Rmd ^CRAN-SUBMISSION$ +^doc$ +^Meta$ diff --git a/.gitignore b/.gitignore index 6f6fb74..2a617a8 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ revdep/checks revdep/data.sqlite revdep/library rredlist.Rproj +/doc/ +/Meta/ diff --git a/DESCRIPTION b/DESCRIPTION index 74d627b..38640a2 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -35,8 +35,10 @@ Imports: Suggests: spelling, testthat, - vcr (>= 0.4.0) + vcr (>= 0.4.0), + knitr RoxygenNote: 7.3.2 +VignetteBuilder: knitr X-schema.org-applicationCategory: Biodiversity X-schema.org-keywords: IUCN, biodiversity, API, web-services, traits, habitat, species, conservation X-schema.org-isPartOf: https://ropensci.org diff --git a/vignettes/.gitignore b/vignettes/.gitignore index 097b241..2d19fc7 100644 --- a/vignettes/.gitignore +++ b/vignettes/.gitignore @@ -1,2 +1 @@ *.html -*.R diff --git a/vignettes/precompile.R b/vignettes/precompile.R new file mode 100644 index 0000000..0a23183 --- /dev/null +++ b/vignettes/precompile.R @@ -0,0 +1,30 @@ +# This script is used to precompile vignettes and should be run for +# each new version of the package + +# Get current wd (to restore later) +old_wd <- getwd() +# Set wd to vignettes to avoid saving to base directory +setwd("vignettes/") +# Precompile vignettes +library(knitr) +knit("./source/rredlist.Rmd", "rredlist.Rmd") + +# Build vignettes +library(devtools) +build_vignettes() + +# x = vignette file name including file extension (e.g. "rredlist.Rmd") +read_only <- function(x) { + tmp <- file(x) + writeLines(c( + paste0("% Generated by vignettes/precompile.R: do not edit by hand.\n", + "% Please edit source in vignettes/source/", x), + readLines(x)), tmp) + close(tmp) +} +# Add read only info +read_only("rredlist.Rmd") +rm(read_only) + +# Restore wd +setwd(old_wd) diff --git a/vignettes/rredlist.Rmd b/vignettes/rredlist.Rmd index 17bf68f..1bf5d1e 100644 --- a/vignettes/rredlist.Rmd +++ b/vignettes/rredlist.Rmd @@ -1,12 +1,10 @@ +% Generated by vignettes/precompile.R: do not edit by hand. +% Please edit source in vignettes/source/rredlist.Rmd --- -title: "rredlist" -author: "Scott Chamberlain" -date: "2020-10-14" -output: - html_document: - toc: true - toc_float: true - theme: readable +title: "Introduction to rredlist" +author: "William Gearty" +date: "2024-09-30" +output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to rredlist} %\VignetteEngine{knitr::rmarkdown} @@ -15,95 +13,123 @@ vignette: > -`rredlist` is an R client for the IUCN Red List (https://apiv3.iucnredlist.org/api/v3/docs). -The IUCN Red List is a global list of threatened and endangered species. +`rredlist` is an R client for the IUCN Red List API (https://api.iucnredlist.org/). +The [IUCN Red List](https://www.iucnredlist.org/) is the world’s most comprehensive information source on the global extinction risk status of animal, fungus and plant species. This package provides access via R to the various data contained within this database which span range details, population size, habitat and ecology, use and/or trade, threats, and conservation actions. -IUCN Red List docs: http://apiv3.iucnredlist.org/api/v3/docs The web API [needs authentication](#authentication). +Documentation for the IUCN Red List API are available at https://api.iucnredlist.org/api-docs. **Note that use of the web API, and therefore this package, [requires authentication](#authentication).** -> What rredlist is not: [redlistr][] is a different package - not working with the IUCN Red List API; Furthermore, rredlist does not include support for the spatial API, described at -https://apiv3.iucnredlist.org/spatial. +### What `rredlist` is not +1. [`redlistr`](https://cran.r-project.org/package=redlistr) is a different package for contributors to the IUCN Red List - not working with the IUCN Red List API. +2. `rredlist` does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial. ## Installation CRAN -```r +``` r install.packages("rredlist") ``` Development version -```r +``` r +# From GitHub remotes::install_github("ropensci/rredlist") -# OR -install.packages("rredlist", repos="https://dev.ropensci.org") + +# From r-universe +install.packages("rredlist", repos = "https://ropensci.r-universe.dev/") +``` + +### API Versioning + +`rredlist` versions ≤ 0.7.1 tracked [version 3](https://apiv3.iucnredlist.org/) of the IUCN Red List API. `rredlist` versions ≥ 1.0.0 track version 4 of the IUCN Red List API. If you need to use version 3 of the API--and it is still functioning--you can install an old version of `rredlist` using the `remotes` package: + + +``` r +# From CRAN archive +remotes::install_version("rredlist", version = "0.7.1") + +# From r-universe +remotes::install_version("rredlist", version = "0.7.1", + repos = "https://ropensci.r-universe.dev/") ``` ## Authentication -IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There's an helper function in the package helping you getting it at https://apiv3.iucnredlist.org/api/v3/token and storing it. +IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There's a helper function in the package helping you getting it at https://api.iucnredlist.org/users/sign_up and storing it. Once you store this key, the functions in `rredlist` will always default to using this key. -```r +``` r rredlist::rl_use_iucn() ``` -Keep this key private. You can pass the key in to each function via the `key` parameter, but it's better to store the key either as a environment variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we recommend using the former option. +**Keep this key private.** You can pass the key in to each function via the `key` parameter, but it's better to store the key either as a environment variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we recommend using the former option. +Note that you can no longer generate a new API key for version 3 of the API. ## High level interface -```r +``` r library("rredlist") ``` -High level functions do the HTTP request and parse data to a data.frame for ease +High level functions do the HTTP request and parse data to a list for ease of downstream use. The high level functions have no underscore on the end -of the function name, e.g., `rl_search()` +of the function name, e.g., `rl_species()`. Most of them return long lists containing lots of different information: -```r -rl_search('Fratercula arctica') -#> $name +``` r +rl_species("Fratercula", "arctica") +#> $taxon +#> $taxon$sis_id +#> [1] 22694927 +#> +#> $taxon$scientific_name #> [1] "Fratercula arctica" #> -#> $result -#> taxonid scientific_name kingdom phylum class order family -#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES ALCIDAE -#> genus main_common_name authority published_year assessment_date -#> 1 Fratercula Atlantic Puffin (Linnaeus, 1758) 2018 2018-08-07 -#> category criteria population_trend marine_system freshwater_system -#> 1 VU A4abcde Decreasing TRUE FALSE -#> terrestrial_system assessor reviewer aoo_km2 eoo_km2 -#> 1 TRUE BirdLife International Westrip, J.R.S. NA 20800000 -#> elevation_upper elevation_lower depth_upper depth_lower errata_flag -#> 1 NA NA NA NA NA -#> errata_reason amended_flag amended_reason -#> 1 NA NA NA +#> $taxon$species_taxa +#> list() +#> +... ``` -> Note: there can sometimes be a discrepancy between what you get on the IUCN website and what -> you get with this package; we don't know why, the IUCN API is not an open book. +By default, these high level functions will also parse the data to a data.frame, when possible: + + +``` r +rl_species("Fratercula", "arctica")$assessments +#> year_published latest sis_taxon_id url assessment_id +#> 1 2021 TRUE 22694927 https://www.iucnredlist.org/species/22694927/166290968 166290968 +#> 2 2018 TRUE 22694927 https://www.iucnredlist.org/species/22694927/132581443 132581443 +#> 3 2017 FALSE 22694927 https://www.iucnredlist.org/species/22694927/117606911 117606911 +#> 4 2016 FALSE 22694927 https://www.iucnredlist.org/species/22694927/93477427 93477427 +#> 5 2017 FALSE 22694927 https://www.iucnredlist.org/species/22694927/110638141 110638141 +#> 6 2015 FALSE 22694927 https://www.iucnredlist.org/species/22694927/82593109 82593109 +#> 7 2015 FALSE 22694927 https://www.iucnredlist.org/species/22694927/60110592 60110592 +#> 8 2012 FALSE 22694927 https://www.iucnredlist.org/species/22694927/38908739 38908739 +#> 9 2009 FALSE 22694927 https://www.iucnredlist.org/species/22694927/28178290 28178290 +... +``` -Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time +Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time: -```r -rl_search('Fratercula arctica', parse = FALSE) -#> $name -#> [1] "Fratercula arctica" +``` r +rl_species("Fratercula", "arctica", parse = FALSE)$assessments +#> [[1]] +#> [[1]]$year_published +#> [1] "2021" +#> +#> [[1]]$latest +#> [1] TRUE #> -#> $result -#> $result[[1]] -#> $result[[1]]$taxonid +#> [[1]]$sis_taxon_id #> [1] 22694927 #> -#> $result[[1]]$scientific_name -#> [1] "Fratercula arctica" ... ``` @@ -112,58 +138,31 @@ For even more speed, use the low level package interface. ## Low level interface The parsing to data.frame in the high level functions does take extra time. The low level functions -only do the HTTP request, and give back JSON without doing any more parsing. The low level functions DO have an underscore on the end -of the function name, e.g., `rl_search_()` +only do the HTTP request, and give back JSON without doing any more parsing. The low level functions DO have an underscore on the end of the function name, e.g., `rl_species_()`: -```r -rl_search_('Fratercula arctica') -#> [1] "{\"name\":\"Fratercula arctica\",\"result\":[{\"taxonid\":22694927,\"scientific_name\":\"Fratercula arctica\",\"kingdom\":\"ANIMALIA\",\"phylum\":\"CHORDATA\",\"class\":\"AVES\",\"order\":\"CHARADRIIFORMES\",\"family\":\"ALCIDAE\",\"genus\":\"Fratercula\",\"main_common_name\":\"Atlantic Puffin\",\"authority\":\"(Linnaeus, 1758)\",\"published_year\":2018,\"assessment_date\":\"2018-08-07\",\"category\":\"VU\",\"criteria\":\"A4abcde\",\"population_trend\":\"Decreasing\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Westrip, J.R.S.\",\"aoo_km2\":null,\"eoo_km2\":\"20800000\",\"elevation_upper\":null,\"elevation_lower\":null,\"depth_upper\":null,\"depth_lower\":null,\"errata_flag\":null,\"errata_reason\":null,\"amended_flag\":null,\"amended_reason\":null}]}" +``` r +rl_species_("Fratercula", "arctica") +#> [1] "{\"taxon\":{\"sis_id\":22694927,\"scientific_name\":\"Fratercula arctica\",\"species_taxa\":[],\"subpopulation_taxa\":[],\"infrarank_taxa\":[],\"kingdom_name\":\"ANIMALIA\",\"phylum_name\":\"CHORDATA\",\"class_name\":\"AVES\",\"order_name\":\"CHARADRIIFORMES\",\"family_name\":\"ALCIDAE\",\"genus_name\":\"Fratercula\",\"species_name\":\"arctica\",\"subpopulation_name\":null,\"infra_name\":null,\"authority\":\"(Linnaeus, 1758)\",\"species\":true,\"subpopulation\":false,\"infrarank\":false,\"ssc_groups\":[{\"name\":\"IUCN SSC Bird Red List Authority (BirdLife International)\",\"url\":\"https://www.birdlife.org/\",\"description\":\"Red List Authority Coordinator: Ian Burfield (ian.burfield@birdlife.org)\"}],\"common_names\":[{\"main\":false,\"name\":\"Puffin\",\"language\":{\"code\":\"eng\",\"description\":{\"en\":\"English\"}}},{\"main\":true,\"name\":\"Atlantic Puffin\",\"language\":{\"code\":\"eng\",\"description\":{\"en\":\"English\"}}}],\"synonyms\":[]},\"assessments\":[{\"year_published\":\"2021\",\"latest\":true,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/166290968\",\"assessment_id\":166290968,\"scopes\":[{\"description\":{\"en\":\"Europe\"},\"code\":\"2\"}]},{\"year_published\":\"2018\",\"latest\":true,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/132581443\",\"assessment_id\":132581443,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2017\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/117606911\",\"assessment_id\":117606911,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2016\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/93477427\",\"assessment_id\":93477427,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2017\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/110638141\",\"assessment_id\":110638141,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2015\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/82593109\",\"assessment_id\":82593109,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2015\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/60110592\",\"assessment_id\":60110592,\"scopes\":[{\"description\":{\"en\":\"Europe\"},\"code\":\"2\"}]},{\"year_published\":\"2012\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/38908739\",\"assessment_id\":38908739,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2009\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28178290\",\"assessment_id\":28178290,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2008\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28179292\",\"assessment_id\":28179292,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2004\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28180639\",\"assessment_id\":28180639,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2000\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28181882\",\"assessment_id\":28181882,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"1994\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28183212\",\"assessment_id\":28183212,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"1988\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28184380\",\"assessment_id\":28184380,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]}],\"params\":{\"genus_name\":\"Fratercula\",\"species_name\":\"arctica\"}}" ``` -To consume this JSON, you can use `jsonlite` +To consume this JSON, you can use [`jsonlite`](https://jeroen.r-universe.dev/jsonlite): -```r +``` r library("jsonlite") -jsonlite::fromJSON(rl_search_('Fratercula arctica')) -#> $name -#> [1] "Fratercula arctica" -#> -#> $result -#> taxonid scientific_name kingdom phylum class order family -#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES ALCIDAE -#> genus main_common_name authority published_year assessment_date -#> 1 Fratercula Atlantic Puffin (Linnaeus, 1758) 2018 2018-08-07 -#> category criteria population_trend marine_system freshwater_system -#> 1 VU A4abcde Decreasing TRUE FALSE -#> terrestrial_system assessor reviewer aoo_km2 eoo_km2 -#> 1 TRUE BirdLife International Westrip, J.R.S. NA 20800000 -#> elevation_upper elevation_lower depth_upper depth_lower errata_flag -#> 1 NA NA NA NA NA -#> errata_reason amended_flag amended_reason -#> 1 NA NA NA -``` - -Or other tools, e.g., `jq` via the `jqr` R client - - -```r -# remotes::install_github("ropensci/jqr") -library("jqr") -rl_search_('Fratercula arctica') %>% dot() -#> $data -#> [1] "{\"name\":\"Fratercula arctica\",\"result\":[{\"taxonid\":22694927,\"scientific_name\":\"Fratercula arctica\",\"kingdom\":\"ANIMALIA\",\"phylum\":\"CHORDATA\",\"class\":\"AVES\",\"order\":\"CHARADRIIFORMES\",\"family\":\"ALCIDAE\",\"genus\":\"Fratercula\",\"main_common_name\":\"Atlantic Puffin\",\"authority\":\"(Linnaeus, 1758)\",\"published_year\":2018,\"assessment_date\":\"2018-08-07\",\"category\":\"VU\",\"criteria\":\"A4abcde\",\"population_trend\":\"Decreasing\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Westrip, J.R.S.\",\"aoo_km2\":null,\"eoo_km2\":\"20800000\",\"elevation_upper\":null,\"elevation_lower\":null,\"depth_upper\":null,\"depth_lower\":null,\"errata_flag\":null,\"errata_reason\":null,\"amended_flag\":null,\"amended_reason\":null}]}" +jsonlite::fromJSON(rl_species_("Fratercula", "arctica")) +#> $taxon +#> $taxon$sis_id +#> [1] 22694927 #> -#> $args -#> $args[[1]] -#> [1] "." -#> attr(,"type") -#> [1] "dot" +#> $taxon$scientific_name +#> [1] "Fratercula arctica" #> +#> $taxon$species_taxa +#> list() #> -#> attr(,"class") -#> [1] "jqr" +... ``` ## Usage best practice @@ -172,9 +171,31 @@ rl_search_('Fratercula arctica') %>% dot() Use the function `rl_citation()`: -```r + +``` r rl_citation() -#> [1] "IUCN 2015. IUCN Red List of Threatened Species. Version 2020-2 " +#> [1] "IUCN 2024. IUCN Red List of Threatened Species. Version 2024-1 " +``` + +We'd also really appreciate it if you could cite your use of this package: + + +``` r +citation("rredlist") +#> To cite package 'rredlist' in publications use: +#> +#> Gearty W, Chamberlain S (????). _rredlist: 'IUCN' Red List Client_. R package version 0.7.1.9000, +#> https://github.com/ropensci/rredlist, . +#> +#> A BibTeX entry for LaTeX users is +#> +#> @Manual{, +#> title = {rredlist: 'IUCN' Red List Client}, +#> author = {William Gearty and Scott Chamberlain}, +#> note = {R package version 0.7.1.9000, +#> https://github.com/ropensci/rredlist}, +#> url = {https://docs.ropensci.org/rredlist/}, +#> } ``` ### Rate Limiting diff --git a/vignettes/rredlist.Rmd.og b/vignettes/rredlist.Rmd.og deleted file mode 100644 index bc02f0d..0000000 --- a/vignettes/rredlist.Rmd.og +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: "rredlist" -author: "Scott Chamberlain" -date: "`r Sys.Date()`" -output: - html_document: - toc: true - toc_float: true - theme: readable -vignette: > - %\VignetteIndexEntry{Introduction to rredlist} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r echo=FALSE} -library("knitr") -library("rredlist") -hook_output <- knitr::knit_hooks$get("output") -knitr::knit_hooks$set(output = function(x, options) { - lines <- options$output.lines - if (is.null(lines)) { - return(hook_output(x, options)) # pass to default hook - } - x <- unlist(strsplit(x, "\n")) - more <- "..." - if (length(lines)==1) { # first n lines - if (length(x) > lines) { - # truncate the output, but add .... - x <- c(head(x, lines), more) - } - } else { - x <- c(if (abs(lines[1])>1) more else NULL, - x[lines], - if (length(x)>lines[abs(length(lines))]) more else NULL - ) - } - # paste these lines together - x <- paste(c(x, ""), collapse = "\n") - hook_output(x, options) - }) - -knitr::opts_chunk$set( - warning = FALSE, - message = FALSE, - collapse = TRUE, - comment = "#>" -) -``` - -`rredlist` is an R client for the IUCN Red List (https://apiv3.iucnredlist.org/api/v3/docs). -The IUCN Red List is a global list of threatened and endangered species. - -IUCN Red List docs: http://apiv3.iucnredlist.org/api/v3/docs The web API [needs authentication](#authentication). - -> What rredlist is not: [redlistr][] is a different package - not working with the IUCN Red List API; Furthermore, rredlist does not include support for the spatial API, described at -https://apiv3.iucnredlist.org/spatial. - - -## Installation - -CRAN - -```{r eval=FALSE} -install.packages("rredlist") -``` - -Development version - -```{r eval=FALSE} -remotes::install_github("ropensci/rredlist") -# OR -install.packages("rredlist", repos="https://dev.ropensci.org") -``` - -## Authentication - -IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There's an helper function in the package helping you getting it at https://apiv3.iucnredlist.org/api/v3/token and storing it. - -```{r} -rredlist::rl_use_iucn() -``` - -Keep this key private. You can pass the key in to each function via the `key` parameter, but it's better to store the key either as a environment variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we recommend using the former option. - - -## High level interface - -```{r} -library("rredlist") -``` - -High level functions do the HTTP request and parse data to a data.frame for ease -of downstream use. The high level functions have no underscore on the end -of the function name, e.g., `rl_search()` - -```{r} -rl_search('Fratercula arctica') -``` - -> Note: there can sometimes be a discrepancy between what you get on the IUCN website and what -> you get with this package; we don't know why, the IUCN API is not an open book. - -Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time - -```{r output.lines=1:10} -rl_search('Fratercula arctica', parse = FALSE) -``` - -For even more speed, use the low level package interface. - -## Low level interface - -The parsing to data.frame in the high level functions does take extra time. The low level functions -only do the HTTP request, and give back JSON without doing any more parsing. The low level functions DO have an underscore on the end -of the function name, e.g., `rl_search_()` - -```{r} -rl_search_('Fratercula arctica') -``` - -To consume this JSON, you can use `jsonlite` - -```{r} -library("jsonlite") -jsonlite::fromJSON(rl_search_('Fratercula arctica')) -``` - -Or other tools, e.g., `jq` via the `jqr` R client - -```{r output.lines=1:20} -# remotes::install_github("ropensci/jqr") -library("jqr") -rl_search_('Fratercula arctica') %>% dot() -``` - -## Usage best practice - -### Citing the IUCN Red List API - -Use the function `rl_citation()`: - -```{r} -rl_citation() -``` - -### Rate Limiting - -From the IUCN folks: "Too many frequent calls, or too many calls per day -might get your access blocked temporarily. If you're a heavy API user, the -Red List Unit asked that you contact them, as there might be better options. -They suggest a 2-second delay between your calls if you plan to make a -lot of calls." diff --git a/vignettes/source/rredlist.Rmd b/vignettes/source/rredlist.Rmd new file mode 100644 index 0000000..fa9fa7e --- /dev/null +++ b/vignettes/source/rredlist.Rmd @@ -0,0 +1,166 @@ +--- +title: "Introduction to rredlist" +author: "William Gearty" +date: "`r Sys.Date()`" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Introduction to rredlist} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r echo=FALSE} +library("knitr") +library("rredlist") +hook_output <- knitr::knit_hooks$get("output") +knitr::knit_hooks$set(output = function(x, options) { + lines <- options$output.lines + if (is.null(lines)) { + return(hook_output(x, options)) # pass to default hook + } + x <- unlist(strsplit(x, "\n")) + more <- "..." + if (length(lines)==1) { # first n lines + if (length(x) > lines) { + # truncate the output, but add .... + x <- c(head(x, lines), more) + } + } else { + x <- c(if (abs(lines[1])>1) more else NULL, + x[lines], + if (length(x)>lines[abs(length(lines))]) more else NULL + ) + } + # paste these lines together + x <- paste(c(x, ""), collapse = "\n") + hook_output(x, options) + }) + +knitr::opts_chunk$set( + warning = FALSE, + message = FALSE, + collapse = TRUE, + comment = "#>" +) +``` + +`rredlist` is an R client for the IUCN Red List API (https://api.iucnredlist.org/). +The [IUCN Red List](https://www.iucnredlist.org/) is the world’s most comprehensive information source on the global extinction risk status of animal, fungus and plant species. This package provides access via R to the various data contained within this database which span range details, population size, habitat and ecology, use and/or trade, threats, and conservation actions. + +Documentation for the IUCN Red List API are available at https://api.iucnredlist.org/api-docs. **Note that use of the web API, and therefore this package, [requires authentication](#authentication).** + +### What `rredlist` is not + +1. [`redlistr`](https://cran.r-project.org/package=redlistr) is a different package for contributors to the IUCN Red List - not working with the IUCN Red List API. +2. `rredlist` does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial. + +## Installation + +CRAN + +```{r eval=FALSE} +install.packages("rredlist") +``` + +Development version + +```{r eval=FALSE} +# From GitHub +remotes::install_github("ropensci/rredlist") + +# From r-universe +install.packages("rredlist", repos = "https://ropensci.r-universe.dev/") +``` + +### API Versioning + +`rredlist` versions ≤ 0.7.1 tracked [version 3](https://apiv3.iucnredlist.org/) of the IUCN Red List API. `rredlist` versions ≥ 1.0.0 track version 4 of the IUCN Red List API. If you need to use version 3 of the API--and it is still functioning--you can install an old version of `rredlist` using the `remotes` package: + +```{r eval=FALSE} +# From CRAN archive +remotes::install_version("rredlist", version = "0.7.1") + +# From r-universe +remotes::install_version("rredlist", version = "0.7.1", + repos = "https://ropensci.r-universe.dev/") +``` + +## Authentication + +IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There's a helper function in the package helping you getting it at https://api.iucnredlist.org/users/sign_up and storing it. Once you store this key, the functions in `rredlist` will always default to using this key. + +```{r eval = FALSE} +rredlist::rl_use_iucn() +``` + +**Keep this key private.** You can pass the key in to each function via the `key` parameter, but it's better to store the key either as a environment variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we recommend using the former option. + +Note that you can no longer generate a new API key for version 3 of the API. + +## High level interface + +```{r} +library("rredlist") +``` + +High level functions do the HTTP request and parse data to a list for ease +of downstream use. The high level functions have no underscore on the end +of the function name, e.g., `rl_species()`. Most of them return long lists containing lots of different information: + +```{r output.lines=1:10} +rl_species("Fratercula", "arctica") +``` + +By default, these high level functions will also parse the data to a data.frame, when possible: + +```{r output.lines=1:10} +rl_species("Fratercula", "arctica")$assessments +``` + +Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time: + +```{r output.lines=1:10} +rl_species("Fratercula", "arctica", parse = FALSE)$assessments +``` + +For even more speed, use the low level package interface. + +## Low level interface + +The parsing to data.frame in the high level functions does take extra time. The low level functions +only do the HTTP request, and give back JSON without doing any more parsing. The low level functions DO have an underscore on the end of the function name, e.g., `rl_species_()`: + +```{r} +rl_species_("Fratercula", "arctica") +``` + +To consume this JSON, you can use [`jsonlite`](https://jeroen.r-universe.dev/jsonlite): + +```{r output.lines=1:10} +library("jsonlite") +jsonlite::fromJSON(rl_species_("Fratercula", "arctica")) +``` + +## Usage best practice + +### Citing the IUCN Red List API + +Use the function `rl_citation()`: + +```{r} +rl_citation() +``` + +We'd also really appreciate it if you could cite your use of this package: + +```{r} +citation("rredlist") +``` + +### Rate Limiting + +From the IUCN folks: "Too many frequent calls, or too many calls per day +might get your access blocked temporarily. If you're a heavy API user, the +Red List Unit asked that you contact them, as there might be better options. +They suggest a 2-second delay between your calls if you plan to make a +lot of calls."