--- title: "Get started with rcites" author: "rcites team" date: 10-08-2018 output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Get started with rcites} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- # Set up a connection to the Species+/CITES Checklist API ## Get your personal token To set up a connection to the Species+/CITES Checklist API, an authentication token is required. Each user should obtain his or her own personal token to run the code below (see for more details). To obtain a token, sign up on the [Species+ API website](http://api.speciesplus.net/users/sign_up). ## Set the token Now, we assume that you already have a token. For illustrative purposes, we will use the generic token value `8QW6Qgh57sBG2k0gtt` from the API documentation. A token is mandatory and needs to be passed to the header of all URL requests. They are three different ways to set the token in `rcites`: 1. set an environment variable `SPECIESPLUS_TOKEN` in your [`.Renviron`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) file (preferred for frequent users); 2. use `set_token()` to set up the token as a character string (with quotes). If not entered in the function, the token can be passed without quotes (not as a character string) after the prompt. This way, the token `SPECIESPLUS_TOKEN` is interactively set up only for the current R session, meaning a login will be required for the future R sessions (preferred); ```r library(rcites) set_token("8QW6Qgh57sBG2k0gtt") ``` 3. use the `token` argument inside the functions, *i.e.* the token is passed manually to each function call. Note that if you set a wrong token and you wish to set it again interactively, you must first forget the previous token with `forget_token()`. # Use of key features ## Retrieve a taxon identifiers with spp_taxonconcept() ### Basic calls to spp_taxonconcept() In order to efficiently query information from the CITES database, you first need to retrieve the unique taxon identifier `taxon_id` from the [Species+ taxon concept](https://api.speciesplus.net/documentation/v1/taxon_concepts/index.html). To do so, you should first call `spp_taxonconcept()` and provide the scientific name of the taxon you are looking for. Let us start by requesting the identifier of the African bush elephant, *i.e.* *Loxodonta africana*. ```r res1 <- spp_taxonconcept(query_taxon = "Loxodonta africana") ``` Note that if you have decide to set your token using the third option, then the code should look like the one below: ```r res1 <- spp_taxonconcept(query_taxon = "Loxodonta africana", token = "8QW6Qgh57sBG2k0gtt") ``` ### Object `spp_taxonconcept` `res1` is an S3 object of class `spp_taxon`: ```r attributes(res1) ``` ``` #> $names #> [1] "all_id" "general" "higher_taxa" "accepted_names" "common_names" "synonyms" #> [7] "cites_listings" #> #> $class #> [1] "spp_taxon" #> #> $taxonomy #> [1] "CITES" ``` that contains information sorted into several data frames (see `?spp_taxonconcept` for further details): ```r res1 ``` ``` #> #> ── General info - CITES ($general): ────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> #> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-10-13 13:12:58 TRUE I/II #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> #> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 4 #> id full_name author_year rank #> #> 1 37069 Loxodonta cyclotis (Matschie, 1900) SPECIES #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id name language #> #> 1 4521 Ndovo SW #> 2 4521 Tembo SW #> 3 4521 Haathi UR #> 4 4521 Elefante PT #> 5 4521 Slon RU #> 6 4521 Elefant NO #> 7 4521 Olifant NL #> 8 4521 Afrikaanse olifant NL #> 9 4521 Elefante africano ES #> 10 4521 afrikansk elefant SV #> -------truncated------- #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms, $cites_listings ``` For some taxa, there are more than one taxon identifier available. In `general` only *active* identifiers are listed, but the full list of identifiers are available in `all_id`: ```r res3 <- spp_taxonconcept(query = "Amazilia versicolor") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ```r res3$general ``` ``` #> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> * #> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A 2015-05-07 15:10:59 TRUE II ``` ```r res3$all_id ``` ``` #> # A tibble: 2 × 7 #> id full_name author_year rank name_status updated_at active #> #> 1 3210 Amazilia versicolor (Vieillot, 1818) SPECIES A 2015-05-07 15:10:59 TRUE #> 2 65789 Amazilia versicolor (Vieillot, 1818) SPECIES S 2016-09-23 15:30:46 FALSE ``` Also, if the taxon is not listed, a warning message should come up. ```r res4 <- spp_taxonconcept(query = "Homo Sapiens") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ``` #> Warning in spp_taxonconcept(query = "Homo Sapiens"): Taxon not listed. ``` ### Custom calls to spp_taxonconcept() `spp_taxonconcept()` includes several arguments to retrieve a specific subset of information (see `?spp_taxonconcept` for more details): ```r args('spp_taxonconcept') ``` ``` #> function (query_taxon, taxonomy = "CITES", with_descendants = FALSE, #> language = NULL, updated_since = NULL, per_page = 500, pages = NULL, #> raw = FALSE, token = NULL, verbose = TRUE, pause = 1, ...) #> NULL ``` Most importantly, the argument `taxonomy` allows a selection between the two databases (CITES or CMS): ```r spp_taxonconcept(query = "Amazilia versicolor", taxonomy = "CMS") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ``` #> Warning in spp_taxonconcept(query = "Amazilia versicolor", taxonomy = "CMS"): Taxon not listed. ``` ``` #> NULL ``` ```r spp_taxonconcept(query = "Loxodonta africana", taxonomy = "CMS") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ``` #> #> ── General info - CMS ($general): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 7 #> id full_name author_year rank name_status updated_at active #> #> 1 11691 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-05-06 12:44:13 TRUE #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> #> 1 11691 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> No records available. #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id name language #> #> 1 11691 Tembo SW #> 2 11691 Ndovo SW #> 3 11691 Haathi UR #> 4 11691 Elefante PT #> 5 11691 Slon RU #> 6 11691 Elefant NO #> 7 11691 Olifant NL #> 8 11691 Afrikaanse olifant NL #> 9 11691 Elefante africano ES #> 10 11691 afrikansk elefant SV #> -------truncated------- #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms ``` `language` and `updated_since` are convenient filters for the written language of common names (must be a two-letters code, see [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) and the last update of the entries, respectively: ```r spp_taxonconcept(query_taxon = "Loxodonta africana", language = 'EN', updated_since = "2016-01-01") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ``` #> #> ── General info - CITES ($general): ────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 8 #> id full_name author_year rank name_status updated_at active cites_listing #> #> 1 4521 Loxodonta africana (Blumenbach, 1797) SPECIES A 2021-10-13 13:12:58 TRUE I/II #> #> ── Classification ($higher_taxa): ──────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 6 #> id kingdom phylum class order family #> #> 1 4521 Animalia Chordata Mammalia Proboscidea Elephantidae #> #> ── Synonyms ($synonyms): ───────────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 1 × 4 #> id full_name author_year rank #> #> 1 37069 Loxodonta cyclotis (Matschie, 1900) SPECIES #> #> ── Common names ($common_names): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 2 × 3 #> id name language #> #> 1 4521 African Elephant EN #> 2 4521 African Savannah Elephant EN #> #> Information available: $all_id, $general, $higher_taxa, $accepted_names, $common_names, $synonyms, $cites_listings ``` ## Retrieve a taxon identifiers available data In order to use the four `spp_*` functions, one needs to use the *active taxon identifier* of a given species. For instance, for the two species we used as examples above we use the value indicated in the table below: |name | taxon identifier| |:-------------------|:----------------| |Loxodonta africana | 4521 | |Amazilia versicolor | 3210 | ### CITES legislation data First, we can retrieve current CITES appendix listings and reservations, CITES quotas, and CITES suspensions for a given taxon concept. ```r spp_cites_legislation(taxon_id = "4521", verbose = FALSE) ``` ``` #> #> ── Cites listings ($cites_listings): ───────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 6 #> id taxon_concept_id is_current appendix change_type effective_at #> #> 1 30344 4521 TRUE I + 2017-01-02 #> 2 30115 4521 TRUE II + 2019-11-26 #> 3 32160 4521 TRUE II R+ 2019-11-26 #> 4 32161 4521 TRUE II R+ 2019-11-26 #> 5 32156 4521 TRUE II R+ 2019-11-26 #> 6 32158 4521 TRUE II R+ 2019-11-26 #> 7 32154 4521 TRUE II R+ 2019-11-26 #> 8 32159 4521 TRUE II R+ 2019-11-26 #> 9 32157 4521 TRUE II R+ 2019-11-26 #> 10 32155 4521 TRUE II R+ 2019-11-26 #> #> ── Cites quotas ($cites_quotas): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 10 #> id taxon_concept_id quota publication_date public_display is_current unit geo_entity.iso_code2 geo_entity.name #> #> 1 25337 4521 0 2021-02-03 TRUE TRUE KE Kenya #> 2 25348 4521 0 2021-02-03 TRUE TRUE LR Liberia #> 3 25355 4521 0 2021-02-03 TRUE TRUE MW Malawi #> 4 25358 4521 0 2021-02-03 TRUE TRUE ML Mali #> 5 25375 4521 0 2021-02-03 TRUE TRUE MZ Mozambique #> 6 25390 4521 0 2021-02-03 TRUE TRUE AO Angola #> 7 25414 4521 0 2021-02-03 TRUE TRUE NE Niger #> 8 25431 4521 0 2021-02-03 TRUE TRUE NG Nigeria #> 9 25554 4521 100 2021-02-03 TRUE TRUE TZ United Republic… #> 10 25555 4521 300 2021-02-03 TRUE TRUE ZA South Africa #> # … with 1 more variable: geo_entity.type #> -------truncated------- #> Field(s) not printed: notes, url #> #> ── Cites suspensions ($cites_suspensions): ─────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 8 #> id taxon_concept_id start_date is_current applies_to_import geo_entity.iso_code2 geo_entity.name geo_entity.type #> #> 1 17621 4521 2014-08-11 TRUE TRUE US United States … COUNTRY #> 2 17620 4521 2014-08-11 TRUE TRUE US United States … COUNTRY #> 3 17686 4521 2014-10-10 TRUE TRUE US United States … COUNTRY #> 4 18709 4521 2010-08-16 TRUE TRUE ZW Zimbabwe COUNTRY #> 5 15983 2011-01-19 TRUE FALSE DJ Djibouti COUNTRY #> 6 22079 2018-01-30 TRUE FALSE DJ Djibouti COUNTRY #> 7 22076 2018-01-22 TRUE FALSE LR Liberia COUNTRY #> 8 22132 4521 2018-03-19 TRUE FALSE AU Australia COUNTRY #> 9 23168 2019-07-04 TRUE FALSE SO Somalia COUNTRY #> 10 24947 4521 2020-05-26 TRUE TRUE CN China COUNTRY #> -------truncated------- #> Field(s) not printed: notes, start_notification.name, start_notification.date, start_notification.url ``` ### EU legislation data Similarly, we can also retrieve current EU annex listings, SRG opinions, and EU suspensions with `spp_eu_legislation`. Both legislation functions have a `scope` argument that sets the time scope of legislation and take one value among `current`, `historic` and `all` (default is set to `current`). For instance, one can get all information pertaining to EU annex listing for *Amazilia versicolor* with the following command line: ```r spp_eu_legislation(taxon_id = "3210", scope = "all", verbose = FALSE) ``` ``` #> #> ── EU listings ($eu_listings): ─────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 6 #> id taxon_concept_id is_current annex change_type effective_at #> #> 1 17611 3210 FALSE B + 1997-06-01 #> 2 17610 3210 FALSE B + 2000-12-18 #> 3 17609 3210 FALSE B + 2003-08-30 #> 4 17608 3210 FALSE B + 2005-08-22 #> 5 17607 3210 FALSE B + 2008-04-11 #> 6 17606 3210 FALSE B + 2009-05-22 #> 7 17605 3210 FALSE B + 2010-08-15 #> 8 17604 3210 FALSE B + 2012-02-14 #> 9 17603 3210 FALSE B + 2012-12-15 #> 10 17602 3210 FALSE B + 2013-08-10 #> -------truncated------- #> #> ── EU decisions ($eu_decisions): ───────────────────────────────────────────────────────────────────────────────────── #> No records available. ``` ### Distribution data Distribution data at the country level is also available for a given taxon concept: ```r spp_distributions("4521", verbose = FALSE) ``` ``` #> #> ── Distributions ($distributions): ─────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 5 #> id iso_code2 name type tags #> #> 1 1778 ML Mali COUNTRY "" #> 2 1923 GQ Equatorial Guinea COUNTRY "" #> 3 4429 RW Rwanda COUNTRY "" #> 4 4491 GH Ghana COUNTRY "" #> 5 5628 SD Sudan COUNTRY "" #> 6 6724 ET Ethiopia COUNTRY "" #> 7 8995 GA Gabon COUNTRY "" #> 8 12983 AO Angola COUNTRY "" #> 9 15554 CM Cameroon COUNTRY "" #> 10 17060 BJ Benin COUNTRY "" #> -------truncated------- #> #> ── References ($references): ───────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 2 #> id reference #> #> 1 1778 Kingdon, J., Happold [truncated] #> 2 1923 Basilio, A. 1962. La [truncated] #> 3 4429 Jackson, P. 1982. El [truncated] #> 4 4429 Monfort, A. 1992. Pr [truncated] #> 5 4491 Grubb, P., Jones, T. [truncated] #> 6 4491 Jackson, P. 1982. El [truncated] #> 7 5628 Hameed, S.M.A. and E [truncated] #> 8 6724 Bolton, M. 1973. Not [truncated] #> 9 6724 Largen, M. J. and Ya [truncated] #> 10 6724 Meester, J. and Setz [truncated] #> -------truncated------- ``` ### References Finally, we can retrieve all available references for a given taxa. ```r spp_references("4521", verbose = FALSE) ``` ``` #> #> ── References ($references): ───────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 3 #> id citation is_standard #> #> 1 10265 Anon. 1978. Red data book: Mammalia. IUC [truncated] FALSE #> 2 6344 Barnes, R. F., Agnagna, M., Alers, M. P. [truncated] FALSE #> 3 17013 Blanc, J.J., Thouless, C.R., Hart, J.A., [truncated] FALSE #> 4 6371 Burton, M. P. 1994. Alternative projecti [truncated] FALSE #> 5 6532 Douglas-Hamilton, I. 1987. African Eleph [truncated] FALSE #> 6 6534 Douglas-Hamilton, I. 1987. African Eleph [truncated] FALSE #> 7 6825 Jackson, P. 1982. Elephants and rhinos i [truncated] FALSE #> 8 7224 Meester, J. and Setzer, H. W (eds.) 1974 [truncated] FALSE #> 9 7609 Parker, I. and Amin, M. 1983. Ivory cris [truncated] FALSE #> 10 19397 Parker, I.S.C. and Martin, E.B. 1982. Ho [truncated] FALSE #> -------truncated------- ```