├── .Rbuildignore ├── .circleci └── config.yml ├── .github ├── CODE_OF_CONDUCT.md └── CONTRIBUTING.md ├── .gitignore ├── .zenodo.json ├── DESCRIPTION ├── LICENSE ├── LICENSE.md ├── NAMESPACE ├── NEWS.md ├── R ├── cites-guidance.R ├── citesdb-package.R ├── connect.R ├── connection-pane.R ├── download.R └── onattach.R ├── README-not.md ├── README.Rmd ├── README.md ├── citesdb.Rproj ├── codemeta.json ├── data-raw ├── country_code_data │ ├── cites_manual_country_code_entries.csv │ └── en-CITES_Trade_Database_Guide.pdf ├── process_tables.R └── process_trade_db.R ├── inst ├── CITATION ├── WORDLIST ├── extdata │ ├── cites_codes.tsv │ ├── cites_metadata.tsv │ ├── cites_parties.tsv │ ├── rcites1.rds │ ├── rcites2.rds │ ├── rcites3.rds │ └── rcites4.rds ├── img │ ├── cites-logo.png │ ├── edit-sql.png │ ├── eha_logo.png │ └── usaid-logo.png ├── paper.bib ├── paper.md ├── response_to_reviewers.md └── ro_blog_post.md ├── man ├── cites_db.Rd ├── cites_db_delete.Rd ├── cites_db_download.Rd ├── cites_disconnect.Rd ├── cites_metadata.Rd ├── cites_pane.Rd ├── cites_shipments.Rd ├── cites_status.Rd ├── citesdb-package.Rd ├── figures │ └── README-unnamed-chunk-5-1.png └── guidance.Rd ├── pkgdown ├── _pkgdown.yml └── favicon │ ├── apple-touch-icon-60x60.png │ ├── apple-touch-icon.png │ ├── favicon-16x16.png │ ├── favicon-32x32.png │ └── favicon.ico ├── tests ├── spelling.R ├── testthat.R └── testthat │ ├── test-01-download.R │ ├── test-02-tables.R │ ├── test-03-connection.R │ ├── test-04-data.R │ └── test-lint.R └── vignettes ├── .gitignore ├── citations.bib ├── exploring-cites-trade-data-with-citesdb.Rmd └── figures ├── cites_pane.gif ├── eha-footer.png └── usaid-logo.png /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^citesdb\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^pkgdown$ 4 | ^\.travis\.yml$ 5 | ^README\.Rmd$ 6 | ^README\.md$ 7 | ^LICENSE\.md$ 8 | ^\.github$ 9 | ^data-raw$ 10 | ^\.circleci$ 11 | ^_pkgdown\.yml$ 12 | ^docs$ 13 | ^appveyor\.yml$ 14 | ^codemeta\.json$ 15 | ^docker$ 16 | ^localdb$ 17 | ^tests/testthat/localdb$ 18 | ^artifacts$ 19 | ^codemeta.json$ 20 | ^README_cache$ 21 | cache$ 22 | ^\.zenodo.json$ 23 | ^doc$ 24 | ^Meta$ 25 | -------------------------------------------------------------------------------- /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | jobs: 3 | build: 4 | working_directory: ~/main 5 | docker: 6 | - image: rocker/verse:latest 7 | environment: 8 | NOT_CRAN: true 9 | steps: 10 | - checkout 11 | - restore_cache: 12 | keys: 13 | - deps4-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 14 | - deps4-{{ .Branch }} 15 | - deps4- 16 | - run: 17 | name: Install packages 18 | command: | 19 | Rscript -e "devtools::install_deps(dependencies = TRUE)" 20 | Rscript -e "if(!require(DT)) devtools::install_cran('DT', dependencies = TRUE)" 21 | Rscript -e "if(!require(covr)) devtools::install_cran('covr', dependencies = TRUE)" 22 | Rscript -e "if(!require(goodpractice)) devtools::install_cran('goodpractice', dependencies = TRUE)" 23 | Rscript -e "if(!require(rhub)) devtools::install_cran('rhub', dependencies = TRUE)" 24 | Rscript -e "devtools::install_github('r-lib/pkgdown', dependencies = TRUE)" 25 | - run: 26 | name: Check package 27 | command: | 28 | Rscript -e "devtools::check()" 29 | Rscript -e "devtools::install()" 30 | - save_cache: 31 | key: deps4-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 32 | paths: 33 | - "/usr/local/lib/R/site-library" 34 | - add_ssh_keys 35 | - deploy: 36 | name: Build and deploy pkgdown site 37 | when: on_success 38 | command: | 39 | if [ "${CIRCLE_BRANCH}" == "master" ]; then 40 | Rscript -e "git2r::config(global = TRUE, user.name = 'Noam Ross', user.email = 'ross@ecohealthalliance.org')" || true 41 | Rscript -e "pkgdown:::deploy_local(pkg = '.', repo_slug = NULL, pkgdown:::construct_commit_message('.'), examples = FALSE)" || true 42 | fi 43 | - run: 44 | name: Extra diagnostics 45 | when: on_success 46 | command: | 47 | mkdir /root/main/artifacts 48 | Rscript -e "goodpractice::gp(checks = grep('(rcmdcheck|covr)', goodpractice::all_checks(), invert=TRUE, value=TRUE))" || true 49 | Rscript -e "Sys.setenv(CI='');cv <- covr::package_coverage(); print(cv); covr::report(x = cv, file = '/root/main/artifacts/citesdb-coverage.html', browse=FALSE); covr::codecov(coverage=cv)" || true 50 | R CMD Rd2pdf --force --output='/root/main/artifacts/citesdb-manual.pdf' . || true 51 | - store_artifacts: 52 | path: /root/main/artifacts/ 53 | destination: artifacts 54 | # - run: 55 | # name: Check on r-hub 56 | # when: on_success 57 | # command: | 58 | # Rscript -e "rhub::validate_email(email = 'ross@ecohealthalliance.org', token = Sys.getenv('RHUB_TOKEN')); rhub::check_for_cran(show_status = TRUE)" || true 59 | build_devel: 60 | working_directory: ~/main 61 | docker: 62 | - image: rocker/verse:devel 63 | environment: 64 | NOT_CRAN: true 65 | steps: 66 | - checkout 67 | - restore_cache: 68 | keys: 69 | - deps4-devel-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 70 | - deps4-devel-{{ .Branch }} 71 | - deps4-devel 72 | - run: 73 | name: Install packages 74 | command: | 75 | Rscript -e "devtools::install_deps(dependencies = TRUE)" 76 | Rscript -e "if(!require(DT)) devtools::install_cran('DT', dependencies = TRUE)" 77 | Rscript -e "if(!require(covr)) devtools::install_cran('covr', dependencies = TRUE)" 78 | Rscript -e "if(!require(goodpractice)) devtools::install_cran('goodpractice', dependencies = TRUE)" 79 | Rscript -e "if(!require(rhub)) devtools::install_cran('rhub', dependencies = TRUE)" 80 | Rscript -e "devtools::install_github('r-lib/pkgdown', dependencies = TRUE)" 81 | - run: 82 | name: Check package 83 | command: | 84 | Rscript -e "devtools::check()" 85 | Rscript -e "devtools::install()" 86 | - save_cache: 87 | key: deps4-devel-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 88 | paths: 89 | - "/usr/local/lib/R/site-library" 90 | build_oldrel: 91 | working_directory: ~/main 92 | docker: 93 | - image: rocker/verse:3.5.3 94 | environment: 95 | NOT_CRAN: true 96 | steps: 97 | - checkout 98 | - restore_cache: 99 | keys: 100 | - deps2-oldrel-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 101 | - deps2-oldrel-{{ .Branch }} 102 | - deps2-oldrel 103 | - run: 104 | name: Install packages 105 | command: | 106 | Rscript -e "devtools::install_deps(dependencies = TRUE)" 107 | Rscript -e "if(!require(DT)) devtools::install_cran('DT', dependencies = TRUE)" 108 | Rscript -e "if(!require(covr)) devtools::install_cran('covr', dependencies = TRUE)" 109 | Rscript -e "if(!require(goodpractice)) devtools::install_cran('goodpractice', dependencies = TRUE)" 110 | Rscript -e "if(!require(rhub)) devtools::install_cran('rhub', dependencies = TRUE)" 111 | Rscript -e "if(!require(pkgdown)) devtools::install_cran('pkgdown', dependencies = TRUE)" 112 | - run: 113 | name: Check package 114 | command: | 115 | Rscript -e "devtools::check()" 116 | Rscript -e "devtools::install()" 117 | - save_cache: 118 | key: deps2-oldrel-{{ .Branch }}-{{ checksum "DESCRIPTION" }}-{{ checksum ".circleci/config.yml" }} 119 | paths: 120 | - "/usr/local/lib/R/site-library" 121 | - add_ssh_keys 122 | 123 | workflows: 124 | version: 2 125 | commit: 126 | jobs: 127 | - build: 128 | filters: 129 | branches: 130 | ignore: 131 | - gh-pages 132 | # - build_devel: 133 | # filters: 134 | # branches: 135 | # ignore: 136 | # - gh-pages 137 | - build_oldrel: 138 | filters: 139 | branches: 140 | ignore: 141 | - gh-pages 142 | weekly: 143 | triggers: 144 | - schedule: 145 | cron: "0 1 * * 6" 146 | filters: 147 | branches: 148 | only: 149 | - master 150 | jobs: 151 | - build 152 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | [Bosnian](http://contributor-covenant.org/version/1/4/bs/) 4 | | [Deutsch](http://contributor-covenant.org/version/1/4/de/) 5 | | [ελληνικά](http://contributor-covenant.org/version/1/4/el/) 6 | | [English](http://contributor-covenant.org/version/1/4/) 7 | | [Español](http://contributor-covenant.org/version/1/4/es/) 8 | | [Français](http://contributor-covenant.org/version/1/4/fr/) 9 | | [Italiano](http://contributor-covenant.org/version/1/3/0/it/) 10 | | [日本語](http://contributor-covenant.org/version/1/3/0/ja/) 11 | | [Magyar](http://contributor-covenant.org/version/1/3/0/hu/) 12 | | [Nederlands](http://contributor-covenant.org/version/1/4/nl/) 13 | | [Polski](http://contributor-covenant.org/version/1/4/pl/) 14 | | [Português](http://contributor-covenant.org/version/1/4/pt/) 15 | | [Português do Brasil](http://contributor-covenant.org/version/1/4/pt_br/) 16 | | [Pусский](http://contributor-covenant.org/version/1/3/0/ru/) 17 | | [Română](http://contributor-covenant.org/version/1/4/ro/) 18 | | [Svenska](http://contributor-covenant.org/version/1/4/sv/) 19 | | [Slovenščina](http://contributor-covenant.org/version/1/4/sl/) 20 | | [Türkçe](http://contributor-covenant.org/version/1/4/tr/) 21 | | [Українська](http://contributor-covenant.org/version/1/4/uk/) 22 | | [한국어](http://contributor-covenant.org/version/1/4/ko/) 23 | 24 | 25 | ## Our Pledge 26 | 27 | In the interest of fostering an open and welcoming environment, we as 28 | contributors and maintainers pledge to making participation in our project and 29 | our community a harassment-free experience for everyone, regardless of age, body 30 | size, disability, ethnicity, gender identity and expression, level of experience, 31 | nationality, personal appearance, race, religion, or sexual identity and 32 | orientation. 33 | 34 | ## Our Standards 35 | 36 | Examples of behavior that contributes to creating a positive environment 37 | include: 38 | 39 | * Using welcoming and inclusive language 40 | * Being respectful of differing viewpoints and experiences 41 | * Gracefully accepting constructive criticism 42 | * Focusing on what is best for the community 43 | * Showing empathy towards other community members 44 | 45 | Examples of unacceptable behavior by participants include: 46 | 47 | * The use of sexualized language or imagery and unwelcome sexual attention or 48 | advances 49 | * Trolling, insulting/derogatory comments, and personal or political attacks 50 | * Public or private harassment 51 | * Publishing others' private information, such as a physical or electronic 52 | address, without explicit permission 53 | * Other conduct which could reasonably be considered inappropriate in a 54 | professional setting 55 | 56 | ## Our Responsibilities 57 | 58 | Project maintainers are responsible for clarifying the standards of acceptable 59 | behavior and are expected to take appropriate and fair corrective action in 60 | response to any instances of unacceptable behavior. 61 | 62 | Project maintainers have the right and responsibility to remove, edit, or 63 | reject comments, commits, code, wiki edits, issues, and other contributions 64 | that are not aligned to this Code of Conduct, or to ban temporarily or 65 | permanently any contributor for other behaviors that they deem inappropriate, 66 | threatening, offensive, or harmful. 67 | 68 | ## Scope 69 | 70 | This Code of Conduct applies both within project spaces and in public spaces 71 | when an individual is representing the project or its community. Examples of 72 | representing a project or community include using an official project e-mail 73 | address, posting via an official social media account, or acting as an appointed 74 | representative at an online or offline event. Representation of a project may be 75 | further defined and clarified by project maintainers. 76 | 77 | ## Enforcement 78 | 79 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 80 | reported by contacting the project team at noam.ross@gmail.com. All 81 | complaints will be reviewed and investigated and will result in a response that 82 | is deemed necessary and appropriate to the circumstances. The project team is 83 | obligated to maintain confidentiality with regard to the reporter of an incident. 84 | Further details of specific enforcement policies may be posted separately. 85 | 86 | Project maintainers who do not follow or enforce the Code of Conduct in good 87 | faith may face temporary or permanent repercussions as determined by other 88 | members of the project's leadership. 89 | 90 | ## Attribution 91 | 92 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 93 | available at [http://contributor-covenant.org/version/1/4][version] 94 | 95 | [homepage]: http://contributor-covenant.org 96 | [version]: http://contributor-covenant.org/version/1/4/ 97 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the citesdb R package 2 | 3 | You want to contribute to **citesdb**? Great! 4 | 5 | Please submit questions, bug reports, and requests in the [issues tracker](https://github.com/ropensci/citesdb/issues). Please submit bug 6 | reports with a minimal [reprex](https://www.tidyverse.org/help/#reprex). 7 | 8 | If you plan to contribute code, go ahead and fork the repo and submit a pull request. A few notes: 9 | 10 | - This package is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. Why? We want contribution to be enjoyable and rewarding for everyone! 11 | - If you have large change, please open an issue first to discuss. 12 | - I'll generally include contributors as authors in the DESCRIPTION file (with 13 | their permission) for most contributions that go beyond small typos in code or documentation. 14 | - This package generally uses the [rOpenSci packaging guidelines](https://github.com/ropensci/onboarding/blob/master/packaging_guide.md) for style and structure. 15 | - Documentation is generated by **roxygen2**. Please write documentation in code files and let it auto-generate documentation files. We use a recent version so documentation my be [written in markdown](https://cran.r-project.org/web/packages/roxygen2/vignettes/markdown.html) 16 | - We aim for testing that has high coverage and is robust. Include tests with 17 | any major contribution to code. Test your changes the package with [**goodpractice**](https://cran.r-project.org/web/packages/goodpractice/index.html) before 18 | submitting your change, and run spelling::spell_check_package() and lintr::lint_package(), both of which are tested. 19 | 20 | 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | inst/doc 2 | .Rproj.user 3 | .Rhistory 4 | .RData 5 | .Ruserdata 6 | *.DS_Store 7 | src/*.o 8 | src/*.so 9 | src/*.dll 10 | data-raw/* 11 | !data-raw/*.R 12 | !data-raw/country_code_data 13 | scraps/ 14 | localdb/ 15 | artifacts 16 | tests/testthat/localdb 17 | docs 18 | *_cache 19 | doc 20 | Meta 21 | *.wal 22 | -------------------------------------------------------------------------------- /.zenodo.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "citesdb", 3 | "license": "MIT", 4 | "access_right": "open", 5 | "creators": [{ 6 | "name": "Ross, Noam", 7 | "affiliation": "EcoHealth Alliance, New York, NY, USA", 8 | "orcid": "0000-0002-2136-0000" 9 | },{ 10 | "name": "Eskew, Evan A.", 11 | "affiliation": "EcoHealth Alliance, New York, NY, USA", 12 | "orcid": "0000-0002-1153-5356" 13 | },{ 14 | "name": "Nicolas Ray", 15 | "affiliation": "GeoHealth Group, Institute of Global Health, Faculty of Medicine and Institute for Environmental Sciences, University of Geneva, Geneva, Switzerland" 16 | }], 17 | "description": "A high-performance database of shipment-level CITES trade data.", 18 | "access_right": "open", 19 | "related_identifiers": [{ 20 | "identifier": "https://trade.cites.org/", 21 | "relation": "hasPart", 22 | "scheme": "url" 23 | }, { 24 | "identifier": "http://github.com/ropensci/citesdb", 25 | "relation": "isIdenticalTo", 26 | "scheme": "url" 27 | }, { 28 | "identifier": "10.21105/joss.01483", 29 | "relation": "isDocumentedBy", 30 | "scheme": "doi" 31 | }] 32 | } 33 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: citesdb 2 | Version: 0.3.0 3 | Title: A High-Performance Database of Shipment-Level 'CITES' Trade Data 4 | Description: Provides convenient access to over 40 years and 20 million records of 5 | endangered wildlife trade data from the Convention on International Trade 6 | in Endangered Species of Wild Fauna and Flora, stored on a local on-disk, 7 | out-of memory 'DuckDB' database for bulk analysis. 8 | Authors@R: c( 9 | person("Noam", "Ross", , "ross@ecohealthalliance.org", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-2136-0000")), 10 | person("Evan A.", "Eskew", , "eskew@ecohealthalliance.org", role = c("aut"), comment = c(ORCID = "0000-0002-1153-5356")), 11 | person("Nicolas", "Ray", role = "ctb"), 12 | person("UNEP World Conservation Monitoring Centre", role = c("dtc"), comment = "Maintainer of CITES Trade Database"), 13 | person("Mauricio", "Vargas", role = c("aut", "rev"), 14 | comment = "Initially reviewed package for rOpenSci: https://github.com/ropensci/software-review/issues/292"), 15 | person("Xavier", "Rotllan-Puig", role = c("rev"), 16 | comment = "Reviewed package for rOpenSci: https://github.com/ropensci/software-review/issues/292"), 17 | person("USAID PREDICT", role = "fnd"), 18 | person("EcoHealth Alliance", role = c("cph", "fnd")) 19 | ) 20 | License: MIT + file LICENSE 21 | Encoding: UTF-8 22 | LazyData: true 23 | ByteCompile: true 24 | URL: https://docs.ropensci.org/citesdb, https://github.com/ropensci/citesdb, https://www.cites.org/ 25 | BugReports: https://github.com/ropensci/citesdb/issues 26 | Imports: 27 | duckdb, 28 | rappdirs, 29 | DBI, 30 | httr, 31 | R.utils, 32 | purrr, 33 | tools, 34 | dplyr, 35 | dbplyr 36 | Suggests: 37 | spelling, 38 | testthat, 39 | roxygen2, 40 | knitr, 41 | rmarkdown, 42 | rstudioapi, 43 | lintr, 44 | callr, 45 | here, 46 | ggplot2, 47 | rcites 48 | RoxygenNote: 7.1.1.9000 49 | Roxygen: list(markdown = TRUE) 50 | Language: en-US 51 | VignetteBuilder: knitr 52 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2019 2 | COPYRIGHT HOLDER: EcoHealth Alliance 3 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # MIT License 2 | 3 | Copyright (c) 2019 EcoHealth Alliance 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(cites_codes) 4 | export(cites_db) 5 | export(cites_db_delete) 6 | export(cites_db_download) 7 | export(cites_disconnect) 8 | export(cites_metadata) 9 | export(cites_pane) 10 | export(cites_parties) 11 | export(cites_shipments) 12 | export(cites_status) 13 | importFrom(DBI,dbConnect) 14 | importFrom(DBI,dbCreateTable) 15 | importFrom(DBI,dbExecute) 16 | importFrom(DBI,dbExistsTable) 17 | importFrom(DBI,dbGetQuery) 18 | importFrom(DBI,dbIsValid) 19 | importFrom(DBI,dbListTables) 20 | importFrom(DBI,dbReadTable) 21 | importFrom(DBI,dbRemoveTable) 22 | importFrom(DBI,dbWriteTable) 23 | importFrom(R.utils,gunzip) 24 | importFrom(dplyr,"%>%") 25 | importFrom(dplyr,as_tibble) 26 | importFrom(dplyr,tbl) 27 | importFrom(duckdb,duckdb) 28 | importFrom(httr,GET) 29 | importFrom(httr,accept) 30 | importFrom(httr,content) 31 | importFrom(httr,progress) 32 | importFrom(httr,stop_for_status) 33 | importFrom(httr,write_disk) 34 | importFrom(purrr,keep) 35 | importFrom(rappdirs,user_data_dir) 36 | importFrom(tools,toTitleCase) 37 | importFrom(utils,read.table) 38 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # citesdb 0.1.0 2 | 3 | * First release with public data 4 | -------------------------------------------------------------------------------- /R/cites-guidance.R: -------------------------------------------------------------------------------- 1 | #' @title CITES Trade Database shipment-level guidance 2 | #' 3 | #' @description _This text copied from the supplementary information file 4 | #' accompanying the full database download from _ 5 | #' 6 | #' @section Recommended citation: 7 | #' 8 | #' UNEP-WCMC (Comps.) 2019. Full CITES Trade Database Download. Version 9 | #' 2019.2. CITES Secretariat, Geneva, Switzerland. Compiled by UNEP-WCMC, 10 | #' Cambridge, UK. Available at: trade.cites.org. 11 | #' 12 | #' @section Background: 13 | #' 14 | #' Under Article VIII of the Convention, Parties are required to provide 15 | #' information regarding their trade in CITES-listed specimens through their 16 | #' annual reports, and the Secretariat makes this information available 17 | #' through the CITES Trade Database (trade.cites.org). This database currently 18 | #' contains over 20 million records of international trade in CITES-listed 19 | #' species. Parties recognise the importance of these reports as a tool for 20 | #' monitoring the implementation of the Convention, assessing the 21 | #' effectiveness of their wildlife management and trade policies, and to 22 | #' enhance the detection of potentially harmful or illicit trade. 23 | #' 24 | #' At the 70th meeting of the Standing Committee, Parties agreed that a full 25 | #' non-aggregated version of the CITES Trade Database should be made available 26 | #' and updated twice a year. These files represent the periodic release of the 27 | #' CITES trade data in a shipment-by-shipment format with unique identifiers 28 | #' replacing confidential permit numbers (see [SC70 Doc 29 | #' 26.2](https://cites.org/sites/default/files/eng/com/sc/70/E-SC70-26-02.pdf 30 | #' ) and [SC70 Inf. 31 | #' 1](https://cites.org/sites/default/files/eng/com/sc/70/Inf/E-SC70-Inf-01.pdf) 32 | #' for further background). 33 | #' 34 | #' @section Overview of data: 35 | #' 36 | #' This zip file contains all trade records (including all historic data) 37 | #' entered in the CITES Trade Database by 29 January 2019 and extracted at the 38 | #' shipment level on 30 January 2019. This file is 2019.v2 and replaces 39 | #' version 2019.v1 which contained some formatting anomalies and strengthens 40 | #' security. 41 | #' 42 | #' While the data provided through the search function on the [Web Portal of 43 | #' the CITES Trade Database](https://trade.cites.org/) are aggregated, the 44 | #' database contains non-aggregated data. The data provided in this download 45 | #' is on a per-shipment basis i.e. it provides the relevant information about 46 | #' each line item in box 7 to 12 of the [CITES 47 | #' permit](https://www.cites.org/sites/default/files/document/E-Res-12-03-R17.pdf) 48 | #' (Annex 1, in line with Notification No. 2017/006) in a separate row. Each 49 | #' csv data file contains 500 thousand rows of data, and files are numbered 50 | #' chronologically with the earliest trade records in the files with the lower 51 | #' numbers. 52 | #' 53 | #' Given their confidential nature, import, export and re-export CITES permit 54 | #' numbers have been replaced with unique identifiers. This ensures that no 55 | #' confidential data are made available, whilst still enabling users of the 56 | #' data to identify instances where the same permit number may have been used 57 | #' for multiple shipments. The method for generating these unique identifiers 58 | #' is detailed below. 59 | #' 60 | #' Subsequent additions to the database will be extracted twice a year and 61 | #' added as new csv files, which will be detailed with each new release. 62 | #' 63 | #' @section Replacement of the permit number by a unique identifier: 64 | #' 65 | #' The permit numbers in the download have been replaced with a unique 66 | #' identification number (‘identifier’). This identifier is a ten character 67 | #' alpha/numeric string which is built from a cryptographically secure 68 | #' pseudo-random alpha-numeric string (which is independent of the permit 69 | #' number), which is then hashed via secure, non-reversible cryptographic hash 70 | #' function (Secure Hash Algorithm 2, SHA-512 which uses 64-bit words to 71 | #' construct the hash. SHA-512 is specified in [document FIPF PUB 180-4, 72 | #' National Institute of Technology 73 | #' (NIST)](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf)). This 74 | #' process preserves the relationship between exports and re-exports if the 75 | #' Parties have reported corresponding export and re-export permit numbers. 76 | #' Permit numbers always retain the same unique identifier in each release. 77 | #' The same unique identifier is assigned irrespective of whether the permit 78 | #' number is reported as an import, export or re-export permit. 79 | #' 80 | #' @rdname guidance 81 | #' @name guidance 82 | #' @aliases si supplementary 83 | NULL 84 | -------------------------------------------------------------------------------- /R/citesdb-package.R: -------------------------------------------------------------------------------- 1 | #' The CITES database package 2 | #' 3 | #' **citesdb** provides over 40 years of wildlife trade data from the [Convention on 4 | #' International Trade in Endangered Species of Wild Fauna and Flora](https://www.cites.org). 5 | #' These data on imports and exports of CITES annex species are provided by 6 | #' CITES member countries to the CITES secretariat. 7 | #' 8 | #' This package allows you to download the full database of historic transactions 9 | #' (commonly called the [CITES Trade Database](https://trade.cites.org/)) 10 | #' to analyze locally on your computer. Because of the large size of this data, 11 | #' the **citesdb** package stores it as an on-disk [DuckDB](https://duckdb.org/) 12 | #' that can be queried without loading into RAM. 13 | #' 14 | #' @author Noam Ross and Evan A. Eskew, [EcoHealth Alliance](https://www.ecohealthalliance.org/) 15 | #' 16 | #' 17 | # 18 | 19 | #' @keywords internal 20 | "_PACKAGE" 21 | 22 | # The following block is used by usethis to automatically manage 23 | # roxygen namespace tags. Modify with care! 24 | ## usethis namespace: start 25 | ## usethis namespace: end 26 | NULL 27 | -------------------------------------------------------------------------------- /R/connect.R: -------------------------------------------------------------------------------- 1 | #' @importFrom rappdirs user_data_dir 2 | cites_path <- function() { 3 | sys_cites_path <- Sys.getenv("CITES_DB_DIR") 4 | if (sys_cites_path == "") { 5 | return(rappdirs::user_data_dir("citesdb")) 6 | } else { 7 | return(sys_cites_path) 8 | } 9 | } 10 | 11 | cites_check_status <- function() { 12 | if (!cites_status(FALSE)) { 13 | stop("Local CITES database empty or corrupt. Download with cites_db_download()") # nolint 14 | } 15 | } 16 | 17 | #' The local CITES database 18 | #' 19 | #' Returns a connection to the local CITES database. This is a DBI-compliant 20 | #' [duckdb::duckdb()] database connection. When using **dplyr**-based 21 | #' workflows, one typically accesses tables with functions such as 22 | #' [cites_shipments()], but this function lets one interact with the database 23 | #' directly via SQL. 24 | #' 25 | #' @param dbdir The location of the database on disk. Defaults to 26 | #' `citesdb` under [rappdirs::user_data_dir()], or the environment variable `CITES_DB_DIR`. 27 | #' 28 | #' @return A DuckDB DBI connection 29 | #' @importFrom DBI dbIsValid dbConnect 30 | #' @importFrom duckdb duckdb 31 | #' @export 32 | #' 33 | #' @examples 34 | #' if (cites_status()) { 35 | #' library(DBI) 36 | #' 37 | #' dbListTables(cites_db()) 38 | #' 39 | #' parties <- dbReadTable(cites_db(), "cites_parties") 40 | #' 41 | #' dbGetQuery( 42 | #' cites_db(), 43 | #' 'SELECT "Taxon", "Importer" FROM cites_shipments WHERE "Year" = 1976 LIMIT 100;' 44 | #' ) 45 | #' } 46 | cites_db <- function(dbdir = cites_path(), read_only = TRUE) { 47 | db <- mget("cites_db", envir = citesdb:::cites_cache, ifnotfound = NA)[[1]] 48 | if (inherits(db, "DBIConnection")) { 49 | if (DBI::dbIsValid(db) && (!read_only && !dbIsReadOnly(db))) { 50 | return(db) 51 | } 52 | } 53 | dbname <- file.path(dbdir, "citesdb") 54 | dir.create(dbdir, FALSE, recursive = TRUE) 55 | 56 | # tryCatch({ 57 | db <- DBI::dbConnect(duckdb::duckdb(dbdir=dbname), debug = FALSE, read_only = read_only) 58 | # 59 | # error = function(e) { 60 | # if (grepl("(Database lock|bad rolemask)", e)) { 61 | # stop(paste( 62 | # "Local citesdb database is locked by another R session.\n", 63 | # "Try closing or running cites_disconnect() in that session." 64 | # ), 65 | # call. = FALSE 66 | # ) 67 | # } else { 68 | # stop(e) 69 | # } 70 | # }, 71 | # finally = NULL 72 | # ) 73 | 74 | assign("cites_db", db, envir = cites_cache) 75 | db 76 | } 77 | 78 | 79 | #' CITES shipment data 80 | #' 81 | #' Returns a remote database table with all CITES shipment data. This is the 82 | #' bulk of the data in the package and constitutes > 20 million records. Loading 83 | #' the whole table into R via the [dplyr::collect()] command will use over 84 | #' 3 GB of RAM, so you may want to pre-process data in the database, as in 85 | #' the examples below. 86 | #' 87 | #' @return A **dplyr** remote tibble ([dplyr::tbl()]) 88 | #' @export 89 | #' 90 | #' @examples 91 | #' if (cites_status()) { 92 | #' library(dplyr) 93 | #' 94 | #' # See the number of CITES shipment records per year 95 | #' cites_shipments() %>% 96 | #' group_by(Year) %>% 97 | #' summarize(n_records = n()) %>% 98 | #' arrange(desc(Year)) %>% 99 | #' collect() 100 | #' 101 | #' # See what pangolin shipments went to which countries in 1990 102 | #' cites_shipments() %>% 103 | #' filter(Order == "Pholidota", Year == 1990) %>% 104 | #' count(Year, Importer, Term) %>% 105 | #' collect() %>% 106 | #' left_join(select(cites_parties(), country, code), 107 | #' by = c("Importer" = "code")) 108 | #' 109 | #' } 110 | #' @importFrom dplyr tbl 111 | cites_shipments <- function() { 112 | cites_check_status() 113 | tbl(cites_db(), "cites_shipments") 114 | } 115 | 116 | #' CITES shipment metadata 117 | #' 118 | #' @description 119 | #' 120 | #' The CITES database also includes tables of column-level metadata and 121 | #' meanings of codes in columns, as well as a listing of CITES Parties/country abbreviations. 122 | #' Convenience functions access these tables. As they are small, the functions 123 | #' collect the tables into R session memory, rather than returning a remote table. 124 | #' 125 | #' This information is drawn from 126 | #' ["A guide to using the CITES Trade Database"](https://trade.cites.org/cites_trade_guidelines/en-CITES_Trade_Database_Guide.pdf), 127 | #' from the CITES website. More information on the shipment-level data can be 128 | #' found in the [guidance] help file. 129 | #' 130 | #' @return A tibble of metadata 131 | #' @export 132 | #' 133 | #' @importFrom DBI dbReadTable 134 | #' @importFrom dplyr as_tibble 135 | #' @aliases metadata cites_metadata 136 | #' @examples 137 | #' if (cites_status()) { 138 | #' library(dplyr) 139 | #' 140 | #' # See the field definitions for cites_shipments() 141 | #' cites_metadata() 142 | #' 143 | #' # See the codes used for shipment purpose 144 | #' cites_codes() %>% 145 | #' filter(field == "Purpose") 146 | #' 147 | #' # See the most recent countries to join CITES 148 | #' cites_parties() %>% 149 | #' arrange(desc(date)) %>% 150 | #' head(10) 151 | #' 152 | #' # See countries or locations with non-standaard or outdated ISO codes 153 | #' cites_parties() %>% 154 | #' filter(former_code | non_ISO_code) 155 | #' 156 | #' # For remote connections to these tables, access the database directly: 157 | #' dplyr::tbl(cites_db(), "cites_metadata") 158 | #' dplyr::tbl(cites_db(), "cites_codes") 159 | #' dplyr::tbl(cites_db(), "cites_parties") 160 | #' } 161 | cites_metadata <- function() { 162 | cites_check_status() 163 | as_tibble(dbReadTable(cites_db(), "cites_metadata")) 164 | } 165 | 166 | #' @export 167 | #' @rdname cites_metadata 168 | cites_codes <- function() { 169 | cites_check_status() 170 | as_tibble(dbReadTable(cites_db(), "cites_codes")) 171 | } 172 | 173 | #' @export 174 | #' @rdname cites_metadata 175 | cites_parties <- function() { 176 | cites_check_status() 177 | as_tibble(dbReadTable(cites_db(), "cites_parties")) 178 | } 179 | 180 | #' Disconnect from the CITES database 181 | #' 182 | #' A utility function for disconnecting from the database. 183 | #' 184 | #' @examples 185 | #' cites_disconnect() 186 | #' @export 187 | #' 188 | cites_disconnect <- function() { 189 | cites_disconnect_() 190 | } 191 | cites_disconnect_ <- function(environment = cites_cache) { # nolint 192 | db <- mget("cites_db", envir = cites_cache, ifnotfound = NA)[[1]] 193 | if (inherits(db, "DBIConnection")) { 194 | DBI::dbDisconnect(db, shutdown = TRUE) 195 | } 196 | observer <- getOption("connectionObserver") 197 | if (!is.null(observer)) { 198 | observer$connectionClosed("CITESDB", "citesdb") 199 | } 200 | } 201 | 202 | cites_cache <- new.env() 203 | reg.finalizer(cites_cache, cites_disconnect_, onexit = TRUE) 204 | -------------------------------------------------------------------------------- /R/connection-pane.R: -------------------------------------------------------------------------------- 1 | sql_action <- function() { 2 | if (requireNamespace("rstudioapi", quietly = TRUE) && 3 | exists("documentNew", asNamespace("rstudioapi"))) { 4 | contents <- paste( 5 | "-- !preview conn=citesdb::cites_db()", 6 | "", 7 | "SELECT * FROM cites_shipments LIMIT 100", 8 | "", 9 | sep = "\n" 10 | ) 11 | 12 | rstudioapi::documentNew( 13 | text = contents, type = "sql", 14 | position = rstudioapi::document_position(2, 40), 15 | execute = FALSE 16 | ) 17 | } 18 | } 19 | 20 | #' Open CITES database connection pane in RStudio 21 | #' 22 | #' This function launches the RStudio "Connection" pane to interactively 23 | #' explore the database. 24 | #' 25 | #' @return NULL 26 | #' @export 27 | #' 28 | #' @examples 29 | #' if (!is.null(getOption("connectionObserver"))) cites_pane() 30 | cites_pane <- function() { 31 | observer <- getOption("connectionObserver") 32 | if (!is.null(observer) && interactive() && !inherits(try(citesdb::cites_db(),silent = TRUE), "try-error")) { 33 | observer$connectionOpened( 34 | type = "CITESDB", 35 | host = "citesdb", 36 | displayName = "CITES Transaction Tables", 37 | icon = system.file("img", "eha_logo.png", package = "citesdb"), 38 | connectCode = "citesdb::cites_pane()", 39 | disconnect = citesdb::cites_disconnect, 40 | listObjectTypes = function() { 41 | list( 42 | table = list(contains = "data") 43 | ) 44 | }, 45 | listObjects = function(type = "datasets") { 46 | tbls <- DBI::dbListTables(cites_db()) 47 | data.frame( 48 | name = tbls, 49 | type = rep("table", length(tbls)), 50 | stringsAsFactors = FALSE 51 | ) 52 | }, 53 | listColumns = function(table) { 54 | res <- DBI::dbGetQuery(cites_db(), 55 | paste("SELECT * FROM", table, "LIMIT 1")) 56 | data.frame( 57 | name = names(res), type = vapply(res, function(x) class(x)[1], character(1)), 58 | stringsAsFactors = FALSE 59 | ) 60 | }, 61 | previewObject = function(rowLimit, table) { #nolint 62 | DBI::dbGetQuery(cites_db(), 63 | paste("SELECT * FROM", table, "LIMIT", rowLimit)) 64 | }, 65 | actions = list( 66 | Status = list( 67 | icon = system.file("img", "cites-logo.png", package = "citesdb"), 68 | callback = cites_status 69 | ), 70 | SQL = list( 71 | icon = system.file("img", "edit-sql.png", package = "citesdb"), 72 | callback = sql_action 73 | ) 74 | ), 75 | connectionObject = cites_db() 76 | ) 77 | } 78 | } 79 | 80 | update_cites_pane <- function() { 81 | observer <- getOption("connectionObserver") 82 | if (!is.null(observer)) { 83 | observer$connectionUpdated("CITESDB", "citesdb", "") 84 | } 85 | } 86 | -------------------------------------------------------------------------------- /R/download.R: -------------------------------------------------------------------------------- 1 | #' Download the CITES database to your local computer 2 | #' 3 | #' This command downloads the CITES shipments database and populates a local 4 | #' database. The download is large (~158 MB), and the database will be ~5 GB 5 | #' on disk. During import 10 GB of disk space may be used temporarily. 6 | #' 7 | #' The database is stored by default under [rappdirs::user_data_dir()], or its 8 | #' location can be set with the environment variable `CITES_DB_DIR`. 9 | #' 10 | #' @param tag What release tag of data to download. Defaults to the most recent. 11 | #' Releases are expected to come twice per year. See all releases at 12 | #' . 13 | #' @param destdir Where to download the compressed file. 14 | #' @param cleanup Whether to delete the compressed file after loading into the database. 15 | #' @param verbose Whether to display messages and download progress 16 | #' 17 | #' @return NULL 18 | #' @export 19 | #' @importFrom DBI dbRemoveTable dbExistsTable dbCreateTable dbExecute 20 | #' dbWriteTable dbListTables 21 | #' @importFrom R.utils gunzip 22 | #' @importFrom dplyr %>% 23 | #' 24 | #' @examples 25 | #' \donttest{ 26 | #' \dontrun{ 27 | #' cites_db_download() 28 | #' } 29 | #' } 30 | cites_db_download <- function(tag = NULL, destdir = tempdir(), 31 | cleanup = TRUE, verbose = interactive()) { 32 | 33 | if (verbose) message("Downloading data...\n") 34 | zfile <- get_gh_release_file("ropensci/citesdb", 35 | tag_name = tag, 36 | destdir = destdir, verbose = verbose 37 | ) 38 | ver <- attr(zfile, "ver") 39 | if (verbose) message("Decompressing and building local database...\n") 40 | temp_tsv <- tempfile(fileext = ".tsv") 41 | gunzip(zfile, destname = temp_tsv, overwrite = TRUE, remove = cleanup) 42 | 43 | # for (tab in dbListTables(cites_db())) { 44 | # dbRemoveTable(cites_db(), tab) 45 | # } 46 | # cites_disconnect() 47 | # invisible(cites_db()) 48 | unlink(cites_path(), recursive = TRUE, force = TRUE, expand = FALSE) 49 | 50 | tblname <- "cites_shipments" 51 | 52 | try(dbRemoveTable(cites_db(read_only = FALSE), tblname), silent = TRUE) 53 | cites_disconnect() 54 | dbCreateTable(cites_db(read_only = FALSE), tblname, fields = cites_field_types) 55 | 56 | suppressMessages( 57 | dbExecute( 58 | cites_db(), 59 | paste0( 60 | "COPY ", tblname, " FROM '", 61 | temp_tsv, 62 | "' ( DELIMITER '\t', HEADER 1, NULL 'NA' )" 63 | ) 64 | ) 65 | ) 66 | cites_disconnect() 67 | dbWriteTable(cites_db(read_only = FALSE), "cites_status", make_status_table(version = ver), 68 | overwrite = TRUE 69 | ) 70 | 71 | load_citesdb_metadata() 72 | 73 | file.remove(temp_tsv) 74 | 75 | update_cites_pane() 76 | 77 | cites_status() 78 | cites_disconnect() 79 | } 80 | 81 | cites_field_types <- c( 82 | Id = "STRING", 83 | Year = "INTEGER", 84 | Appendix = "STRING", 85 | Taxon = "STRING", 86 | Class = "STRING", 87 | Order = "STRING", 88 | Family = "STRING", 89 | Genus = "STRING", 90 | Term = "STRING", 91 | Quantity = "DOUBLE PRECISION", 92 | Unit = "STRING", 93 | Importer = "STRING", 94 | Exporter = "STRING", 95 | Origin = "STRING", 96 | Purpose = "STRING", 97 | Source = "STRING", 98 | Reporter.type = "STRING", 99 | Import.permit.RandomID = "STRING", 100 | Export.permit.RandomID = "STRING", 101 | Origin.permit.RandomID = "STRING" 102 | ) 103 | 104 | #' @importFrom DBI dbGetQuery 105 | make_status_table <- function(version) { 106 | sz <- sum(file.info(list.files(cites_path(), 107 | all.files = TRUE, 108 | recursive = TRUE, 109 | full.names = TRUE))$size) 110 | class(sz) <- "object_size" 111 | data.frame( 112 | time_imported = Sys.time(), 113 | version = version, 114 | number_of_records = formatC( 115 | DBI::dbGetQuery(cites_db(), 116 | "SELECT COUNT(*) FROM cites_shipments;")[[1]], 117 | format = "d", big.mark = ","), 118 | size_on_disk = format(sz, "auto"), 119 | location_on_disk = cites_path() 120 | ) 121 | } 122 | 123 | #' @importFrom httr GET stop_for_status content accept write_disk progress 124 | #' @importFrom purrr keep 125 | get_gh_release_file <- function(repo, tag_name = NULL, destdir = tempdir(), 126 | overwrite = TRUE, verbose = interactive()) { 127 | releases <- GET( 128 | paste0("https://api.github.com/repos/", repo, "/releases") 129 | ) 130 | stop_for_status(releases, "finding releases") 131 | 132 | releases <- content(releases) 133 | 134 | if (is.null(tag_name)) { 135 | release_obj <- releases[1] 136 | } else { 137 | release_obj <- purrr::keep(releases, function(x) x$tag_name == tag_name) 138 | } 139 | 140 | if (!length(release_obj)) stop("No release tagged \"", tag_name, "\"") 141 | 142 | if (release_obj[[1]]$prerelease) { 143 | message("This is pre-release/sample data! It has not been cleaned or validated.") #nolint 144 | } 145 | 146 | download_url <- release_obj[[1]]$assets[[1]]$url 147 | filename <- basename(release_obj[[1]]$assets[[1]]$browser_download_url) 148 | out_path <- normalizePath(file.path(destdir, filename), mustWork = FALSE) 149 | response <- GET( 150 | download_url, 151 | accept("application/octet-stream"), 152 | write_disk(path = out_path, overwrite = overwrite), 153 | if (verbose) progress() 154 | ) 155 | stop_for_status(response, "downloading data") 156 | 157 | attr(out_path, "ver") <- release_obj[[1]]$tag_name 158 | return(out_path) 159 | } 160 | 161 | #' @importFrom utils read.table 162 | load_citesdb_metadata <- function() { 163 | tsvs <- list.files(system.file("extdata", package = "citesdb"), 164 | pattern = "\\.tsv$", full.names = TRUE 165 | ) 166 | tblnames <- tools::file_path_sans_ext(basename(tsvs)) 167 | for (i in seq_along(tsvs)) { 168 | suppressMessages(dbWriteTable(cites_db(), tblnames[i], 169 | read.table( 170 | tsvs[i], 171 | stringsAsFactors = FALSE, sep = "\t", 172 | header = TRUE, quote = "\"" 173 | ), 174 | overwrite = TRUE 175 | )) 176 | } 177 | } 178 | -------------------------------------------------------------------------------- /R/onattach.R: -------------------------------------------------------------------------------- 1 | in_chk <- function() { 2 | any( 3 | grepl("check", 4 | sapply(sys.calls(), function(a) paste(deparse(a), collapse = "\n")) 5 | ) 6 | ) 7 | } 8 | 9 | .onAttach <- function(libname, pkgname) { #nolint 10 | if (interactive() && Sys.getenv("RSTUDIO") == "1" && !in_chk()) { 11 | cites_pane() 12 | } 13 | if (interactive()) cites_status() 14 | } 15 | 16 | #' Remove the local CITES database 17 | #' 18 | #' Deletes all tables from the local database 19 | #' 20 | #' @return NULL 21 | #' @export 22 | #' @importFrom DBI dbListTables dbRemoveTable 23 | #' 24 | #' @examples 25 | #' \donttest{ 26 | #' \dontrun{ 27 | #' cites_db_delete() 28 | #' } 29 | #' } 30 | cites_db_delete <- function() { 31 | cites_disconnect() 32 | unlink(cites_path(), recursive = TRUE, force = TRUE, expand = FALSE) 33 | } 34 | 35 | 36 | #' Get the status of the current local CITES database 37 | #' 38 | #' @param verbose Whether to print a status message 39 | #' 40 | #' @return TRUE if the database exists, FALSE if it is not detected. (invisible) 41 | #' @export 42 | #' @importFrom DBI dbExistsTable 43 | #' @importFrom tools toTitleCase 44 | #' @examples 45 | #' cites_status() 46 | cites_status <- function(verbose = TRUE) { 47 | if (DBI::dbExistsTable(cites_db(), "cites_shipments") && 48 | DBI::dbExistsTable(cites_db(), "cites_status")) { 49 | status <- DBI::dbReadTable(cites_db(), "cites_status") 50 | status_msg <- 51 | paste0( 52 | "CITES database status:\n", 53 | paste0(toTitleCase(gsub("_", " ", names(status))), 54 | ": ", as.matrix(status), 55 | collapse = "\n" 56 | ) 57 | ) 58 | out <- TRUE 59 | } else { 60 | status_msg <- "Local CITES database empty or corrupt. Download with cites_db_download()" #nolint 61 | out <- FALSE 62 | } 63 | if (verbose) message(status_msg) 64 | invisible(out) 65 | } 66 | -------------------------------------------------------------------------------- /README-not.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | # citesdb 5 | 6 | Authors: *Noam Ross, Evan A. Eskew and Mauricio Vargas* 7 | 8 | 9 | 10 | [![License: 11 | MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) 12 | [![rOpensci\_Badge](https://badges.ropensci.org/292_status.svg)](https://github.com/ropensci/software-review/issues/292) 13 | [![Published in the Journal of Open Source 14 | Software](http://joss.theoj.org/papers/10.21105/joss.01483/status.svg)](https://doi.org/10.21105/joss.01483) 15 | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2630836.svg)](https://doi.org/10.5281/zenodo.2630836) 16 | [![CircleCI](https://circleci.com/gh/ropensci/citesdb/tree/master.svg?style=shield)](https://circleci.com/gh/ropensci/citesdb) 17 | [![codecov](https://codecov.io/gh/ropensci/citesdb/branch/master/graph/badge.svg)](https://codecov.io/gh/ropensci/citesdb) 18 | [![Project Status: Active – The project has reached a stable, usable 19 | state and is being actively 20 | developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) 21 | 22 | 23 | 24 | **citesdb** is an R package to conveniently analyze the full CITES 25 | shipment-level wildlife trade database, available at 26 | . This data consists of over 40 years and 20 27 | million records of reported shipments of wildlife and wildlife products 28 | subject to oversight under the [Convention on International Trade in 29 | Endangered Species of Wild Fauna and Flora](https://www.cites.org). The 30 | source data are maintained by the [UN Environment World Conservation 31 | Monitoring Centre](https://www.unep-wcmc.org/). 32 | 33 | ## Installation 34 | 35 | Install the **citesdb** package with this command: 36 | 37 | ``` r 38 | devtools::install_github("ropensci/citesdb") 39 | ``` 40 | 41 | Note that since **citesdb** installs a source dependency from GitHub, 42 | you will need [package build 43 | tools](http://stat545.com/packages01_system-prep.html). 44 | 45 | ## Usage 46 | 47 | ### Getting the data 48 | 49 | When you first load the package, you will see a message like this: 50 | 51 | library(citesdb) 52 | #> Local CITES database empty or corrupt. Download with cites_db_download() 53 | 54 | Not to worry, just do as it says and run `cites_db_download()`. This 55 | will fetch the most recent database from online, an approximately 158 MB 56 | download. It will expand to over 1 GB in the local database. During the 57 | download and database building, up to 3.5 GB of disk space may be used 58 | temporarily. 59 | 60 | ### Using the database 61 | 62 | Once you fetch the data, you can connect to the database with the 63 | `cites_db()` command. The `cites_shipments()` command loads a remote 64 | `tibble` that is backed by the database but is not loaded into R. You 65 | can use this command to analyze CITES data without ever loading it into 66 | memory, gathering your results with the `dplyr` function `collect()`. 67 | For example: 68 | 69 | ``` r 70 | library(citesdb) 71 | library(dplyr) 72 | 73 | start <- Sys.time() 74 | 75 | cites_shipments() %>% 76 | group_by(Year) %>% 77 | summarize(n_records = n()) %>% 78 | arrange(desc(Year)) %>% 79 | collect() 80 | #> # A tibble: 45 x 2 81 | #> Year n_records 82 | #> 83 | #> 1 2019 12610 84 | #> 2 2018 1143044 85 | #> 3 2017 1246684 86 | #> 4 2016 1293178 87 | #> 5 2015 1299183 88 | #> 6 2014 1109877 89 | #> 7 2013 1127377 90 | #> 8 2012 1096664 91 | #> 9 2011 950148 92 | #> 10 2010 894115 93 | #> # … with 35 more rows 94 | 95 | stop <- Sys.time() 96 | ``` 97 | 98 | (*Note that running `collect()` on all of `cites_shipments()` will load 99 | a \>3 GB data frame into memory\!*) 100 | 101 | The back-end database, [duckdb](https://duckdb.org/), is very fast and 102 | powerful, making analyses on such large data quite snappy using normal 103 | desktops and laptops. Here’s the timing of the above query, which 104 | processes over 20 million records: 105 | 106 | ``` r 107 | stop - start 108 | #> Time difference of 0.4658868 secs 109 | ``` 110 | 111 | If you are using a recent version of RStudio interactively, loading the 112 | CITES package also brings up a browsable pane in the “Connections” tab 113 | that lets you explore and preview the database, as well as interact with 114 | it directly via SQL commands. 115 | 116 | If you don’t need any of the bells and whistles of this package, you can 117 | download the raw data as a single compressed TSV file from the [releases 118 | page](https://github.com/ropensci/citesdb/releases), or as a `.zip` file 119 | of many CSV files from the original source at 120 | . 121 | 122 | ### Metadata 123 | 124 | The package database also contains tables of field metadata, codes used, 125 | and CITES countries. This information comes from [“A guide to using the 126 | CITES Trade 127 | Database”](https://trade.cites.org/cites_trade_guidelines/en-CITES_Trade_Database_Guide.pdf), 128 | on the CITES website. Convenience functions `cites_metadata()`, 129 | `cites_codes()`, and `cites_parties()` access this information: 130 | 131 | ``` r 132 | head(cites_metadata()) 133 | #> # A tibble: 6 x 2 134 | #> variable description 135 | #> 136 | #> 1 Year year in which trade occurred 137 | #> 2 Appendix CITES Appendix of taxon concerned 138 | #> 3 Taxon scientific name of animal or plant concerned 139 | #> 4 Class scientific name of animal or plant concerned 140 | #> 5 Order scientific name of animal or plant concerned 141 | #> 6 Family scientific name of animal or plant concerned 142 | 143 | head(cites_codes()) 144 | #> # A tibble: 6 x 3 145 | #> field code description 146 | #> 147 | #> 1 Purpose B Breeding in captivity or artificial propagation 148 | #> 2 Purpose E Educational 149 | #> 3 Purpose G Botanical garden 150 | #> 4 Purpose H Hunting trophy 151 | #> 5 Purpose L Law enforcement / judicial / forensic 152 | #> 6 Purpose M Medical (including biomedical research) 153 | 154 | head(cites_parties()) 155 | #> # A tibble: 6 x 6 156 | #> country code former_code non_ISO_code date data_source 157 | #> 158 | #> 1 Afghanistan AF FALSE FALSE 1986-01-28 'A guide to using the CITES Trade Database', Version 8, Anne… 159 | #> 2 Africa XF FALSE TRUE 'A guide to using the CITES Trade Database', Version 8, Anne… 160 | #> 3 Åland Islands AX FALSE FALSE 'A guide to using the CITES Trade Database', Version 8, Anne… 161 | #> 4 Albania AL FALSE FALSE 2003-09-25 'A guide to using the CITES Trade Database', Version 8, Anne… 162 | #> 5 Algeria DZ FALSE FALSE 1984-02-21 'A guide to using the CITES Trade Database', Version 8, Anne… 163 | #> 6 American Samoa AS FALSE FALSE 'A guide to using the CITES Trade Database', Version 8, Anne… 164 | ``` 165 | 166 | More information on the release of shipment-level CITES data can be 167 | found in the `?guidance` help file. 168 | 169 | ## Related work 170 | 171 | The [**rcites**](https://github.com/ropensci/rcites) package provides 172 | access to the Speciesplus/CITES Checklist API, which includes metadata 173 | about species and their protected status through time. 174 | 175 | ## Citation 176 | 177 | If you use **citesdb** in a publication, please cite both the package 178 | and source data: 179 | 180 | Ross, Noam, Evan A. Eskew, and Nicolas Ray. 2019. citesdb: An R package 181 | to support analysis of CITES Trade Database shipment-level data. Journal 182 | of Open Source Software, 4(37), 1483, 183 | 184 | 185 | UNEP-WCMC (Comps.) 2019. Full CITES Trade Database Download. Version 186 | 2019.2. CITES Secretariat, Geneva, Switzerland. Compiled by UNEP-WCMC, 187 | Cambridge, UK. Available at: . 188 | 189 | ## Contributing 190 | 191 | Have feedback or want to contribute? Great\! Please take a look at the 192 | [contributing 193 | guidelines](https://github.com/ropensci/citesdb/blob/master/.github/CONTRIBUTING.md) 194 | before filing an issue or pull request. 195 | 196 | Please note that this project is released with a [Contributor Code of 197 | Conduct](https://github.com/ropensci/citesdb/blob/master/.github/CODE_OF_CONDUCT.md). 198 | By participating in this project you agree to abide by its terms. 199 | 200 | [![Created by EcoHealth 201 | Alliance](https://raw.githubusercontent.com/ropensci/citesdb/master/vignettes/figures/eha-footer.png)](https://www.ecohealthalliance.org/) 202 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | output: 3 | github_document: 4 | html_preview: FALSE 5 | --- 6 | 7 | 8 | 9 | ```{r setup, include = FALSE} 10 | knitr::opts_chunk$set( 11 | collapse = TRUE, 12 | comment = "#>", 13 | fig.path = "man/figures/README-", 14 | out.width = "100%" 15 | ) 16 | 17 | library(dplyr) 18 | ``` 19 | 20 | 21 | # citesdb 22 | 23 | ```{r authors, echo = FALSE, results = 'asis'} 24 | unclass(desc::desc_get_authors(here::here("DESCRIPTION"))) %>% 25 | purrr::keep(~"aut" %in% .$role) %>% 26 | purrr::map_chr(~paste(.$given, .$family)) %>% 27 | glue::glue_collapse(sep = ", ", last = " and ") %>% 28 | paste0("Authors: _", ., "_") %>% 29 | cat() 30 | ``` 31 | 32 | 33 | 34 | [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg){data-external="1"}](https://opensource.org/licenses/MIT) 35 | [![rOpensci\_Badge](https://badges.ropensci.org/292_status.svg)](https://github.com/ropensci/software-review/issues/292) 36 | [![Published in the Journal of Open Source Software](http://joss.theoj.org/papers/10.21105/joss.01483/status.svg){data-external="1"}](https://doi.org/10.21105/joss.01483) 37 | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2630836.svg){data-external="1"}](https://doi.org/10.5281/zenodo.2630836) 38 | [![CircleCI](https://circleci.com/gh/ropensci/citesdb/tree/master.svg?style=shield){data-external="1"}](https://circleci.com/gh/ropensci/citesdb) 39 | [![codecov](https://codecov.io/gh/ropensci/citesdb/branch/master/graph/badge.svg){data-external="1"}](https://codecov.io/gh/ropensci/citesdb) 40 | [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) 41 | 42 | 43 | 44 | **citesdb** is an R package to conveniently analyze the full CITES shipment-level wildlife trade database, available at . This data consists of over 40 years and 20 million records of reported shipments of wildlife and wildlife products subject to oversight under the [Convention on International Trade in Endangered Species of Wild Fauna and Flora](https://www.cites.org). The source data are maintained by the [UN Environment World Conservation Monitoring Centre](https://www.unep-wcmc.org/). 45 | 46 | 47 | ## Installation 48 | 49 | Install the **citesdb** package with this command: 50 | 51 | ```{r install_me, eval = FALSE} 52 | devtools::install_github("ropensci/citesdb") 53 | ``` 54 | 55 | Note that since **citesdb** installs a source dependency from GitHub, you 56 | will need [package build tools](http://stat545.com/packages01_system-prep.html). 57 | 58 | ```{r message = FALSE, warning = FALSE, error = FALSE, include = FALSE} 59 | options(width = 120) 60 | knitr::opts_chunk$set(cache = TRUE) 61 | citesdb::cites_disconnect() 62 | ``` 63 | 64 | 65 | ## Usage 66 | 67 | ### Getting the data 68 | 69 | When you first load the package, you will see a message like this: 70 | 71 | library(citesdb) 72 | #> Local CITES database empty or corrupt. Download with cites_db_download() 73 | 74 | Not to worry, just do as it says and run `cites_db_download()`. This will fetch the most recent database from online, an approximately 158 MB download. It will expand to over 1 GB in the local database. During the download and database building, up to 3.5 GB of disk space may be used temporarily. 75 | 76 | ### Using the database 77 | 78 | Once you fetch the data, you can connect to the database with the `cites_db()` command. The `cites_shipments()` command loads a remote `tibble` that is backed by the database but is not loaded into R. You can use this command to analyze CITES data without ever loading it into memory, gathering your results with the `dplyr` function `collect()`. For example: 79 | 80 | ```{r getdata, include = FALSE} 81 | if (!citesdb::cites_status()) citesdb::cites_db_download() 82 | ``` 83 | 84 | ```{r, warning = FALSE} 85 | library(citesdb) 86 | library(dplyr) 87 | 88 | start <- Sys.time() 89 | 90 | cites_shipments() %>% 91 | group_by(Year) %>% 92 | summarize(n_records = n()) %>% 93 | arrange(desc(Year)) %>% 94 | collect() 95 | 96 | stop <- Sys.time() 97 | ``` 98 | 99 | (_Note that running `collect()` on all of `cites_shipments()` will load a >3 GB data frame into memory!_) 100 | 101 | The back-end database, [duckdb](https://duckdb.org/), is very fast and powerful, making analyses on such large data quite snappy using normal desktops and laptops. Here's the timing of the above query, which processes over 20 million records: 102 | 103 | ```{r} 104 | stop - start 105 | ``` 106 | 107 | If you are using a recent version of RStudio interactively, loading the CITES package also brings up a browsable pane in the "Connections" tab that lets you explore and preview the database, as well as interact with it directly via SQL commands. 108 | 109 | If you don't need any of the bells and whistles of this package, you can download the raw data as a single compressed TSV file from the [releases page](https://github.com/ropensci/citesdb/releases), or as a `.zip` file of many CSV files from the original source at . 110 | 111 | ### Metadata 112 | 113 | The package database also contains tables of field metadata, codes used, and CITES countries. This information comes from ["A guide to using the CITES Trade Database"](https://trade.cites.org/cites_trade_guidelines/en-CITES_Trade_Database_Guide.pdf), on the CITES website. Convenience functions `cites_metadata()`, `cites_codes()`, and `cites_parties()` access this information: 114 | 115 | ```{r} 116 | head(cites_metadata()) 117 | 118 | head(cites_codes()) 119 | 120 | head(cites_parties()) 121 | ``` 122 | 123 | ```{r message = FALSE, warning = FALSE, error = FALSE, include = FALSE} 124 | citesdb::cites_disconnect() 125 | ``` 126 | 127 | More information on the release of shipment-level CITES data can be found in the `?guidance` help file. 128 | 129 | 130 | ## Related work 131 | 132 | The [**rcites**](https://github.com/ropensci/rcites) package provides access to the Speciesplus/CITES Checklist API, which includes metadata about species and their protected status through time. 133 | 134 | 135 | ## Citation 136 | 137 | If you use **citesdb** in a publication, please cite both the package and source data: 138 | 139 | ```{r, results = "asis", echo = FALSE} 140 | print(citation("citesdb"), style = "textVersion") 141 | ``` 142 | 143 | 144 | ## Contributing 145 | 146 | Have feedback or want to contribute? Great! Please take a look at the [contributing guidelines](https://github.com/ropensci/citesdb/blob/master/.github/CONTRIBUTING.md) before filing an issue or pull request. 147 | 148 | Please note that this project is released with a [Contributor Code of Conduct](https://github.com/ropensci/citesdb/blob/master/.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. 149 | 150 | [![Created by EcoHealth Alliance](https://raw.githubusercontent.com/ropensci/citesdb/master/vignettes/figures/eha-footer.png){data-external="1"}](https://www.ecohealthalliance.org/) 151 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # citesdb 2 | 3 | [![Project Status: Unsupported](https://www.repostatus.org/badges/latest/unsupported.svg)](https://www.repostatus.org/#unsupported) 4 | [![Peer-review badge](https://badges.ropensci.org/292_status.svg)](https://github.com/ropensci/software-review/issues/292) 5 | 6 | This package has been archived. The former README is now in [README-not](README-not.md). 7 | -------------------------------------------------------------------------------- /citesdb.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: No 4 | SaveWorkspace: No 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: XeLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | PackageRoxygenize: rd,collate,namespace,vignette 22 | -------------------------------------------------------------------------------- /codemeta.json: -------------------------------------------------------------------------------- 1 | { 2 | "@context": [ 3 | "https://doi.org/10.5063/schema/codemeta-2.0", 4 | "http://schema.org" 5 | ], 6 | "@type": "SoftwareSourceCode", 7 | "identifier": "citesdb", 8 | "description": "Provides convenient access to over 40 years and 20 million records of\n endangered wildlife trade data from the Convention on International Trade\n in Endangered Species of Wild Fauna and Flora, stored on a local on-disk,\n out-of memory 'DuckDB' database for bulk analysis.", 9 | "name": "citesdb: A High-Performance Database of Shipment-Level 'CITES' Trade Data", 10 | "codeRepository": "https://github.com/ropensci/citesdb", 11 | "relatedLink": [ 12 | "https://docs.ropensci.org/citesdb", 13 | "https://www.cites.org/" 14 | ], 15 | "issueTracker": "https://github.com/ropensci/citesdb/issues", 16 | "license": "https://spdx.org/licenses/MIT", 17 | "version": "0.3.0", 18 | "programmingLanguage": { 19 | "@type": "ComputerLanguage", 20 | "name": "R", 21 | "url": "https://r-project.org" 22 | }, 23 | "runtimePlatform": "R version 3.6.3 (2020-02-29)", 24 | "author": [ 25 | { 26 | "@type": "Person", 27 | "givenName": "Noam", 28 | "familyName": "Ross", 29 | "email": "ross@ecohealthalliance.org", 30 | "@id": "https://orcid.org/0000-0002-2136-0000" 31 | }, 32 | { 33 | "@type": "Person", 34 | "givenName": "Evan A.", 35 | "familyName": "Eskew", 36 | "email": "eskew@ecohealthalliance.org", 37 | "@id": "https://orcid.org/0000-0002-1153-5356" 38 | }, 39 | { 40 | "@type": "Person", 41 | "givenName": "Mauricio", 42 | "familyName": "Vargas" 43 | } 44 | ], 45 | "contributor": [ 46 | { 47 | "@type": "Person", 48 | "givenName": "Nicolas", 49 | "familyName": "Ray" 50 | }, 51 | { 52 | "@type": "Organization", 53 | "name": "UNEP World Conservation Monitoring Centre" 54 | } 55 | ], 56 | "copyrightHolder": [ 57 | { 58 | "@type": "Organization", 59 | "name": "EcoHealth Alliance" 60 | } 61 | ], 62 | "funder": [ 63 | { 64 | "@type": "Organization", 65 | "name": "USAID PREDICT" 66 | }, 67 | { 68 | "@type": "Organization", 69 | "name": "EcoHealth Alliance" 70 | } 71 | ], 72 | "maintainer": [ 73 | { 74 | "@type": "Person", 75 | "givenName": "Noam", 76 | "familyName": "Ross", 77 | "email": "ross@ecohealthalliance.org", 78 | "@id": "https://orcid.org/0000-0002-2136-0000" 79 | } 80 | ], 81 | "softwareSuggestions": [ 82 | { 83 | "@type": "SoftwareApplication", 84 | "identifier": "spelling", 85 | "name": "spelling", 86 | "provider": { 87 | "@id": "https://cran.r-project.org", 88 | "@type": "Organization", 89 | "name": "Comprehensive R Archive Network (CRAN)", 90 | "url": "https://cran.r-project.org" 91 | }, 92 | "sameAs": "https://CRAN.R-project.org/package=spelling" 93 | }, 94 | { 95 | "@type": "SoftwareApplication", 96 | "identifier": "testthat", 97 | "name": "testthat", 98 | "provider": { 99 | "@id": "https://cran.r-project.org", 100 | "@type": "Organization", 101 | "name": "Comprehensive R Archive Network (CRAN)", 102 | "url": "https://cran.r-project.org" 103 | }, 104 | "sameAs": "https://CRAN.R-project.org/package=testthat" 105 | }, 106 | { 107 | "@type": "SoftwareApplication", 108 | "identifier": "roxygen2", 109 | "name": "roxygen2", 110 | "provider": { 111 | "@id": "https://cran.r-project.org", 112 | "@type": "Organization", 113 | "name": "Comprehensive R Archive Network (CRAN)", 114 | "url": "https://cran.r-project.org" 115 | }, 116 | "sameAs": "https://CRAN.R-project.org/package=roxygen2" 117 | }, 118 | { 119 | "@type": "SoftwareApplication", 120 | "identifier": "knitr", 121 | "name": "knitr", 122 | "provider": { 123 | "@id": "https://cran.r-project.org", 124 | "@type": "Organization", 125 | "name": "Comprehensive R Archive Network (CRAN)", 126 | "url": "https://cran.r-project.org" 127 | }, 128 | "sameAs": "https://CRAN.R-project.org/package=knitr" 129 | }, 130 | { 131 | "@type": "SoftwareApplication", 132 | "identifier": "rmarkdown", 133 | "name": "rmarkdown", 134 | "provider": { 135 | "@id": "https://cran.r-project.org", 136 | "@type": "Organization", 137 | "name": "Comprehensive R Archive Network (CRAN)", 138 | "url": "https://cran.r-project.org" 139 | }, 140 | "sameAs": "https://CRAN.R-project.org/package=rmarkdown" 141 | }, 142 | { 143 | "@type": "SoftwareApplication", 144 | "identifier": "rstudioapi", 145 | "name": "rstudioapi", 146 | "provider": { 147 | "@id": "https://cran.r-project.org", 148 | "@type": "Organization", 149 | "name": "Comprehensive R Archive Network (CRAN)", 150 | "url": "https://cran.r-project.org" 151 | }, 152 | "sameAs": "https://CRAN.R-project.org/package=rstudioapi" 153 | }, 154 | { 155 | "@type": "SoftwareApplication", 156 | "identifier": "lintr", 157 | "name": "lintr", 158 | "provider": { 159 | "@id": "https://cran.r-project.org", 160 | "@type": "Organization", 161 | "name": "Comprehensive R Archive Network (CRAN)", 162 | "url": "https://cran.r-project.org" 163 | }, 164 | "sameAs": "https://CRAN.R-project.org/package=lintr" 165 | }, 166 | { 167 | "@type": "SoftwareApplication", 168 | "identifier": "callr", 169 | "name": "callr", 170 | "provider": { 171 | "@id": "https://cran.r-project.org", 172 | "@type": "Organization", 173 | "name": "Comprehensive R Archive Network (CRAN)", 174 | "url": "https://cran.r-project.org" 175 | }, 176 | "sameAs": "https://CRAN.R-project.org/package=callr" 177 | }, 178 | { 179 | "@type": "SoftwareApplication", 180 | "identifier": "here", 181 | "name": "here", 182 | "provider": { 183 | "@id": "https://cran.r-project.org", 184 | "@type": "Organization", 185 | "name": "Comprehensive R Archive Network (CRAN)", 186 | "url": "https://cran.r-project.org" 187 | }, 188 | "sameAs": "https://CRAN.R-project.org/package=here" 189 | }, 190 | { 191 | "@type": "SoftwareApplication", 192 | "identifier": "ggplot2", 193 | "name": "ggplot2", 194 | "provider": { 195 | "@id": "https://cran.r-project.org", 196 | "@type": "Organization", 197 | "name": "Comprehensive R Archive Network (CRAN)", 198 | "url": "https://cran.r-project.org" 199 | }, 200 | "sameAs": "https://CRAN.R-project.org/package=ggplot2" 201 | }, 202 | { 203 | "@type": "SoftwareApplication", 204 | "identifier": "rcites", 205 | "name": "rcites", 206 | "provider": { 207 | "@id": "https://cran.r-project.org", 208 | "@type": "Organization", 209 | "name": "Comprehensive R Archive Network (CRAN)", 210 | "url": "https://cran.r-project.org" 211 | }, 212 | "sameAs": "https://CRAN.R-project.org/package=rcites" 213 | } 214 | ], 215 | "softwareRequirements": [ 216 | { 217 | "@type": "SoftwareApplication", 218 | "identifier": "duckdb", 219 | "name": "duckdb", 220 | "provider": { 221 | "@id": "https://cran.r-project.org", 222 | "@type": "Organization", 223 | "name": "Comprehensive R Archive Network (CRAN)", 224 | "url": "https://cran.r-project.org" 225 | }, 226 | "sameAs": "https://CRAN.R-project.org/package=duckdb" 227 | }, 228 | { 229 | "@type": "SoftwareApplication", 230 | "identifier": "rappdirs", 231 | "name": "rappdirs", 232 | "provider": { 233 | "@id": "https://cran.r-project.org", 234 | "@type": "Organization", 235 | "name": "Comprehensive R Archive Network (CRAN)", 236 | "url": "https://cran.r-project.org" 237 | }, 238 | "sameAs": "https://CRAN.R-project.org/package=rappdirs" 239 | }, 240 | { 241 | "@type": "SoftwareApplication", 242 | "identifier": "DBI", 243 | "name": "DBI", 244 | "provider": { 245 | "@id": "https://cran.r-project.org", 246 | "@type": "Organization", 247 | "name": "Comprehensive R Archive Network (CRAN)", 248 | "url": "https://cran.r-project.org" 249 | }, 250 | "sameAs": "https://CRAN.R-project.org/package=DBI" 251 | }, 252 | { 253 | "@type": "SoftwareApplication", 254 | "identifier": "httr", 255 | "name": "httr", 256 | "provider": { 257 | "@id": "https://cran.r-project.org", 258 | "@type": "Organization", 259 | "name": "Comprehensive R Archive Network (CRAN)", 260 | "url": "https://cran.r-project.org" 261 | }, 262 | "sameAs": "https://CRAN.R-project.org/package=httr" 263 | }, 264 | { 265 | "@type": "SoftwareApplication", 266 | "identifier": "R.utils", 267 | "name": "R.utils", 268 | "provider": { 269 | "@id": "https://cran.r-project.org", 270 | "@type": "Organization", 271 | "name": "Comprehensive R Archive Network (CRAN)", 272 | "url": "https://cran.r-project.org" 273 | }, 274 | "sameAs": "https://CRAN.R-project.org/package=R.utils" 275 | }, 276 | { 277 | "@type": "SoftwareApplication", 278 | "identifier": "purrr", 279 | "name": "purrr", 280 | "provider": { 281 | "@id": "https://cran.r-project.org", 282 | "@type": "Organization", 283 | "name": "Comprehensive R Archive Network (CRAN)", 284 | "url": "https://cran.r-project.org" 285 | }, 286 | "sameAs": "https://CRAN.R-project.org/package=purrr" 287 | }, 288 | { 289 | "@type": "SoftwareApplication", 290 | "identifier": "tools", 291 | "name": "tools" 292 | }, 293 | { 294 | "@type": "SoftwareApplication", 295 | "identifier": "dplyr", 296 | "name": "dplyr", 297 | "provider": { 298 | "@id": "https://cran.r-project.org", 299 | "@type": "Organization", 300 | "name": "Comprehensive R Archive Network (CRAN)", 301 | "url": "https://cran.r-project.org" 302 | }, 303 | "sameAs": "https://CRAN.R-project.org/package=dplyr" 304 | }, 305 | { 306 | "@type": "SoftwareApplication", 307 | "identifier": "dbplyr", 308 | "name": "dbplyr", 309 | "provider": { 310 | "@id": "https://cran.r-project.org", 311 | "@type": "Organization", 312 | "name": "Comprehensive R Archive Network (CRAN)", 313 | "url": "https://cran.r-project.org" 314 | }, 315 | "sameAs": "https://CRAN.R-project.org/package=dbplyr" 316 | } 317 | ], 318 | "releaseNotes": "https://github.com/ropensci/citesdb/blob/master/NEWS.md", 319 | "readme": "https://github.com/ropensci/citesdb/blob/master/README.md", 320 | "fileSize": "3443.675KB", 321 | "contIntegration": ["https://circleci.com/gh/ropensci/citesdb", "https://codecov.io/gh/ropensci/citesdb"], 322 | "developmentStatus": "https://www.repostatus.org/#active", 323 | "review": { 324 | "@type": "Review", 325 | "url": "https://github.com/ropensci/software-review/issues/292", 326 | "provider": "https://ropensci.org" 327 | }, 328 | "keywords": [ 329 | "r", 330 | "rstats", 331 | "r-package", 332 | "wildlife", 333 | "dataset" 334 | ], 335 | "citation": [ 336 | { 337 | "@type": "ScholarlyArticle", 338 | "datePublished": "2019", 339 | "author": [ 340 | { 341 | "@type": "Person", 342 | "givenName": "Noam", 343 | "familyName": "Ross" 344 | }, 345 | { 346 | "@type": "Person", 347 | "givenName": ["Evan", "A."], 348 | "familyName": "Eskew" 349 | }, 350 | { 351 | "@type": "Person", 352 | "givenName": "Nicolas", 353 | "familyName": "Ray" 354 | } 355 | ], 356 | "name": "citesdb: An R package to support analysis of CITES Trade Database shipment-level data", 357 | "identifier": "10.21105/joss.01483", 358 | "url": "https://doi.org/10.21105/joss.01483", 359 | "pagination": "1483", 360 | "@id": "https://doi.org/10.21105/joss.01483", 361 | "sameAs": "https://doi.org/10.21105/joss.01483", 362 | "isPartOf": { 363 | "@type": "PublicationIssue", 364 | "issueNumber": "37", 365 | "datePublished": "2019", 366 | "isPartOf": { 367 | "@type": ["PublicationVolume", "Periodical"], 368 | "volumeNumber": "4", 369 | "name": "Journal of Open Source Software" 370 | } 371 | } 372 | }, 373 | { 374 | "@type": "CreativeWork", 375 | "datePublished": "2019", 376 | "author": [ 377 | { 378 | "@type": "Organization", 379 | "name": "UNEP-WCMC" 380 | } 381 | ], 382 | "name": "Full CITES Trade Database Download. Version 2019.2", 383 | "url": "https://trade.cites.org" 384 | } 385 | ] 386 | } 387 | -------------------------------------------------------------------------------- /data-raw/country_code_data/cites_manual_country_code_entries.csv: -------------------------------------------------------------------------------- 1 | country,code,former_code,non_ISO_code,data_source 2 | Saint Barthélemy,BL,FALSE,FALSE,Manually curated 3 | "Bonaire, Sint Eustatius and Saba",BQ,FALSE,FALSE,Manually curated 4 | Clipperton Island,CP,FALSE,FALSE,Manually curated 5 | Curaçao,CW,FALSE,FALSE,Manually curated 6 | Kosovo,KV,FALSE,TRUE,Manually curated 7 | Saint Martin (French part),MF,FALSE,FALSE,Manually curated 8 | Neutral Zone,NT,TRUE,FALSE,Manually curated 9 | South Sudan,SS,FALSE,FALSE,Manually curated 10 | Sint Maarten (Dutch part),SX,FALSE,FALSE,Manually curated 11 | "Yemen, Democratic",YD,TRUE,FALSE,Manually curated -------------------------------------------------------------------------------- /data-raw/country_code_data/en-CITES_Trade_Database_Guide.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/data-raw/country_code_data/en-CITES_Trade_Database_Guide.pdf -------------------------------------------------------------------------------- /data-raw/process_tables.R: -------------------------------------------------------------------------------- 1 | 2 | 3 | library(tidyverse) 4 | library(tabulizer) 5 | 6 | h <- here::here 7 | 8 | #============================================================================== 9 | 10 | 11 | # Prepare cites_metadata table 12 | 13 | cites_metadata <- h("data-raw", "cites_metadata.tsv") %>% 14 | read_tsv() 15 | 16 | write_tsv(cites_metadata, h("inst", "extdata", "cites_metadata.tsv")) 17 | 18 | #============================================================================== 19 | 20 | 21 | # Prepare cites_codes table 22 | 23 | cites_codes <- h("data-raw", "cites_codes.tsv") %>% 24 | read_tsv() %>% 25 | arrange(field, code) %>% 26 | filter(field != "Term", field != "Unit") 27 | 28 | # Note, currently leaving out "Term" and "Unit" since these variables appear 29 | # as full descriptions (not codes) in the citesdb data 30 | 31 | write_tsv(cites_codes, h("inst", "extdata", "cites_codes.tsv")) 32 | 33 | #============================================================================== 34 | 35 | 36 | # Prepare cites_parties table 37 | 38 | cites_parties <- h("data-raw", "cites_parties.tsv") %>% 39 | read_tsv() %>% 40 | mutate(code = ifelse(country == "Namibia", "NA", code)) %>% 41 | separate(., code, into = c("code1", "code2"), 42 | sep = ", formerly| ex-", fill = "right") %>% 43 | mutate(code1 = str_replace_all(code1, " ", ""), 44 | code2 = str_replace_all(code2, " ", "")) %>% 45 | gather(., key = code_version, value = code, -country, -date) %>% 46 | filter(!is.na(code)) %>% 47 | mutate(code_version = ifelse(code_version == "code2", TRUE, FALSE)) %>% 48 | rename(former_code = code_version) %>% 49 | select(country, code, former_code, date) %>% 50 | mutate(data_source = "'A guide to using the CITES Trade Database', Version 8, Annex 4") %>% 51 | filter(!(country == "Slovakia" & former_code == TRUE), 52 | !(country == "Czech Republic" & former_code == TRUE)) 53 | 54 | countries_raw <- h("data-raw", "country_code_data", "en-CITES_Trade_Database_Guide.pdf") %>% 55 | extract_areas(., pages = c(14, 15, 16)) 56 | 57 | countries_raw2 <- do.call(rbind, countries_raw) 58 | 59 | countries <- 60 | tibble(code = c(countries_raw2[, c(1, 3)]), 61 | country = c(countries_raw2[, c(2, 4)])) %>% 62 | filter(country != "" | code != "", 63 | country != "ISLANDS", 64 | country != "AND NORTHERN IRELAND") %>% 65 | mutate(country = tolower(country), 66 | country = stringi::stri_trans_totitle(country)) %>% 67 | tidyr::separate(., col = code, into = c("code", "non_ISO_code"), 68 | sep = "1", fill = "right") %>% 69 | mutate(non_ISO_code = ifelse(is.na(non_ISO_code), FALSE, TRUE), 70 | country = str_replace_all(country, "And", "and"), 71 | country = str_replace_all(country, "Of", "of"), 72 | country = str_replace_all(country, "The", "the")) %>% 73 | mutate(country = case_when( 74 | country == "andorra" ~ "Andorra", 75 | country == "Bolivia (Plurinational State of)" ~ "Bolivia, Plurinational State of", 76 | country == "Congo, Democratic Republic of the" ~ "Democratic Republic of the Congo", 77 | country == "Côte D'ivoire" ~ "Côte d'Ivoire", 78 | country == "Tanzania, United Republic of" ~ "United Republic of Tanzania", 79 | country == "Saint Vincent and the Grenadines" ~ "Saint Vincent and the Grenadines", 80 | country == "South Georgia and the South Sandwich" ~ "South Georgia and the South Sandwich Islands", 81 | country == "United Kingdom of Great Britain" ~ "United Kingdom of Great Britain and Northern Ireland", 82 | country == "Virgin Islands (U.s.)" ~ "Virgin Islands (U.S.)", 83 | TRUE ~ country 84 | )) %>% 85 | mutate(former_code = FALSE) 86 | 87 | joined_parties <- full_join(cites_parties, countries, 88 | by = c("code", "country", "former_code")) %>% 89 | mutate(data_source = 90 | ifelse(is.na(data_source), 91 | "'A guide to using the CITES Trade Database', Version 8, Annex 3", data_source), 92 | non_ISO_code = ifelse(is.na(non_ISO_code), FALSE, non_ISO_code) 93 | ) %>% 94 | select(country, code, former_code, non_ISO_code, date, data_source) %>% 95 | # Deal with CS and YU code issues 96 | filter(!(country == "Former Serbia and Montenegro"), 97 | !(country == "Serbia and Montenegro" & former_code == TRUE)) 98 | 99 | manual_countries <- h("data-raw", "country_code_data", "cites_manual_country_code_entries.csv") %>% 100 | read_csv() 101 | 102 | final_parties <- bind_rows(joined_parties, manual_countries) %>% 103 | arrange(country, desc(former_code)) 104 | 105 | write_tsv(final_parties, h("inst", "extdata", "cites_parties.tsv")) 106 | -------------------------------------------------------------------------------- /data-raw/process_trade_db.R: -------------------------------------------------------------------------------- 1 | 2 | 3 | library(httr) 4 | library(here) 5 | library(readr) 6 | library(fs) 7 | library(purrr) 8 | library(dplyr) 9 | 10 | GET( 11 | "https://trade.cites.org/cites_trade/download_db", 12 | write_disk(here("data-raw", "Trade_database.zip"), overwrite = TRUE) 13 | ) 14 | 15 | unzip(here("data-raw", "Trade_database.zip"), 16 | overwrite = TRUE, 17 | exdir = here("data-raw"), 18 | ) 19 | 20 | tdb <- map_dfr( 21 | list.files(here("data-raw"), pattern = "^trade_db_\\d+\\.csv$", full.names = TRUE), 22 | ~ read_csv(., 23 | col_types = cols( 24 | Id = col_character(), 25 | Year = col_integer(), 26 | Appendix = col_character(), 27 | Taxon = col_character(), 28 | Class = col_character(), 29 | Order = col_character(), 30 | Family = col_character(), 31 | Genus = col_character(), 32 | Term = col_character(), 33 | Quantity = col_double(), 34 | Unit = col_character(), 35 | Importer = col_character(), 36 | Exporter = col_character(), 37 | Origin = col_character(), 38 | Purpose = col_character(), 39 | Source = col_character(), 40 | Reporter.type = col_character(), 41 | Import.permit.RandomID = col_character(), 42 | Export.permit.RandomID = col_character(), 43 | Origin.permit.RandomID = col_character() 44 | ) 45 | ) 46 | ) 47 | 48 | # Removing invalid records to be fixed if possible in the future 49 | tdb <- tdb %>% 50 | filter(!is.na(Year) & Year > 1970 & Year < 2021) 51 | 52 | # Arrange values; improves compressibility 53 | tdb <- tdb %>% 54 | arrange(Year, Taxon, Order, Family, Genus, Term, Importer, Exporter, Appendix) 55 | 56 | # Write compressed data 57 | write_tsv( 58 | tdb, 59 | here("data-raw", "cites_trade_db.tsv.bz2") 60 | ) 61 | 62 | # Clean up 63 | file_delete( 64 | list.files(here("data-raw"), pattern = "(zip|csv|docx)$", full.names = TRUE) 65 | ) 66 | 67 | # Release the compressed data 68 | datastorr::github_release_info( 69 | "ropensci/citesdb", 70 | read = read_tsv, 71 | filename = "cites_trade_db.tsv.bz2" 72 | ) %>% 73 | datastorr::github_release_create( 74 | description = "Release of CITES shipment data (v2020.1)", 75 | target = "master", ignore_dirty = TRUE 76 | ) 77 | -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | citHeader("If you use citesdb in a publication, please cite both the package and source data:") 2 | 3 | citEntry(entry = "article", 4 | doi = "10.21105/joss.01483", 5 | url = "https://doi.org/10.21105/joss.01483", 6 | year = "2019", 7 | month = "May", 8 | publisher = "The Open Journal", 9 | volume = 4, 10 | number = 37, 11 | pages = 1483, 12 | author = personList(as.person("Noam Ross"), as.person("Evan A. Eskew"), as.person("Nicolas Ray")), 13 | title = "citesdb: An R package to support analysis of CITES Trade Database shipment-level data", 14 | journal = "Journal of Open Source Software", 15 | textVersion = "Ross, Noam, Evan A. Eskew, and Nicolas Ray. 2019. citesdb: An R package to support analysis of CITES Trade Database shipment-level data. Journal of Open Source Software, 4(37), 1483, https://doi.org/10.21105/joss.01483") 16 | 17 | citEntry(entry = "misc", 18 | author = "UNEP-WCMC (Comps.)", 19 | title = "Full CITES Trade Database Download. Version 2020.1", 20 | year = "2020", 21 | institution = "CITES Secretariat", 22 | address = "Geneva, Switzerland", 23 | url = "https://trade.cites.org", 24 | textVersion = "UNEP-WCMC (Comps.) 2019. Full CITES Trade Database Download. Version 2019.2. CITES Secretariat, Geneva, Switzerland. Compiled by UNEP-WCMC, Cambridge, UK. Available at: https://trade.cites.org.") 25 | -------------------------------------------------------------------------------- /inst/WORDLIST: -------------------------------------------------------------------------------- 1 | browsable 2 | carcharias 3 | Carcharodon 4 | Centre 5 | CircleCI 6 | codecov 7 | cryptographic 8 | cryptographically 9 | csv 10 | doi 11 | DOI 12 | dplyr 13 | DuckDB 14 | EcoHealth 15 | ecohealthalliance 16 | FIPF 17 | github 18 | https 19 | identifier’ 20 | Lamniformes 21 | NIST 22 | pre 23 | rcites 24 | README 25 | recognise 26 | RStudio 27 | SHA 28 | Speciesplus 29 | th 30 | tibble 31 | TSV 32 | UNEP 33 | uplisting 34 | WCMC 35 | WIP 36 | zenodo 37 | -------------------------------------------------------------------------------- /inst/extdata/cites_codes.tsv: -------------------------------------------------------------------------------- 1 | field code description 2 | Purpose B Breeding in captivity or artificial propagation 3 | Purpose E Educational 4 | Purpose G Botanical garden 5 | Purpose H Hunting trophy 6 | Purpose L Law enforcement / judicial / forensic 7 | Purpose M Medical (including biomedical research) 8 | Purpose N Reintroduction or introduction into the wild 9 | Purpose P Personal 10 | Purpose Q Circus or travelling exhibition 11 | Purpose S Scientific 12 | Purpose T Commercial 13 | Purpose Z Zoo 14 | Source A Plants that are artificially propagated in accordance with Resolution Conf. 11.11 (Rev. CoP15), as well as parts and derivatives thereof, exported under the provisions of Article VII, paragraph 5, of the Convention (specimens of species included in Appendix I that have been propagated artificially for non-commercial purposes and specimens of species included in Appendices II and III). 15 | Source C Animals bred in captivity in accordance with Resolution Conf. 10.16 (Rev.), as well as parts and derivatives thereof, exported under the provisions of Article VII, paragraph 5, of the Convention. 16 | Source D Appendix-I animals bred in captivity for commercial purposes in operations included in the Secretariat's Register, in accordance with Resolution Conf. 12.10 (Rev. CoP15), and Appendix-I plants artificially propagated for commercial purposes, as well as parts and derivatives thereof, exported under the provisions of Article VII, paragraph 4, of the Convention. 17 | Source F Animals born in captivity (F1 or subsequent generations) that do not fulfil the definition of 'bred in captivity' in Resolution Conf. 10.16 (Rev.), as well as parts and derivatives thereof. 18 | Source I Confiscated or seized specimens 19 | Source O Pre-Convention specimens 20 | Source R Ranched specimens: specimens of animals reared in a controlled environment, taken as eggs or juveniles from the wild, where they would otherwise have had a very low probability of surviving to adulthood. 21 | Source U Source unknown. 22 | Source W Specimens taken from the wild. 23 | Source X "Specimens taken in ""the marine environment not under the jurisdiction of any State""." 24 | -------------------------------------------------------------------------------- /inst/extdata/cites_metadata.tsv: -------------------------------------------------------------------------------- 1 | variable description 2 | Year year in which trade occurred 3 | Appendix CITES Appendix of taxon concerned 4 | Taxon scientific name of animal or plant concerned 5 | Class scientific name of animal or plant concerned 6 | Order scientific name of animal or plant concerned 7 | Family scientific name of animal or plant concerned 8 | Genus scientific name of animal or plant concerned 9 | Term description of specimens traded, as reported by the importing country 10 | Quantity amount of specimens 11 | Unit unit associated with the quantity reported by the importing country, e.g. 'KIL' (kilograms). If no unit is shown, the figure represents the 12 | Importer country of import (where exports are reported, this is the declared country of destination) 13 | Exporter country of export (where imports are reported, this is the declared country from which the specimens were consigned) 14 | Origin country of origin (this column is blank if the country of export is the country of origin, or if the country of origin is not reported) 15 | Purpose purpose of the transaction (see Annex 2), as reported by the importing country 16 | Source source of the specimen (see Annex 2), as reported by the importing country 17 | Reporter.type reported by importer (I) or exporter (E) 18 | Import.permit.RandomID cryptographic hash of importer permit ID 19 | Export.permit.RandomID cryptographic hash of exporter permit ID 20 | Origin.permit.RandomID cryptographic hash of origin permit ID (under re-export) 21 | -------------------------------------------------------------------------------- /inst/extdata/cites_parties.tsv: -------------------------------------------------------------------------------- 1 | country code former_code non_ISO_code date data_source 2 | Afghanistan AF FALSE FALSE 1986-01-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 3 | Africa XF FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 4 | Åland Islands AX FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 5 | Albania AL FALSE FALSE 2003-09-25 'A guide to using the CITES Trade Database', Version 8, Annex 4 6 | Algeria DZ FALSE FALSE 1984-02-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 7 | American Samoa AS FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 8 | Andorra AD FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 9 | Angola AO FALSE FALSE 2013-12-31 'A guide to using the CITES Trade Database', Version 8, Annex 4 10 | Anguilla AI FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 11 | Antarctica AQ FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 12 | Antigua and Barbuda AG FALSE FALSE 1997-10-06 'A guide to using the CITES Trade Database', Version 8, Annex 4 13 | Argentina AR FALSE FALSE 1981-04-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 14 | Armenia AM FALSE FALSE 2009-01-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 15 | Aruba AW FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 16 | Asia XS FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 17 | Australia AU FALSE FALSE 1976-10-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 18 | Austria AT FALSE FALSE 1982-04-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 19 | Azerbaijan AZ FALSE FALSE 1999-02-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 20 | Bahamas BS FALSE FALSE 1979-09-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 21 | Bahrain BH FALSE FALSE 2012-11-17 'A guide to using the CITES Trade Database', Version 8, Annex 4 22 | Bangladesh BD FALSE FALSE 1982-02-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 23 | Barbados BB FALSE FALSE 1993-03-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 24 | Belarus BY FALSE FALSE 1995-11-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 25 | Belgium BE FALSE FALSE 1984-01-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 26 | Belize BZ FALSE FALSE 1981-09-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 27 | Benin BJ FALSE FALSE 1984-05-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 28 | Bermuda BM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 29 | Bhutan BT FALSE FALSE 2002-11-13 'A guide to using the CITES Trade Database', Version 8, Annex 4 30 | Bolivia, Plurinational State of BO FALSE FALSE 1979-10-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 31 | Bonaire, Sint Eustatius and Saba BQ FALSE FALSE NA Manually curated 32 | Bosnia and Herzegovina BA FALSE FALSE 2009-04-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 33 | Botswana BW FALSE FALSE 1978-02-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 34 | Bouvet Island BV FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 35 | Brazil BR FALSE FALSE 1975-11-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 36 | British Indian Ocean Territory IO FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 37 | Brunei Darussalam BN FALSE FALSE 1990-08-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 38 | Bulgaria BG FALSE FALSE 1991-04-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 39 | Burkina Faso BF FALSE FALSE 1990-01-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 40 | Burundi BI FALSE FALSE 1988-11-06 'A guide to using the CITES Trade Database', Version 8, Annex 4 41 | Cambodia KH FALSE FALSE 1997-10-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 42 | Cameroon CM FALSE FALSE 1981-09-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 43 | Canada CA FALSE FALSE 1975-07-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 44 | Cape Verde CV FALSE FALSE 2005-11-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 45 | Caribbean XC FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 46 | Cayman Islands KY FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 47 | Central African Republic CF FALSE FALSE 1980-11-25 'A guide to using the CITES Trade Database', Version 8, Annex 4 48 | Chad TD FALSE FALSE 1989-05-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 49 | Chile CL FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 50 | China CN FALSE FALSE 1981-04-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 51 | Christmas Island CX FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 52 | Clipperton Island CP FALSE FALSE NA Manually curated 53 | Cocos (Keeling) Islands CC FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 54 | Colombia CO FALSE FALSE 1981-11-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 55 | Comoros KM FALSE FALSE 1995-02-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 56 | Congo CG FALSE FALSE 1983-05-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 57 | Cook Islands CK FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 58 | Costa Rica CR FALSE FALSE 1975-09-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 59 | Côte d'Ivoire CI FALSE FALSE 1995-02-19 'A guide to using the CITES Trade Database', Version 8, Annex 4 60 | Croatia HR FALSE FALSE 2000-06-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 61 | Cuba CU FALSE FALSE 1990-07-19 'A guide to using the CITES Trade Database', Version 8, Annex 4 62 | Curaçao CW FALSE FALSE NA Manually curated 63 | Cyprus CY FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 64 | Czech Republic CZ FALSE FALSE 1992-05-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 65 | Democratic Republic of the Congo ZR TRUE FALSE 1976-10-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 66 | Democratic Republic of the Congo CD FALSE FALSE 1976-10-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 67 | Denmark DK FALSE FALSE 1977-10-24 'A guide to using the CITES Trade Database', Version 8, Annex 4 68 | Djibouti DJ FALSE FALSE 1992-05-07 'A guide to using the CITES Trade Database', Version 8, Annex 4 69 | Dominica DM FALSE FALSE 1995-11-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 70 | Dominican Republic DO FALSE FALSE 1987-03-17 'A guide to using the CITES Trade Database', Version 8, Annex 4 71 | Ecuador EC FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 72 | Egypt EG FALSE FALSE 1978-04-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 73 | El Salvador SV FALSE FALSE 1987-07-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 74 | Equatorial Guinea GQ FALSE FALSE 1992-06-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 75 | Eritrea ER FALSE FALSE 1995-01-22 'A guide to using the CITES Trade Database', Version 8, Annex 4 76 | Estonia EE FALSE FALSE 1992-10-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 77 | Ethiopia ET FALSE FALSE 1989-07-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 78 | Europe XE FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 79 | Falkland Islands (Malvinas) FK FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 80 | Faroe Islands FO FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 81 | Fiji FJ FALSE FALSE 1997-12-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 82 | Finland FI FALSE FALSE 1976-08-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 83 | Former Czechoslovakia ZC FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 84 | Former East Germany DD FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 85 | Former Pacific Trust Territory PC FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 86 | Former Soviet Union SU FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 87 | Former Yugoslavia YU FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 88 | France FR FALSE FALSE 1978-08-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 89 | French Antilles XA FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 90 | French Guiana GF FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 91 | French Polynesia PF FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 92 | French Southern Territories TF FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 93 | Gabon GA FALSE FALSE 1989-05-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 94 | Gambia GM FALSE FALSE 1977-11-24 'A guide to using the CITES Trade Database', Version 8, Annex 4 95 | Georgia GE FALSE FALSE 1996-12-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 96 | Germany DE FALSE FALSE 1976-06-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 97 | Ghana GH FALSE FALSE 1976-02-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 98 | Gibraltar GI FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 99 | Greece GR FALSE FALSE 1993-01-06 'A guide to using the CITES Trade Database', Version 8, Annex 4 100 | Greenland GL FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 101 | Grenada GD FALSE FALSE 1999-11-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 102 | Guadeloupe GP FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 103 | Guam GU FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 104 | Guatemala GT FALSE FALSE 1980-02-05 'A guide to using the CITES Trade Database', Version 8, Annex 4 105 | Guernsey GG FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 106 | Guinea GN FALSE FALSE 1981-12-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 107 | Guinea-Bissau GW FALSE FALSE 1990-08-14 'A guide to using the CITES Trade Database', Version 8, Annex 4 108 | Guyana GY FALSE FALSE 1977-08-25 'A guide to using the CITES Trade Database', Version 8, Annex 4 109 | Haiti HT FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 110 | Heard and Mcdonald Islands HM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 111 | Holy See VA FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 112 | Honduras HN FALSE FALSE 1985-06-13 'A guide to using the CITES Trade Database', Version 8, Annex 4 113 | Hong Kong HK FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 114 | Hungary HU FALSE FALSE 1985-08-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 115 | Iceland IS FALSE FALSE 2000-04-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 116 | India IN FALSE FALSE 1976-10-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 117 | Indonesia ID FALSE FALSE 1979-03-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 118 | Introduction From the Sea ZZ FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 119 | Iran, Islamic Republic of IR FALSE FALSE 1976-11-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 120 | Iraq IQ FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 121 | Ireland IE FALSE FALSE 2002-04-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 122 | Isle of Man IM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 123 | Israel IL FALSE FALSE 1980-03-17 'A guide to using the CITES Trade Database', Version 8, Annex 4 124 | Italy IT FALSE FALSE 1979-12-31 'A guide to using the CITES Trade Database', Version 8, Annex 4 125 | Jamaica JM FALSE FALSE 1997-07-22 'A guide to using the CITES Trade Database', Version 8, Annex 4 126 | Japan JP FALSE FALSE 1980-11-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 127 | Jersey JE FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 128 | Jordan JO FALSE FALSE 1979-03-14 'A guide to using the CITES Trade Database', Version 8, Annex 4 129 | Kazakhstan KZ FALSE FALSE 2000-04-19 'A guide to using the CITES Trade Database', Version 8, Annex 4 130 | Kenya KE FALSE FALSE 1979-03-13 'A guide to using the CITES Trade Database', Version 8, Annex 4 131 | Kiribati KI FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 132 | Korea, Democratic People's Republic of KP FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 133 | Korea, Republic of KR FALSE FALSE 1993-10-07 'A guide to using the CITES Trade Database', Version 8, Annex 4 134 | Kosovo KV FALSE TRUE NA Manually curated 135 | Kuwait KW FALSE FALSE 2002-11-10 'A guide to using the CITES Trade Database', Version 8, Annex 4 136 | Kyrgyzstan KG FALSE FALSE 2007-09-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 137 | Lao People's Democratic Republic LA FALSE FALSE 2004-05-30 'A guide to using the CITES Trade Database', Version 8, Annex 4 138 | Latvia LV FALSE FALSE 1997-05-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 139 | Lebanon LB FALSE FALSE 2013-05-26 'A guide to using the CITES Trade Database', Version 8, Annex 4 140 | Lesotho LS FALSE FALSE 2003-12-30 'A guide to using the CITES Trade Database', Version 8, Annex 4 141 | Liberia LR FALSE FALSE 1981-06-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 142 | Libya LY FALSE FALSE 2003-04-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 143 | Liechtenstein LI FALSE FALSE 1980-02-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 144 | Lithuania LT FALSE FALSE 2002-03-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 145 | Luxembourg LU FALSE FALSE 1984-03-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 146 | Macau MO FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 147 | Macedonia MK FALSE FALSE 2000-10-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 148 | Madagascar MG FALSE FALSE 1975-11-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 149 | Malawi MW FALSE FALSE 1982-05-06 'A guide to using the CITES Trade Database', Version 8, Annex 4 150 | Malaysia MY FALSE FALSE 1978-01-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 151 | Maldives MV FALSE FALSE 2013-03-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 152 | Mali ML FALSE FALSE 1994-10-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 153 | Malta MT FALSE FALSE 1989-07-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 154 | Marshall Islands MH FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 155 | Martinique MQ FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 156 | Mauritania MR FALSE FALSE 1998-06-11 'A guide to using the CITES Trade Database', Version 8, Annex 4 157 | Mauritius MU FALSE FALSE 1975-07-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 158 | Mayotte YT FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 159 | Mexico MX FALSE FALSE 1991-09-30 'A guide to using the CITES Trade Database', Version 8, Annex 4 160 | Micronesia, Federated States of FM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 161 | Monaco MC FALSE FALSE 1978-07-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 162 | Mongolia MN FALSE FALSE 1996-04-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 163 | Montenegro ME FALSE FALSE 2006-06-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 164 | Montserrat MS FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 165 | Morocco MA FALSE FALSE 1976-01-14 'A guide to using the CITES Trade Database', Version 8, Annex 4 166 | Mozambique MZ FALSE FALSE 1981-06-23 'A guide to using the CITES Trade Database', Version 8, Annex 4 167 | Myanmar MM FALSE FALSE 1997-09-11 'A guide to using the CITES Trade Database', Version 8, Annex 4 168 | Namibia "NA" FALSE FALSE 1991-03-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 169 | Nauru NR FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 170 | Nepal NP FALSE FALSE 1975-09-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 171 | Netherlands NL FALSE FALSE 1984-07-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 172 | Netherlands Antilles AN FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 173 | Neutral Zone NT TRUE FALSE NA Manually curated 174 | New Caledonia NC FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 175 | New Zealand NZ FALSE FALSE 1989-08-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 176 | Nicaragua NI FALSE FALSE 1977-11-04 'A guide to using the CITES Trade Database', Version 8, Annex 4 177 | Niger NE FALSE FALSE 1975-12-07 'A guide to using the CITES Trade Database', Version 8, Annex 4 178 | Nigeria NG FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 179 | Niue NU FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 180 | Norfolk Island NF FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 181 | Northern Mariana Islands MP FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 182 | Norway NO FALSE FALSE 1976-10-25 'A guide to using the CITES Trade Database', Version 8, Annex 4 183 | Occupied Palestinian Territory PS FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 184 | Oman OM FALSE FALSE 2008-06-17 'A guide to using the CITES Trade Database', Version 8, Annex 4 185 | Pakistan PK FALSE FALSE 1976-07-19 'A guide to using the CITES Trade Database', Version 8, Annex 4 186 | Palau PW FALSE FALSE 2004-07-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 187 | Panama PA FALSE FALSE 1978-11-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 188 | Papua New Guinea PG FALSE FALSE 1976-03-11 'A guide to using the CITES Trade Database', Version 8, Annex 4 189 | Paraguay PY FALSE FALSE 1977-02-13 'A guide to using the CITES Trade Database', Version 8, Annex 4 190 | Peru PE FALSE FALSE 1975-09-25 'A guide to using the CITES Trade Database', Version 8, Annex 4 191 | Philippines PH FALSE FALSE 1981-11-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 192 | Pitcairn PN FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 193 | Poland PL FALSE FALSE 1990-03-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 194 | Portugal PT FALSE FALSE 1981-03-11 'A guide to using the CITES Trade Database', Version 8, Annex 4 195 | Puerto Rico PR FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 196 | Qatar QA FALSE FALSE 2001-08-06 'A guide to using the CITES Trade Database', Version 8, Annex 4 197 | Republic of Moldova MD FALSE FALSE 2001-06-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 198 | Réunion RE FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 199 | Romania RO FALSE FALSE 1994-11-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 200 | Russian Federation RU FALSE FALSE 1992-01-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 201 | Rwanda RW FALSE FALSE 1981-01-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 202 | Saint Barthélemy BL FALSE FALSE NA Manually curated 203 | Saint Helena and Dependencies SH FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 204 | Saint Kitts and Nevis KN FALSE FALSE 1994-05-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 205 | Saint Lucia LC FALSE FALSE 1983-03-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 206 | Saint Martin (French part) MF FALSE FALSE NA Manually curated 207 | Saint Pierre and Miquelon PM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 208 | Saint Vincent and the Grenadines VC FALSE FALSE 1989-02-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 209 | Samoa WS FALSE FALSE 2005-02-07 'A guide to using the CITES Trade Database', Version 8, Annex 4 210 | San Marino SM FALSE FALSE 2005-10-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 211 | Sao Tome and Principe ST FALSE FALSE 2001-11-07 'A guide to using the CITES Trade Database', Version 8, Annex 4 212 | Saudi Arabia SA FALSE FALSE 1996-06-10 'A guide to using the CITES Trade Database', Version 8, Annex 4 213 | Senegal SN FALSE FALSE 1977-11-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 214 | Serbia RS FALSE FALSE 2006-06-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 215 | Serbia and Montenegro CS FALSE FALSE 2002-05-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 216 | Seychelles SC FALSE FALSE 1977-05-09 'A guide to using the CITES Trade Database', Version 8, Annex 4 217 | Sierra Leone SL FALSE FALSE 1995-01-26 'A guide to using the CITES Trade Database', Version 8, Annex 4 218 | Singapore SG FALSE FALSE 1987-02-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 219 | Sint Maarten (Dutch part) SX FALSE FALSE NA Manually curated 220 | Slovakia SK FALSE FALSE 1992-05-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 221 | Slovenia SI FALSE FALSE 2000-04-23 'A guide to using the CITES Trade Database', Version 8, Annex 4 222 | Solomon Islands SB FALSE FALSE 2007-06-24 'A guide to using the CITES Trade Database', Version 8, Annex 4 223 | Somalia SO FALSE FALSE 1986-03-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 224 | South Africa ZA FALSE FALSE 1975-10-13 'A guide to using the CITES Trade Database', Version 8, Annex 4 225 | South America XM FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 226 | South Georgia and the South Sandwich Islands GS FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 227 | South Sudan SS FALSE FALSE NA Manually curated 228 | Spain ES FALSE FALSE 1986-08-28 'A guide to using the CITES Trade Database', Version 8, Annex 4 229 | Sri Lanka LK FALSE FALSE 1979-08-02 'A guide to using the CITES Trade Database', Version 8, Annex 4 230 | Sudan SD FALSE FALSE 1983-01-24 'A guide to using the CITES Trade Database', Version 8, Annex 4 231 | Suriname SR FALSE FALSE 1981-02-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 232 | Svalbard and Jan Mayen Islands SJ FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 233 | Swaziland SZ FALSE FALSE 1997-05-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 234 | Sweden SE FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 235 | Switzerland CH FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 236 | Syrian Arab Republic SY FALSE FALSE 2003-07-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 237 | Taiwan Province of China TW FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 238 | Tajikistan TJ FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 239 | Thailand TH FALSE FALSE 1983-04-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 240 | Timor-Leste TL FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 241 | Togo TG FALSE FALSE 1979-01-21 'A guide to using the CITES Trade Database', Version 8, Annex 4 242 | Tokelau TK FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 243 | Tonga TO FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 244 | Trinidad and Tobago TT FALSE FALSE 1984-04-18 'A guide to using the CITES Trade Database', Version 8, Annex 4 245 | Tunisia TN FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 246 | Turkey TR FALSE FALSE 1996-12-22 'A guide to using the CITES Trade Database', Version 8, Annex 4 247 | Turkmenistan TM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 248 | Turks and Caicos Islands TC FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 249 | Tuvalu TV FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 250 | Uganda UG FALSE FALSE 1991-10-16 'A guide to using the CITES Trade Database', Version 8, Annex 4 251 | Ukraine UA FALSE FALSE 2000-03-29 'A guide to using the CITES Trade Database', Version 8, Annex 4 252 | United Arab Emirates AE FALSE FALSE 1990-05-12 'A guide to using the CITES Trade Database', Version 8, Annex 4 253 | United Kingdom of Great Britain and Northern Ireland GB FALSE FALSE 1976-10-31 'A guide to using the CITES Trade Database', Version 8, Annex 4 254 | United Republic of Tanzania TZ FALSE FALSE 1980-02-27 'A guide to using the CITES Trade Database', Version 8, Annex 4 255 | United States Minor Outlying Islands UM FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 256 | United States of America US FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 257 | Unknown XX FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 258 | Uruguay UY FALSE FALSE 1975-07-01 'A guide to using the CITES Trade Database', Version 8, Annex 4 259 | Uzbekistan UZ FALSE FALSE 1997-10-08 'A guide to using the CITES Trade Database', Version 8, Annex 4 260 | Vanuatu VU FALSE FALSE 1989-10-15 'A guide to using the CITES Trade Database', Version 8, Annex 4 261 | Various XV FALSE TRUE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 262 | Venezuela, Bolivarian Republic of VE FALSE FALSE 1978-01-22 'A guide to using the CITES Trade Database', Version 8, Annex 4 263 | Viet Nam VN FALSE FALSE 1994-04-20 'A guide to using the CITES Trade Database', Version 8, Annex 4 264 | Virgin Islands (British) VG FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 265 | Virgin Islands (U.S.) VI FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 266 | Wallis and Futuna Islands WF FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 267 | Western Sahara EH FALSE FALSE NA 'A guide to using the CITES Trade Database', Version 8, Annex 3 268 | Yemen YE FALSE FALSE 1997-08-03 'A guide to using the CITES Trade Database', Version 8, Annex 4 269 | Yemen, Democratic YD TRUE FALSE NA Manually curated 270 | Zambia ZM FALSE FALSE 1981-02-22 'A guide to using the CITES Trade Database', Version 8, Annex 4 271 | Zimbabwe ZW FALSE FALSE 1981-08-17 'A guide to using the CITES Trade Database', Version 8, Annex 4 272 | -------------------------------------------------------------------------------- /inst/extdata/rcites1.rds: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/extdata/rcites1.rds -------------------------------------------------------------------------------- /inst/extdata/rcites2.rds: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/extdata/rcites2.rds -------------------------------------------------------------------------------- /inst/extdata/rcites3.rds: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/extdata/rcites3.rds -------------------------------------------------------------------------------- /inst/extdata/rcites4.rds: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/extdata/rcites4.rds -------------------------------------------------------------------------------- /inst/img/cites-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/img/cites-logo.png -------------------------------------------------------------------------------- /inst/img/edit-sql.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/img/edit-sql.png -------------------------------------------------------------------------------- /inst/img/eha_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/img/eha_logo.png -------------------------------------------------------------------------------- /inst/img/usaid-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/inst/img/usaid-logo.png -------------------------------------------------------------------------------- /inst/paper.bib: -------------------------------------------------------------------------------- 1 | @Misc{tradedb, 2 | author = {{UNEP-WCMC}}, 3 | title = {Full {CITES} {T}rade {D}atabase Download. Version 2019.2}, 4 | year = {2019}, 5 | institution = {CITES Secretariat}, 6 | address = {Geneva, Switzerland}, 7 | url = {https://trade.cites.org}, 8 | } 9 | 10 | @inproceedings{duckdb, 11 | title={DuckDB: an embeddable analytical database}, 12 | author={Raasveldt, Mark and M{\"u}hleisen, Hannes}, 13 | booktitle={Proceedings of the 2019 International Conference on Management of Data}, 14 | pages={1981--1984}, 15 | year={2019} 16 | } 17 | 18 | @Manual{rstudio, 19 | title = {RStudio: Integrated Development Environment for {R}}, 20 | author = {{RStudio Team}}, 21 | organization = {RStudio, Inc.}, 22 | address = {Boston, MA, USA}, 23 | year = {2015}, 24 | url = {http://www.rstudio.com/} 25 | } 26 | 27 | @Manual{dplyr, 28 | title = {{dplyr}: A Grammar of Data Manipulation}, 29 | author = {Hadley Wickham and Romain François and Lionel Henry and Kirill Müller}, 30 | year = {2019}, 31 | note = {R package version 0.8.0.1}, 32 | url = {https://CRAN.R-project.org/package=dplyr}, 33 | } 34 | 35 | @Manual{DBI, 36 | title = {DBI: R Database Interface}, 37 | author = {{R Special Interest Group on Databases (R-SIG-DB)} and Hadley Wickham and Kirill Müller}, 38 | year = {2018}, 39 | note = {R package version 1.0.0}, 40 | url = {https://CRAN.R-project.org/package=DBI}, 41 | } 42 | 43 | @article{Bennett_2002, 44 | doi = {10.1017/S0030605302000637}, 45 | url = {https://doi.org/10.1017/S0030605302000637}, 46 | year = 2002, 47 | volume = {36}, 48 | pages = {328--329}, 49 | author = {Elizabeth L. Bennett and E. J. Milner-Gulland and Mohamed Bakarr and Heather E. Eves and John G. Robinson and David S. Wilkie}, 50 | title = {Hunting the world’s wildlife to extinction}, 51 | journal = {Oryx} 52 | } 53 | 54 | @article{Lenzen_2012, 55 | doi = {10.1038/nature11145}, 56 | url = {https://doi.org/10.1038/nature11145}, 57 | year = 2012, 58 | volume = {486}, 59 | pages = {109--112}, 60 | author = {M. Lenzen and D. Moran and K. Kanemoto and B. Foran and L. Lobefaro and A. Geschke}, 61 | title = {International trade drives biodiversity threats in developing nations}, 62 | journal = {Nature} 63 | } 64 | 65 | @article{Bush_2014, 66 | doi = {10.1111/cobi.12240}, 67 | url = {https://doi.org/10.1111/cobi.12240}, 68 | year = 2014, 69 | volume = {28}, 70 | pages = {663--676}, 71 | author = {Emma R. Bush and Sandra E. Baker and David W. Macdonald}, 72 | title = {Global trade in exotic pets 2006-2012}, 73 | journal = {Conservation Biology} 74 | } 75 | 76 | @article{Harrington_2015, 77 | doi = {10.1111/cobi.12448}, 78 | url = {https://doi.org/10.1111%2Fcobi.12448}, 79 | year = 2015, 80 | volume = {29}, 81 | pages = {293--296}, 82 | author = {Lauren A. Harrington}, 83 | title = {International commercial trade in live carnivores and primates 2006-2012: response to {B}ush et {al.} 2014}, 84 | journal = {Conservation Biology} 85 | } 86 | 87 | @article{Joppa_2016, 88 | doi = {10.1126/science.aaf3565}, 89 | url = {https://doi.org/10.1126/science.aaf3565}, 90 | year = 2016, 91 | volume = {352}, 92 | pages = {416--418}, 93 | author = {L. N. Joppa and B. O'Connor and P. Visconti and C. Smith and J. Geldmann and M. Hoffmann and J. E. M. Watson and S. H. M. Butchart and M. Virah-Sawmy and B. S. Halpern and S. E. Ahmed and A. Balmford and W. J. Sutherland and Michael Harfoot and C. Hilton-Taylor and W. Foden and E. Di Minin and S. Pagad and P. Genovesi and J. Hutton and N. D. Burgess}, 94 | title = {Filling in biodiversity threat gaps}, 95 | journal = {Science} 96 | } 97 | 98 | @article{Lopes_2017, 99 | doi = {10.3897/natureconservation.21.13071}, 100 | url = {https://doi.org/10.3897/natureconservation.21.13071}, 101 | year = 2017, 102 | volume = {21}, 103 | pages = {159--161}, 104 | author = {Ricardo Jorge Lopes and Juliana Machado Ferreira and Nadia Moraes-Barros}, 105 | title = {A critical comment to {D'Cruze and Macdonald} (2016)}, 106 | journal = {Nature Conservation} 107 | } 108 | 109 | @article{Tingley_2017, 110 | doi = {10.1126/science.aan5158}, 111 | url = {https://doi.org/10.1126/science.aan5158}, 112 | year = 2017, 113 | volume = {356}, 114 | pages = {916}, 115 | author = {Morgan W. Tingley and J. Berton C. Harris and Fangyuan Hua and David S. Wilcove and Ding Li Yong}, 116 | title = {The pet trade’s role in defaunation}, 117 | journal = {Science} 118 | } 119 | 120 | @article{Berec_2018, 121 | doi = {10.1016/j.biocon.2018.05.025}, 122 | url = {https://doi.org/10.1016%2Fj.biocon.2018.05.025}, 123 | year = 2018, 124 | volume = {224}, 125 | pages = {111--116}, 126 | author = {Michal Berec and Lucie Vr{\v{s}}eck{\'{a}} and Irena {\v{S}}etl{\'{i}}kov{\'{a}}}, 127 | title = {What is the reality of wildlife trade volume? {CITES} {T}rade {D}atabase limitations}, 128 | journal = {Biological Conservation} 129 | } 130 | 131 | @article{Harfoot_2018, 132 | doi = {10.1016/j.biocon.2018.04.017}, 133 | url = {https://doi.org/10.1016/j.biocon.2018.04.017}, 134 | year = 2018, 135 | volume = {223}, 136 | pages = {47--57}, 137 | author = {Michael Harfoot and Satu A. M. Glaser and Derek P. Tittensor and Gregory L. Britten and Claire McLardy and Kelly Malsch and Neil D. Burgess}, 138 | title = {Unveiling the patterns and trends in 40 years of global trade in {CITES}-listed wildlife}, 139 | journal = {Biological Conservation} 140 | } 141 | 142 | @article{Robinson_2018, 143 | doi = {10.1111/cobi.13095}, 144 | url = {https://doi.org/10.1111%2Fcobi.13095}, 145 | year = 2018, 146 | volume = {32}, 147 | pages = {1203--1206}, 148 | author = {Janine E. Robinson and Pablo Sinovas}, 149 | title = {Challenges of analyzing the global trade in {CITES}-listed wildlife}, 150 | journal = {Conservation Biology} 151 | } 152 | 153 | @article{Eskew_2019, 154 | doi = {10.1016/j.gecco.2019.e00631}, 155 | url = {https://doi.org/10.1016/j.gecco.2019.e00631}, 156 | year = 2019, 157 | volume = {18}, 158 | pages = {e00631}, 159 | author = {Evan A. Eskew and Noam Ross and Carlos Zambrana-Torrelio and William B. Karesh}, 160 | title = {The {CITES} {T}rade {D}atabase is not a ``global snapshot'' of legal wildlife trade: response to {C}an et {al.}, 2019}, 161 | journal = {Global Ecology and Conservation} 162 | } 163 | -------------------------------------------------------------------------------- /inst/paper.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'citesdb: An R package to support analysis of CITES Trade Database shipment-level data' 3 | tags: 4 | - R 5 | - database 6 | - wildlife 7 | - trade 8 | - conservation 9 | - sustainability 10 | authors: 11 | - name: Noam Ross 12 | orcid: 0000-0002-2136-0000 13 | affiliation: 1 14 | - name: Evan A. Eskew 15 | orcid: 0000-0002-1153-5356 16 | affiliation: 1 17 | - name: Nicolas Ray 18 | affiliation: "2, 3" 19 | affiliations: 20 | - name: EcoHealth Alliance, New York, New York, USA 21 | index: 1 22 | - name: GeoHealth Group, Institute of Global Health, Faculty of Medicine, University of Geneva, Geneva, Switzerland 23 | index: 2 24 | - name: Institute for Environmental Sciences, University of Geneva, Geneva, Switzerland 25 | index: 3 26 | date: 21 May 2019 27 | bibliography: paper.bib 28 | --- 29 | 30 | # Summary 31 | 32 | International trade is a significant threat to wildlife globally [@Bennett_2002; @Lenzen_2012; @Bush_2014; @Tingley_2017]. Consequently, high-quality, widely accessible data on the wildlife trade are urgently needed to generate effective conservation strategies and action [@Joppa_2016]. The [Convention on International Trade in Endangered Species of Wild Fauna and Flora](https://www.cites.org) (CITES) provides a key wildlife trade dataset for conservationists, the CITES Trade Database, which is maintained by the [UN Environment World Conservation Monitoring Centre](https://www.unep-wcmc.org/). Broadly, CITES is a trade oversight mechanism which aims to limit the negative effects of overharvesting, and the CITES Trade Database represents compiled data from CITES Parties regarding the trade of wildlife or wildlife products listed under the CITES Appendices. Despite data complexities that can complicate interpretation [@Harrington_2015; @Lopes_2017; @Berec_2018; @Robinson_2018; @Eskew_2019], the CITES Trade Database remains a critically important resource for evaluating the extent and impact of the legal, international wildlife trade [@Harfoot_2018]. 33 | 34 | `citesdb` is an R package designed to support analysis of the recently released shipment-level CITES Trade Database [@tradedb]. Currently, the database contains over 40 years and 20 million records of shipments of wildlife and wildlife products subject to reporting under CITES, including individual shipment permit IDs that have been anonymized by hashing, and accompanying metadata. @Harfoot_2018 provide a recent overview of broad temporal and spatial trends in this data. To facilitate further analysis of this large dataset, the `citesdb` package imports the CITES Trade Database into a local, on-disk embedded database [@duckdb]. This avoids the need for users to pre-process the data or load the multi-gigabyte dataset into memory. The DuckDB back-end allows high-performance querying and is accessible via a `DBI`- and `dplyr`-compatible interface familiar to most R users [@DBI; @dplyr]. For users of the RStudio integrated development environment [@rstudio], the package also provides an interactive pane for exploring the database and previewing data. `citesdb` has undergone [code review at rOpenSci](https://github.com/ropensci/software-review/issues/292). 35 | 36 | # Acknowledgements 37 | 38 | Authors N. Ross and E. A. Eskew were funded by the generous support of the American people through the United States Agency for International Development (USAID) Emerging Pandemic Threats PREDICT project. 39 | 40 | # References 41 | -------------------------------------------------------------------------------- /inst/response_to_reviewers.md: -------------------------------------------------------------------------------- 1 | # Response to reviewers 2 | 3 | Thanks to both reviewers for their comments and issues that have 4 | helped us to make a more user-friendly package. 5 | 6 | ## Changes implemented 7 | 8 | - We have changed the installation method in the `README` to use **devtools**. 9 | 10 | - We have added information to the `cites_status` table indicating the location 11 | of the database files on disk. 12 | 13 | - We now clear out and disconnect the database tables after updating, which 14 | should trigger disk cleanup and avoid doubling database size. 15 | 16 | - Thanks for the reviewers for sticking with us through a long and merry chase 17 | of a bug that was preventing package-building in 18 | https://github.com/ecohealthalliance/citesdb/issues/1, which had its origins 19 | in a missing token for use with the **rcites** package as well as a low-level 20 | database lock issue. We now cache this the **rcites** information to avoid 21 | having to make remote calls in vignette-building, and also have resolved the 22 | DB locking conflict. 23 | 24 | - We have modified our linter tests to avoid the false positives shown in 25 | https://github.com/ecohealthalliance/citesdb/issues/2. 26 | 27 | - We have renamed the internal function `check_status()` to `cites_check_status()` 28 | to be less generic. 29 | 30 | - We have made more elaborate help and examples for the `cites_db()`, 31 | `cites_shipments()`, and metadata functions to illustrate their use and 32 | distinguish between **dplyr**- and **DBI**-based workflows. 33 | 34 | ## Changes not implemented / justifications 35 | 36 | - We have opted not to use the **glue** package and instead stick with the base 37 | R `paste()` functions in the interest of limiting dependencies. We believe 38 | this is a minor trade-off. 39 | 40 | - The low test coverage shown in https://github.com/ecohealthalliance/citesdb/issues/4 41 | is due to tests skipped on CRAN. Setting the environment variable to 42 | `NOT_CRAN=true` shows that our test coverage is 65%. This is lower than 43 | typical, but as we note in the issue above, this is largely due to the 44 | verbose code for interacting with the RStudio connection pane, which cannot be 45 | tested except in an interactive session. Other code coverage is 46 | [greater than 90%](https://codecov.io/gh/ecohealthalliance/citesdb/tree/master/R). 47 | We believe that all core functionality is tested, including important 48 | edge-cases and conditions not reflected in the coverage statistic, such as 49 | error handling in multiple sessions and changing up upstream data sources. 50 | 51 | A final note: we have learned from the maintainers of **MonetDBLite** that it will 52 | not be returning to CRAN (its current iteration fails on R-devel), but they are 53 | working on a successor embedded database package that will replace it and go 54 | to CRAN later this year. So, for now, we will host this package on GitHub and 55 | replace the database back-end and send to CRAN when the successor package is ready. 56 | We've added a note to the README showing that users need package build tools for 57 | the current version. 58 | -------------------------------------------------------------------------------- /inst/ro_blog_post.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: "citesdb" 3 | title: " 4 | package_version: 0.1.0 5 | authors: 6 | - Noam Ross 7 | - Evan A. Eskew 8 | date: 2019-06-01 9 | categories: blog 10 | topicid: 11 | tags: 12 | - Software Peer Review 13 | - R 14 | - community 15 | - software 16 | - packages 17 | - citesdb 18 | - wildlife 19 | - databases 20 | --- 21 | 22 | # topics 23 | 24 | At EHA, we work with wildlife trade data to help understand risks to wildlife 25 | and their potential as vectors for infectious disease. Critical in controlling, 26 | monitoring, and understanding this trade is the Convention on Trade in 27 | Endangered Species, a treaty and organization that regulates and monitors the 28 | international wildlife trade. 29 | 30 | Recently, CITES, together with WCMC, began publishing their data at a new level 31 | of detail - individual shipment-level records of trade going back 40 years. 32 | 33 | 34 | Importance of context and metadata for analyzing data. 35 | 36 | I've been an editor for rOpenSci for five years, but this is the first time I 37 | put a package of my own through the process! 38 | 39 | citesdb was also an an opportunity to put into practice some [ideas 40 | for data package design](https://www.youtube.com/watch?v=zsEsh5QpN0U). 41 | The CITES trade database falls into a common category of "biggish" data - larger 42 | than RAM for many users, but still small enough to analyze on a single machine. 43 | 44 | Thanks to reviewers and editors. 45 | -------------------------------------------------------------------------------- /man/cites_db.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/connect.R 3 | \name{cites_db} 4 | \alias{cites_db} 5 | \title{The local CITES database} 6 | \usage{ 7 | cites_db(dbdir = cites_path()) 8 | } 9 | \arguments{ 10 | \item{dbdir}{The location of the database on disk. Defaults to 11 | \code{citesdb} under \code{\link[rappdirs:user_data_dir]{rappdirs::user_data_dir()}}, or the environment variable \code{CITES_DB_DIR}.} 12 | } 13 | \value{ 14 | A DuckDB DBI connection 15 | } 16 | \description{ 17 | Returns a connection to the local CITES database. This is a DBI-compliant 18 | \code{\link[duckdb:duckdb]{duckdb::duckdb()}} database connection. When using \strong{dplyr}-based 19 | workflows, one typically accesses tables with functions such as 20 | \code{\link[=cites_shipments]{cites_shipments()}}, but this function lets one interact with the database 21 | directly via SQL. 22 | } 23 | \examples{ 24 | if (cites_status()) { 25 | library(DBI) 26 | 27 | dbListTables(cites_db()) 28 | 29 | parties <- dbReadTable(cites_db(), "cites_parties") 30 | 31 | dbGetQuery( 32 | cites_db(), 33 | 'SELECT "Taxon", "Importer" FROM cites_shipments WHERE "Year" = 1976 LIMIT 100;' 34 | ) 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /man/cites_db_delete.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/onattach.R 3 | \name{cites_db_delete} 4 | \alias{cites_db_delete} 5 | \title{Remove the local CITES database} 6 | \usage{ 7 | cites_db_delete() 8 | } 9 | \description{ 10 | Deletes all tables from the local database 11 | } 12 | \examples{ 13 | \donttest{ 14 | \dontrun{ 15 | cites_db_delete() 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /man/cites_db_download.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/download.R 3 | \name{cites_db_download} 4 | \alias{cites_db_download} 5 | \title{Download the CITES database to your local computer} 6 | \usage{ 7 | cites_db_download( 8 | tag = NULL, 9 | destdir = tempdir(), 10 | cleanup = TRUE, 11 | verbose = interactive() 12 | ) 13 | } 14 | \arguments{ 15 | \item{tag}{What release tag of data to download. Defaults to the most recent. 16 | Releases are expected to come twice per year. See all releases at 17 | \url{https://github.com/ropensci/citesdb/releases}.} 18 | 19 | \item{destdir}{Where to download the compressed file.} 20 | 21 | \item{cleanup}{Whether to delete the compressed file after loading into the database.} 22 | 23 | \item{verbose}{Whether to display messages and download progress} 24 | } 25 | \description{ 26 | This command downloads the CITES shipments database and populates a local 27 | database. The download is large (~158 MB), and the database will be ~5 GB 28 | on disk. During import 10 GB of disk space may be used temporarily. 29 | } 30 | \details{ 31 | The database is stored by default under \code{\link[rappdirs:user_data_dir]{rappdirs::user_data_dir()}}, or its 32 | location can be set with the environment variable \code{CITES_DB_DIR}. 33 | } 34 | \examples{ 35 | \donttest{ 36 | \dontrun{ 37 | cites_db_download() 38 | } 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /man/cites_disconnect.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/connect.R 3 | \name{cites_disconnect} 4 | \alias{cites_disconnect} 5 | \title{Disconnect from the CITES database} 6 | \usage{ 7 | cites_disconnect() 8 | } 9 | \description{ 10 | A utility function for disconnecting from the database. 11 | } 12 | \examples{ 13 | cites_disconnect() 14 | } 15 | -------------------------------------------------------------------------------- /man/cites_metadata.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/connect.R 3 | \name{cites_metadata} 4 | \alias{cites_metadata} 5 | \alias{metadata} 6 | \alias{cites_codes} 7 | \alias{cites_parties} 8 | \title{CITES shipment metadata} 9 | \usage{ 10 | cites_metadata() 11 | 12 | cites_codes() 13 | 14 | cites_parties() 15 | } 16 | \value{ 17 | A tibble of metadata 18 | } 19 | \description{ 20 | The CITES database also includes tables of column-level metadata and 21 | meanings of codes in columns, as well as a listing of CITES Parties/country abbreviations. 22 | Convenience functions access these tables. As they are small, the functions 23 | collect the tables into R session memory, rather than returning a remote table. 24 | 25 | This information is drawn from 26 | \href{https://trade.cites.org/cites_trade_guidelines/en-CITES_Trade_Database_Guide.pdf}{"A guide to using the CITES Trade Database"}, 27 | from the CITES website. More information on the shipment-level data can be 28 | found in the \link{guidance} help file. 29 | } 30 | \examples{ 31 | if (cites_status()) { 32 | library(dplyr) 33 | 34 | # See the field definitions for cites_shipments() 35 | cites_metadata() 36 | 37 | # See the codes used for shipment purpose 38 | cites_codes() \%>\% 39 | filter(field == "Purpose") 40 | 41 | # See the most recent countries to join CITES 42 | cites_parties() \%>\% 43 | arrange(desc(date)) \%>\% 44 | head(10) 45 | 46 | # See countries or locations with non-standaard or outdated ISO codes 47 | cites_parties() \%>\% 48 | filter(former_code | non_ISO_code) 49 | 50 | # For remote connections to these tables, access the database directly: 51 | dplyr::tbl(cites_db(), "cites_metadata") 52 | dplyr::tbl(cites_db(), "cites_codes") 53 | dplyr::tbl(cites_db(), "cites_parties") 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /man/cites_pane.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/connection-pane.R 3 | \name{cites_pane} 4 | \alias{cites_pane} 5 | \title{Open CITES database connection pane in RStudio} 6 | \usage{ 7 | cites_pane() 8 | } 9 | \description{ 10 | This function launches the RStudio "Connection" pane to interactively 11 | explore the database. 12 | } 13 | \examples{ 14 | if (!is.null(getOption("connectionObserver"))) cites_pane() 15 | } 16 | -------------------------------------------------------------------------------- /man/cites_shipments.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/connect.R 3 | \name{cites_shipments} 4 | \alias{cites_shipments} 5 | \title{CITES shipment data} 6 | \usage{ 7 | cites_shipments() 8 | } 9 | \value{ 10 | A \strong{dplyr} remote tibble (\code{\link[dplyr:tbl]{dplyr::tbl()}}) 11 | } 12 | \description{ 13 | Returns a remote database table with all CITES shipment data. This is the 14 | bulk of the data in the package and constitutes > 20 million records. Loading 15 | the whole table into R via the \code{\link[dplyr:compute]{dplyr::collect()}} command will use over 16 | 3 GB of RAM, so you may want to pre-process data in the database, as in 17 | the examples below. 18 | } 19 | \examples{ 20 | if (cites_status()) { 21 | library(dplyr) 22 | 23 | # See the number of CITES shipment records per year 24 | cites_shipments() \%>\% 25 | group_by(Year) \%>\% 26 | summarize(n_records = n()) \%>\% 27 | arrange(desc(Year)) \%>\% 28 | collect() 29 | 30 | # See what pangolin shipments went to which countries in 1990 31 | cites_shipments() \%>\% 32 | filter(Order == "Pholidota", Year == 1990) \%>\% 33 | count(Year, Importer, Term) \%>\% 34 | collect() \%>\% 35 | left_join(select(cites_parties(), country, code), 36 | by = c("Importer" = "code")) 37 | 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /man/cites_status.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/onattach.R 3 | \name{cites_status} 4 | \alias{cites_status} 5 | \title{Get the status of the current local CITES database} 6 | \usage{ 7 | cites_status(verbose = TRUE) 8 | } 9 | \arguments{ 10 | \item{verbose}{Whether to print a status message} 11 | } 12 | \value{ 13 | TRUE if the database exists, FALSE if it is not detected. (invisible) 14 | } 15 | \description{ 16 | Get the status of the current local CITES database 17 | } 18 | \examples{ 19 | cites_status() 20 | } 21 | -------------------------------------------------------------------------------- /man/citesdb-package.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/citesdb-package.R 3 | \docType{package} 4 | \name{citesdb-package} 5 | \alias{citesdb} 6 | \alias{citesdb-package} 7 | \title{The CITES database package} 8 | \description{ 9 | \strong{citesdb} provides over 40 years of wildlife trade data from the \href{https://www.cites.org}{Convention on International Trade in Endangered Species of Wild Fauna and Flora}. 10 | These data on imports and exports of CITES annex species are provided by 11 | CITES member countries to the CITES secretariat. 12 | } 13 | \details{ 14 | This package allows you to download the full database of historic transactions 15 | (commonly called the \href{https://trade.cites.org/}{CITES Trade Database}) 16 | to analyze locally on your computer. Because of the large size of this data, 17 | the \strong{citesdb} package stores it as an on-disk \href{https://duckdb.org/}{DuckDB} 18 | that can be queried without loading into RAM. 19 | } 20 | \seealso{ 21 | Useful links: 22 | \itemize{ 23 | \item \url{https://docs.ropensci.org/citesdb} 24 | \item \url{https://github.com/ropensci/citesdb} 25 | \item \url{https://www.cites.org/} 26 | \item Report bugs at \url{https://github.com/ropensci/citesdb/issues} 27 | } 28 | 29 | } 30 | \author{ 31 | Noam Ross and Evan A. Eskew, \href{https://www.ecohealthalliance.org/}{EcoHealth Alliance} 32 | } 33 | \keyword{internal} 34 | -------------------------------------------------------------------------------- /man/figures/README-unnamed-chunk-5-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/man/figures/README-unnamed-chunk-5-1.png -------------------------------------------------------------------------------- /man/guidance.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/cites-guidance.R 3 | \name{guidance} 4 | \alias{guidance} 5 | \alias{si} 6 | \alias{supplementary} 7 | \title{CITES Trade Database shipment-level guidance} 8 | \description{ 9 | \emph{This text copied from the supplementary information file 10 | accompanying the full database download from \url{https://trade.cites.org/}} 11 | } 12 | \section{Recommended citation}{ 13 | 14 | 15 | UNEP-WCMC (Comps.) 2019. Full CITES Trade Database Download. Version 16 | 2019.2. CITES Secretariat, Geneva, Switzerland. Compiled by UNEP-WCMC, 17 | Cambridge, UK. Available at: trade.cites.org. 18 | } 19 | 20 | \section{Background}{ 21 | 22 | 23 | Under Article VIII of the Convention, Parties are required to provide 24 | information regarding their trade in CITES-listed specimens through their 25 | annual reports, and the Secretariat makes this information available 26 | through the CITES Trade Database (trade.cites.org). This database currently 27 | contains over 20 million records of international trade in CITES-listed 28 | species. Parties recognise the importance of these reports as a tool for 29 | monitoring the implementation of the Convention, assessing the 30 | effectiveness of their wildlife management and trade policies, and to 31 | enhance the detection of potentially harmful or illicit trade. 32 | 33 | At the 70th meeting of the Standing Committee, Parties agreed that a full 34 | non-aggregated version of the CITES Trade Database should be made available 35 | and updated twice a year. These files represent the periodic release of the 36 | CITES trade data in a shipment-by-shipment format with unique identifiers 37 | replacing confidential permit numbers (see \href{https://cites.org/sites/default/files/eng/com/sc/70/E-SC70-26-02.pdf}{SC70 Doc 26.2} and \href{https://cites.org/sites/default/files/eng/com/sc/70/Inf/E-SC70-Inf-01.pdf}{SC70 Inf. 1} 38 | for further background). 39 | } 40 | 41 | \section{Overview of data}{ 42 | 43 | 44 | This zip file contains all trade records (including all historic data) 45 | entered in the CITES Trade Database by 29 January 2019 and extracted at the 46 | shipment level on 30 January 2019. This file is 2019.v2 and replaces 47 | version 2019.v1 which contained some formatting anomalies and strengthens 48 | security. 49 | 50 | While the data provided through the search function on the \href{https://trade.cites.org/}{Web Portal of the CITES Trade Database} are aggregated, the 51 | database contains non-aggregated data. The data provided in this download 52 | is on a per-shipment basis i.e. it provides the relevant information about 53 | each line item in box 7 to 12 of the \href{https://www.cites.org/sites/default/files/document/E-Res-12-03-R17.pdf}{CITES permit} 54 | (Annex 1, in line with Notification No. 2017/006) in a separate row. Each 55 | csv data file contains 500 thousand rows of data, and files are numbered 56 | chronologically with the earliest trade records in the files with the lower 57 | numbers. 58 | 59 | Given their confidential nature, import, export and re-export CITES permit 60 | numbers have been replaced with unique identifiers. This ensures that no 61 | confidential data are made available, whilst still enabling users of the 62 | data to identify instances where the same permit number may have been used 63 | for multiple shipments. The method for generating these unique identifiers 64 | is detailed below. 65 | 66 | Subsequent additions to the database will be extracted twice a year and 67 | added as new csv files, which will be detailed with each new release. 68 | } 69 | 70 | \section{Replacement of the permit number by a unique identifier}{ 71 | 72 | 73 | The permit numbers in the download have been replaced with a unique 74 | identification number (‘identifier’). This identifier is a ten character 75 | alpha/numeric string which is built from a cryptographically secure 76 | pseudo-random alpha-numeric string (which is independent of the permit 77 | number), which is then hashed via secure, non-reversible cryptographic hash 78 | function (Secure Hash Algorithm 2, SHA-512 which uses 64-bit words to 79 | construct the hash. SHA-512 is specified in \href{http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf}{document FIPF PUB 180-4, National Institute of Technology (NIST)}). This 80 | process preserves the relationship between exports and re-exports if the 81 | Parties have reported corresponding export and re-export permit numbers. 82 | Permit numbers always retain the same unique identifier in each release. 83 | The same unique identifier is assigned irrespective of whether the permit 84 | number is reported as an import, export or re-export permit. 85 | } 86 | 87 | -------------------------------------------------------------------------------- /pkgdown/_pkgdown.yml: -------------------------------------------------------------------------------- 1 | destination: docs 2 | bootswatch: flatly 3 | 4 | navbar: 5 | title: citesdb 6 | type: inverse 7 | 8 | authors: 9 | Noam Ross: 10 | href: "https://www.ecohealthalliance.org/personnel/dr-noam-ross" 11 | Evan A. Eskew: 12 | href: "https://www.ecohealthalliance.org/personnel/evan-eskew" 13 | USAID PREDICT: 14 | href: "https://www.ecohealthalliance.org" 15 | html: "USAID PREDICT" 16 | EcoHealth Alliance: 17 | href: "https://www.ecohealthalliance.org" 18 | html: "EcoHealth Alliance EcoHealth Alliance" 19 | -------------------------------------------------------------------------------- /pkgdown/favicon/apple-touch-icon-60x60.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/pkgdown/favicon/apple-touch-icon-60x60.png -------------------------------------------------------------------------------- /pkgdown/favicon/apple-touch-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/pkgdown/favicon/apple-touch-icon.png -------------------------------------------------------------------------------- /pkgdown/favicon/favicon-16x16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/pkgdown/favicon/favicon-16x16.png -------------------------------------------------------------------------------- /pkgdown/favicon/favicon-32x32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/pkgdown/favicon/favicon-32x32.png -------------------------------------------------------------------------------- /pkgdown/favicon/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/pkgdown/favicon/favicon.ico -------------------------------------------------------------------------------- /tests/spelling.R: -------------------------------------------------------------------------------- 1 | if (requireNamespace("spelling", quietly = TRUE)) { 2 | spelling::spell_check_test( 3 | vignettes = TRUE, error = FALSE, 4 | skip_on_cran = TRUE 5 | ) 6 | } 7 | -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | library(testthat) 2 | library(citesdb) 3 | 4 | test_check("citesdb") 5 | -------------------------------------------------------------------------------- /tests/testthat/test-01-download.R: -------------------------------------------------------------------------------- 1 | context("Download") 2 | 3 | olddir <- Sys.getenv("CITES_DB_DIR") 4 | Sys.setenv(CITES_DB_DIR = normalizePath(file.path(getwd(), "localdb"), 5 | mustWork = FALSE 6 | )) 7 | 8 | test_that("Download succeeds", { 9 | skip_on_cran() 10 | cites_db_download() 11 | expect_true(cites_status()) 12 | }) 13 | 14 | Sys.setenv(CITES_DB_DIR = olddir) 15 | -------------------------------------------------------------------------------- /tests/testthat/test-02-tables.R: -------------------------------------------------------------------------------- 1 | olddir <- Sys.getenv("CITES_DB_DIR") 2 | Sys.setenv(CITES_DB_DIR = normalizePath(file.path(getwd(), "localdb"), 3 | mustWork = FALSE 4 | )) 5 | 6 | context("Tables") 7 | 8 | test_that("Tables have expected types", { 9 | skip_on_cran() 10 | skip_if_not(cites_status()) 11 | expect_is(cites_shipments(), "tbl_duckdb_connection") 12 | expect_is(cites_metadata(), "data.frame") 13 | expect_is(cites_codes(), "data.frame") 14 | expect_is(cites_parties(), "data.frame") 15 | }) 16 | 17 | test_that("All codes are accounted for", { 18 | skip_on_cran() 19 | skip_if_not(cites_status()) 20 | suppressWarnings(suppressPackageStartupMessages(library(dplyr))) 21 | 22 | sources <- cites_shipments() %>% 23 | count(Source) %>% 24 | pull(Source) %>% 25 | na.omit() 26 | source_codes <- cites_codes() %>% 27 | filter(field == "Source") %>% 28 | pull(code) 29 | expect_setequal(sources, source_codes) 30 | 31 | purposes <- cites_shipments() %>% 32 | count(Purpose) %>% 33 | pull(Purpose) %>% 34 | na.omit() 35 | purpose_codes <- cites_codes() %>% 36 | filter(field == "Purpose") %>% 37 | pull(code) 38 | expect_setequal(purposes, purpose_codes) 39 | }) 40 | 41 | Sys.setenv(CITES_DB_DIR = olddir) 42 | -------------------------------------------------------------------------------- /tests/testthat/test-03-connection.R: -------------------------------------------------------------------------------- 1 | olddir <- Sys.getenv("CITES_DB_DIR") 2 | Sys.setenv(CITES_DB_DIR = normalizePath(file.path(getwd(), "localdb"), 3 | mustWork = FALSE 4 | )) 5 | 6 | context("Connection") 7 | 8 | test_that("Disconnetion works", { 9 | skip_on_cran() 10 | skip_if_not(cites_status()) 11 | cites_disconnect() 12 | expect_error({ 13 | success <- callr::r(function() { 14 | Sys.setenv(CITES_DB_DIR = normalizePath(file.path(getwd(), "localdb"), 15 | mustWork = FALSE)) 16 | con <- DBI::dbConnect( 17 | duckdb::duckdb(), 18 | dbdir = file.path(Sys.getenv("CITES_DB_DIR")) 19 | ) 20 | out <- inherits(con, "duckdb_connection") 21 | citesdb::cites_disconnect() 22 | options(CITES_DB_DIR = NULL) 23 | return(out) 24 | }) 25 | stopifnot(success) 26 | }, 27 | NA 28 | ) 29 | }) 30 | 31 | test_that("Database is deleted", { 32 | skip_on_cran() 33 | skip_if_not(cites_status()) 34 | 35 | expect_error(cites_db_delete(), NA) 36 | expect_equal(DBI::dbListTables(cites_db()), character(0)) 37 | expect_false(cites_status()) 38 | }) 39 | 40 | test_that("Tables fail when database is deleted", { 41 | skip_on_cran() 42 | 43 | expect_error(cites_shipments()) 44 | expect_error(cites_codes()) 45 | expect_error(cites_metadata()) 46 | expect_error(cites_parties()) 47 | }) 48 | 49 | #unlink(Sys.getenv("CITES_DB_DIR"), recursive = TRUE) 50 | Sys.setenv(CITES_DB_DIR = olddir) 51 | -------------------------------------------------------------------------------- /tests/testthat/test-04-data.R: -------------------------------------------------------------------------------- 1 | context("Data") 2 | 3 | test_that("CITES data source hasn't changed", { 4 | skip_on_cran() 5 | tmpf <- tempfile() 6 | response <- httr::GET("https://trade.cites.org/cites_trade/download_db", 7 | httr::write_disk(tmpf, overwrite = TRUE)) 8 | if (httr::http_error(response)) { 9 | message("CITES data source not responding") 10 | } 11 | hash <- tools::md5sum(tmpf) 12 | unlink(tmpf) 13 | skip_if(httr::http_error(response)) 14 | expect_equivalent(hash, "d64d99182bdfb3696f6ce91687ccdd81") 15 | }) 16 | -------------------------------------------------------------------------------- /tests/testthat/test-lint.R: -------------------------------------------------------------------------------- 1 | # if (requireNamespace("lintr", quietly = TRUE)) { 2 | # context("lints") 3 | # test_that("Package Style", { 4 | # skip_on_cran() 5 | # lintr::expect_lint_free( 6 | # linters = lintr::with_defaults( 7 | # camel_case_linter = NULL, 8 | # snake_case_linter = NULL, 9 | # absolute_paths_linter = NULL, 10 | # line_length_linter = lintr::line_length_linter(120) 11 | # )) 12 | # }) 13 | # } 14 | -------------------------------------------------------------------------------- /vignettes/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.R 3 | -------------------------------------------------------------------------------- /vignettes/citations.bib: -------------------------------------------------------------------------------- 1 | @article{Berec_2018, 2 | doi = {10.1016/j.biocon.2018.05.025}, 3 | url = {https://doi.org/10.1016%2Fj.biocon.2018.05.025}, 4 | year = 2018, 5 | volume = {224}, 6 | pages = {111--116}, 7 | author = {Michal Berec and Lucie Vr{\v{s}}eck{\'{a}} and Irena {\v{S}}etl{\'{i}}kov{\'{a}}}, 8 | title = {What is the reality of wildlife trade volume? {CITES} Trade Database limitations}, 9 | journal = {Biological Conservation} 10 | } 11 | 12 | @article{Robinson_2018, 13 | doi = {10.1111/cobi.13095}, 14 | url = {https://doi.org/10.1111%2Fcobi.13095}, 15 | year = 2018, 16 | volume = {32}, 17 | pages = {1203--1206}, 18 | author = {Janine E. Robinson and Pablo Sinovas}, 19 | title = {Challenges of analyzing the global trade in {CITES}-listed wildlife}, 20 | journal = {Conservation Biology} 21 | } 22 | 23 | @article{Harrington_2015, 24 | doi = {10.1111/cobi.12448}, 25 | url = {https://doi.org/10.1111%2Fcobi.12448}, 26 | year = 2015, 27 | volume = {29}, 28 | pages = {293--296}, 29 | author = {Lauren A. Harrington}, 30 | title = {International commercial trade in live carnivores and primates 2006-2012: response to Bush et {al.} 2014}, 31 | journal = {Conservation Biology} 32 | } 33 | 34 | @article{Harfoot_2018, 35 | doi = {10.1016/j.biocon.2018.04.017}, 36 | url = {https://doi.org/10.1016/j.biocon.2018.04.017}, 37 | year = 2018, 38 | volume = {223}, 39 | pages = {47--57}, 40 | author = {Michael Harfoot and Satu A. M. Glaser and Derek P. Tittensor and Gregory L. Britten and Claire McLardy and Kelly Malsch and Neil D. Burgess}, 41 | title = {Unveiling the patterns and trends in 40 years of global trade in {CITES}-listed wildlife}, 42 | journal = {Biological Conservation} 43 | } 44 | 45 | @article{Eskew_2019, 46 | doi = {10.1016/j.gecco.2019.e00631}, 47 | url = {https://doi.org/10.1016/j.gecco.2019.e00631}, 48 | year = 2019, 49 | volume = {18}, 50 | pages = {e00631}, 51 | author = {Evan A. Eskew and Noam Ross and Carlos Zambrana-Torrelio and William B. Karesh}, 52 | title = {The {CITES} Trade Database is not a "global snapshot" of legal wildlife trade: response to Can et {al.}, 2019}, 53 | journal = {Global Ecology and Conservation} 54 | } 55 | -------------------------------------------------------------------------------- /vignettes/exploring-cites-trade-data-with-citesdb.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Exploring CITES Trade Data with citesdb" 3 | output: rmarkdown::html_vignette 4 | vignette: > 5 | %\VignetteIndexEntry{Exploring CITES Trade Data with citesdb} 6 | %\VignetteEngine{knitr::rmarkdown} 7 | %\VignetteEncoding{UTF-8} 8 | bibliography: citations.bib 9 | link-citations: true 10 | --- 11 | 12 | ```{r, include = FALSE} 13 | knitr::opts_chunk$set( 14 | collapse = TRUE, 15 | comment = "#>", 16 | fig.width = 6.5, 17 | fig.align = "center" 18 | ) 19 | ``` 20 | 21 | 22 | **citesdb** is an R package to conveniently analyze the full CITES shipment-level wildlife trade database, available at . This data consists of over 40 years and 20 million records of reported shipments of wildlife and wildlife products subject to oversight under the [Convention on International Trade in Endangered Species of Wild Fauna and Flora](https://www.cites.org). The source data are maintained by the [UN Environment World Conservation Monitoring Centre](https://www.unep-wcmc.org/). @Harfoot_2018 provide a recent overview of broad temporal and spatial trends in the data. 23 | 24 | 25 | ## Installation 26 | 27 | Install the **citesdb** package with this command: 28 | 29 | ```{r install_me, eval = FALSE} 30 | devtools::install_github("ropensci/citesdb") 31 | ``` 32 | 33 | Note that since **citesdb** installs a source dependency from GitHub, you 34 | will need [package build tools](http://stat545.com/packages01_system-prep.html). 35 | 36 | ```{r message = FALSE, warning = FALSE, error = FALSE, include = FALSE} 37 | options(width = 120) 38 | citesdb::cites_disconnect() 39 | ``` 40 | 41 | 42 | ## Usage 43 | 44 | ### Getting the data 45 | 46 | When you first load the package you will see a message like this: 47 | 48 | library(citesdb) 49 | #> Local CITES database empty or corrupt. Download with cites_db_download() 50 | 51 | Not to worry, just do as it says and run `cites_db_download()`. This will fetch the most recent[^1] database from online, an approximately 158 MB download. It will expand to over 1 GB in the local database. During the download and database building, up to 3.5 GB of disk space may be used temporarily. 52 | 53 | [^1]: When data is updated on the CITES website, we check for changes in structure, metadata, or documentation that we should pass on to the user (e.g., in the `?guidance` help file) and re-package the data for distribution in our own repository. Data updates are expected twice per year, and we expect our repository to update within 2 weeks of the official release. 54 | 55 | ### Using the database for basic analyses 56 | 57 | Once you fetch the data you can connect to the database with the `cites_db()` command. You can use the `cites_shipments()` command to load a remote `tibble` that is backed by the database but not loaded into R. You can use this to analyze CITES data without ever loading it into memory, then gather your results with the `dplyr` function `collect()`. For example, as demonstrated in the package README file, one could compute the number of shipment records per year like so: 58 | 59 | ```{r getdata, include = FALSE} 60 | if (!citesdb::cites_status()) citesdb::cites_db_download() 61 | ``` 62 | 63 | ```{r, warning = FALSE} 64 | library(citesdb) 65 | library(dplyr) 66 | 67 | cites_shipments() %>% 68 | group_by(Year) %>% 69 | summarize(n_records = n()) %>% 70 | arrange(desc(Year)) %>% 71 | collect() 72 | ``` 73 | 74 | (_Note that running `collect()` on all of `cites_shipments()` will load a >3 GB data frame into memory!_) 75 | 76 | Alternatively, one could visualize the same information by piping results from a `cites_shipments()` call directly into `ggplot()`: 77 | 78 | ```{r message = FALSE, warning = FALSE} 79 | library(ggplot2) 80 | 81 | breaks <- seq(from = 1975, to = 2020, by = 5) 82 | 83 | cites_shipments() %>% 84 | group_by(Year) %>% 85 | summarize(n_records = n()) %>% 86 | mutate(log10_n_records = log10(n_records)) %>% 87 | ggplot(aes(x = Year, y = n_records)) + 88 | geom_point() + 89 | geom_line(linetype = "dashed", size = 0.2) + 90 | ylab("Number of Records") + 91 | theme_minimal() + 92 | scale_x_continuous(breaks = breaks) 93 | 94 | cites_shipments() %>% 95 | group_by(Year) %>% 96 | summarize(n_records = n()) %>% 97 | mutate(log10_n_records = log10(n_records)) %>% 98 | ggplot(aes(x = Year, y = log10_n_records)) + 99 | geom_point() + 100 | geom_line(linetype = "dashed", size = 0.2) + 101 | ylab("log10(Number of Records)") + 102 | ylim(1.5, 6.5) + 103 | theme_minimal() + 104 | scale_x_continuous(breaks = breaks) 105 | ``` 106 | 107 | ### Metadata 108 | 109 | The package database also contains tables of field metadata, codes used, and CITES countries. This information comes from ["A guide to using the CITES Trade Database"](https://trade.cites.org/cites_trade_guidelines/en-CITES_Trade_Database_Guide.pdf), on the CITES website. Convenience functions `cites_metadata()`, `cites_codes()`, and `cites_parties()` access this information: 110 | 111 | ```{r} 112 | head(cites_metadata()) 113 | 114 | head(cites_codes()) 115 | 116 | head(cites_parties()) 117 | ``` 118 | 119 | More information on the release of shipment-level data can be found in the `?guidance` help file. 120 | 121 | 122 | ## Direct Database Connection 123 | 124 | **citesdb** stores data in an on-disk [DuckDB](https://duckdb.org/) SQL database. If you want to use SQL commands for complex queries or otherwise want to directly access the database connection, use the `cites_db()` command: 125 | 126 | ```{r} 127 | con <- cites_db() 128 | DBI::dbListTables(con) 129 | ``` 130 | 131 | Note that DuckDB, as implemented by the [DuckDB](https://cran.r-project.org/package=duckdb) package, currently has a limitation of only one connection to the database at a time. Therefore, if you are running R in multiple sessions (say, one in a console and separately knitting an R Markdown document), you will receive this error: 132 | 133 | ``` 134 | Error: Local citesdb database is locked by another R session. 135 | Try closing or running cites_disconnect() in that session. 136 | ``` 137 | 138 | `cites_disconnect()` shuts down the current connection, freeing up your other session to connect. 139 | 140 | If you are using a recent version of RStudio interactively, loading the `citesdb` package also brings up a browsable pane in the "Connections" tab that lets you explore and preview the database tables. 141 | 142 | ![](figures/cites_pane.gif) 143 | 144 | Click on the arrows to see the data types in each table, or the table icon to the right for a preview of the table. The **SQL** button (which appears in RStudio >=1.2) opens an SQL document to [write and preview SQL queries directly](https://blog.rstudio.com/2018/10/02/rstudio-1-2-preview-sql/). 145 | 146 | 147 | ## CITES Metadata with `rcites` 148 | 149 | Suppose we were interested in CITES data on sharks from the order Lamniformes. We might begin an analysis by visualizing shipments of these organisms and their derived products over time: 150 | 151 | ```{r} 152 | cites_shipments() %>% 153 | filter(Order == "Lamniformes") %>% 154 | group_by(Year, Taxon) %>% 155 | summarize(n_records = n()) %>% 156 | ggplot(aes(x = Year, y = n_records, color = Taxon)) + 157 | geom_point() + 158 | geom_line(linetype = "dashed", size = 0.2) + 159 | ylab("Number of Records") + 160 | theme_minimal() + 161 | scale_x_continuous(breaks = breaks, limits = c(1990, max(breaks))) 162 | ``` 163 | 164 | What accounts for the temporal differences in the number of CITES records we observe? Why are there no data prior to 2001? It would be helpful to know more about the history of these particular species within CITES. 165 | 166 | Fortunately, the [**rcites**](https://github.com/ropensci/rcites) package provides access to the Speciesplus/CITES Checklist API, which includes metadata about species and their protected status through time. To use the functions within this package, users will first need to [sign up for a Speciesplus API account](https://api.speciesplus.net/users/sign_up) in order to generate a personal access token. This token can then be set for the current R session using `rcites::set_token()` or can be stored permanently if written to the user's `.Renviron` file (the approach taken in this tutorial). See [here](https://docs.ropensci.org/rcites/articles/a_get_started.html) for more information on use of the API access tokens. 167 | 168 | As an initial step in `rcites` workflows, it will typically be most useful to call `spp_taxonconcept()` on some taxa of interest. Using the specific example of one of our Lamniformes sharks, the great white (*Carcharodon carcharias*), as a query taxon, we can see that this function returns a variety of information: 169 | 170 | ```{r, eval = FALSE} 171 | library(rcites) 172 | 173 | spp_taxonconcept(query_taxon = "Carcharodon carcharias")$general$id 174 | ``` 175 | 176 | ```{r, echo = FALSE, eval = TRUE} 177 | library(rcites) 178 | readRDS(system.file("extdata", "rcites1.rds", package = "citesdb")) 179 | ``` 180 | 181 | Importantly, we can collect the ID for our taxon of interest from this output and store it as an object for ease of reference: 182 | 183 | ```{r, echo = TRUE, eval = FALSE} 184 | great_white_id <- spp_taxonconcept("Carcharodon carcharias")$general$id 185 | ``` 186 | 187 | Using our stored ID variable, we can query other `rcites` functions like `spp_cites_legislation()`, which returns the CITES listing and reservation status for the query taxon. Note that [reservations](https://www.cites.org/eng/app/reserve_intro.php) are essentially exemptions declared by particular CITES Parties in reference to specific taxa. 188 | 189 | ```{r, echo = TRUE, eval = FALSE} 190 | spp_cites_legislation(great_white_id)$cites_listings 191 | ``` 192 | 193 | ```{r, echo = FALSE, eval = TRUE} 194 | readRDS(system.file("extdata", "rcites2.rds", package = "citesdb")) 195 | ``` 196 | 197 | So this function query reveals that the great white is listed under CITES Appendix II (as of 12 January 2005) and that three CITES Parties have active reservations for this species. 198 | 199 | To reveal the full listing and reservation history, rather than just current information, we use the `scope = "all"` argument: 200 | 201 | ```{r, echo = TRUE, eval = FALSE} 202 | spp_cites_legislation(great_white_id, scope = "all")$cites_listings 203 | ``` 204 | 205 | ```{r, echo = FALSE, eval = TRUE} 206 | readRDS(system.file("extdata", "rcites3.rds", package = "citesdb")) 207 | ``` 208 | 209 | Here, we see that the species was in fact listed under CITES Appendix III as early as 29 October 2001. This may account for the CITES trade records for this species that date prior to its uplisting to Appendix II, a status which affords more stringent protection and monitoring. 210 | 211 | In general, the historical listing information provides critical context for CITES data interpretation. In this case, for instance, it is clear that the lack of CITES data for great white sharks prior to the year 2002 should not be taken as an indication of a lack of trade in this species during that time frame but rather a lack of intergovernmental oversight and data collection. 212 | 213 | `rcites` also offers functions that return other useful metadata such as species distribution information: 214 | 215 | ```{r, echo = TRUE, eval = FALSE} 216 | spp_distributions(great_white_id)$distributions 217 | ``` 218 | 219 | ```{r, echo = FALSE, eval = TRUE} 220 | readRDS(system.file("extdata", "rcites4.rds", package = "citesdb")) 221 | ``` 222 | 223 | More in-depth description of `rcites` and usage tutorials can be found via the package [publication](http://joss.theoj.org/papers/10.21105/joss.01091) and [website](https://docs.ropensci.org/rcites/). 224 | 225 | 226 | ## Pitfalls of Working with CITES Trade Data 227 | 228 | The CITES shipment-level data is a valuable resource for understanding part of the global wildlife trade. However, care must be taken in working with this data. Incomplete or ambiguous data can lead to misinterpretation and different approaches to handling the data can lead to different conclusions. @Harrington_2015, @Berec_2018, @Robinson_2018, and @Eskew_2019 all provide greater detail on challenges related to analyzing the CITES Trade Database. Also note the shipment-level guidance provided by CITES, which can be found in the `?guidance` help file. 229 | 230 | As an example, single shipments may be recorded multiple times, as they may be reported by both exporting and importing countries. Here we examine a set of shipments of orchids from a US exporter to the Netherlands: 231 | 232 | ```{r, echo = TRUE, eval = TRUE} 233 | cites_shipments() %>% 234 | filter(Year == 2016, Export.permit.RandomID == "ce63001ff5", Genus == "Paphiopedilum") %>% 235 | collect() %>% 236 | head() %>% 237 | knitr::kable() 238 | ``` 239 | 240 | See that each pair of shipments is identical except for `Reporter.type`, indicating that the shipment was reported both from the US and from the Netherlands. Note that while the importer reported both import and export permit numbers, the exporter reported only the export permit numbers. 241 | 242 | How to deal with repeat records? If you are aggregating records to calculate total shipments it is best to remove them, but not every record is recorded twice. This code filters to use only the importer's records, should all fields other than `Reporter.type` and `Import.permit.RandomID` be the same: 243 | 244 | ```{r} 245 | cites_shipments() %>% 246 | filter(Year == 2016, Export.permit.RandomID == "ce63001ff5", Genus == "Paphiopedilum") %>% 247 | collect() %>% 248 | group_by_at(vars(-Reporter.type, -Import.permit.RandomID)) %>% 249 | mutate(n = n()) %>% 250 | filter((n > 1 & Reporter.type == "I") | n == 1) %>% 251 | ungroup() %>% 252 | head() %>% 253 | knitr::kable() 254 | ``` 255 | 256 | ```{r message = FALSE, warning = FALSE, error = FALSE, include = FALSE} 257 | citesdb::cites_disconnect() 258 | duckdb::duckdb_shutdown(duckdb::duckdb()) 259 | ``` 260 | 261 | 262 | ## Citation 263 | 264 | If you use **citesdb** in a publication, please cite both the package and source data: 265 | 266 | ```{r, results = "asis", echo = FALSE} 267 | print(citation("citesdb"), style = "textVersion") 268 | ``` 269 | 270 | 271 | ## Contributing 272 | 273 | Have feedback or want to contribute? Great! Please take a look at the [contributing guidelines](https://github.com/ropensci/citesdb/blob/master/.github/CONTRIBUTING.md) before filing an issue or pull request. 274 | 275 | Please note that this project is released with a [Contributor Code of Conduct](https://github.com/ropensci/citesdb/blob/master/.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. 276 | 277 | 278 | ## References 279 | 280 |
281 | 282 | [![Created by EcoHealth Alliance](figures/eha-footer.png)](https://www.ecohealthalliance.org/) 283 | -------------------------------------------------------------------------------- /vignettes/figures/cites_pane.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/vignettes/figures/cites_pane.gif -------------------------------------------------------------------------------- /vignettes/figures/eha-footer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/vignettes/figures/eha-footer.png -------------------------------------------------------------------------------- /vignettes/figures/usaid-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ropensci-archive/citesdb/8986014eb46f92f09cf7bc8f684a07c861526f9b/vignettes/figures/usaid-logo.png --------------------------------------------------------------------------------