--- title: "Study case: the African bush elephant (*Loxodonta africana*)" author: "rcites team" date: 10-08-2018 output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Study case: the African bush elephant (*Loxodonta africana*)} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- # Introduction and setup In the vignettes "Get started with rcites", we explained how to get a token and set it up for general access to the CITES Species+ database. Also, we very briefly introduced to how to code the key features of `rcites`. With this article, we aim to further introduce to the functionality and workflows of `rcites`. For this, we use the African bush elephant (*Loxodonta africana*, hereafter "elephant") as a case study. The elephant not only is a highly endangered species that is illegally traded globally but also a flagship species of nature conservation and the logo species of CITES. We start with a basic set up: we load the package and set the token: ```r library(rcites) set_token("8QW6Qgh57sBG2k0gtt") ``` # Retrieve the taxon id In order to access information about the elephant, we first need to retrieve its Species+ taxon identifier. For this, we use the `spp_taxonconcept()` function and the elephant's scientific name, *Loxodonta africana*, as `query_taxon` argument. ```r elephant_taxonconcept <- spp_taxonconcept(query_taxon = "Loxodonta africana") ``` ``` #> ℹ Retrieving info from page 1 ........................ ✔ ``` ```r elephant_taxonconcept ``` ``` #> #> ── 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 ``` As the first column of the output shows, the taxon identifier of the elephant is 4521. This `taxon_id` will be used for all next function coding. Beyond the taxon identifier, the output also provides information about the taxon classification and other names, both synonyms and common names if any, in different languages. ## Map the elephant's distribution Before giving more insights into the legislation status of the elephant, we have a look at where the elephant actually occurs naturally. For this, we can access the elephant's distribution information with the `spp_distributions()` function. Thereafter, we can map the distribution with the help of the `rworldmap` package. ```r library(rworldmap) par(las = 1) elephant_distr <- spp_distributions(taxon_id = "4521", verbose = FALSE)$distributions map2 <- joinCountryData2Map(elephant_distr, joinCode="ISO2", nameJoinColumn = "iso_code2", nameCountryColumn = "name") ``` ``` #> 42 codes from your data successfully matched countries in the map #> 0 codes from your data failed to match with a country code in the map #> 201 codes from the map weren't represented in your data ``` ```r plot(c(-23, 62), c(45, -40), type = "n", main = "Loxodonta africana", xlab = "Longitude", ylab = "Latitude") plot(map2, add = TRUE) plot(map2[!is.na(map2$iso_code2),], col = "#cba74d", add = TRUE) ``` plot of chunk map ## Access the legislation status The functions `spp_cites_legislation()` and `spp_eu_legislation()` provide access to the legislation status information of the elephant. First, we have a look at the CITES legislation status: ```r elephant_cites <- spp_cites_legislation(taxon_id = "4521") ``` ``` #> ℹ Now processing taxon_id '4521'...................... ✔ ``` ```r elephant_cites ``` ``` #> #> ── 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 ``` We can do the same for the elephant's legislation status in the European Union: ```r elephant_eu <- spp_eu_legislation(taxon_id = "4521") ``` ``` #> ℹ Now processing taxon_id '4521'...................... ✔ ``` ```r elephant_eu ``` ``` #> #> ── EU listings ($eu_listings): ─────────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 2 × 6 #> id taxon_concept_id is_current annex change_type effective_at #> #> 1 31788 4521 TRUE A + 2019-12-14 #> 2 31876 4521 TRUE B + 2019-12-14 #> #> ── EU decisions ($eu_decisions): ───────────────────────────────────────────────────────────────────────────────────── #> # A tibble: 10 × 15 #> id taxon_concept_id start_date is_current eu_decision_type… eu_decision_type… geo_entity.iso_c… geo_entity.name #> #> 1 26285 4521 2015-04-09 TRUE Positive POSITIVE_OPINION ZW Zimbabwe #> 2 25508 4521 2014-09-03 TRUE Positive POSITIVE_OPINION BW Botswana #> 3 11682 4521 2012-02-23 TRUE Positive POSITIVE_OPINION NA Namibia #> 4 24825 4521 2014-05-28 TRUE Positive POSITIVE_OPINION ZA South Africa #> 5 27017 4521 2015-09-15 TRUE Positive POSITIVE_OPINION ZM Zambia #> 6 27360 4521 2016-06-27 TRUE Negative NEGATIVE_OPINION MZ Mozambique #> 7 35567 4521 2020-03-03 TRUE MZ Mozambique #> 8 30377 4521 2017-06-21 TRUE Negative NEGATIVE_OPINION TZ United Republic… #> 9 30553 4521 2017-06-21 TRUE Positive POSITIVE_OPINION TZ United Republic… #> 10 32143 4521 2019-10-17 TRUE Suspension (a) SUSPENSION CM Cameroon #> # … with 7 more variables: geo_entity.type , start_event.name , start_event.date , source.code , #> # source.name , term.code , term.name #> Field(s) not printed: notes, eu_decision_type.description, start_event.url ``` With the combination of `map2` and the legislation data, one might be able to illustrate the elephant's trade directions. This and other use examples of the `rcites` data output will be added bit by bit. ## Access the elephant's Species+ reference data Last but not least, it is important to identify which references the Species+ information about the elephant is based on. For this, we can access the Species+ reference data with the `spp_references()` function. ```r elephant_refs <- spp_references(taxon_id = "4521", verbose = FALSE) elephant_refs ``` ``` #> #> ── 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------- ``` ```r dim(elephant_refs$references) ``` ``` #> [1] 15 3 ```