rredlist: 'IUCN' Red List Client

[willgearty]

Date accepted: 2025-01-28
Submitting Author Name: William Gearty
Submitting Author Github Handle: @willgearty
Other Package Authors Github handles: (comma separated, delete if none) @sckott, @maelle
Repository: https://github.com/ropensci/rredlist
Version submitted:
Submission type: Standard
Editor: @robitalec
Reviewers: @stephhazlitt, @KevCaz

Archive: TBD
Version accepted: TBD
Language: en

---

• Paste the full DESCRIPTION file inside a code block below:

Package: rredlist
Type: Package
Title: 'IUCN' Red List Client
Description: 'IUCN' Red List (<https://api.iucnredlist.org/>) client.
    The 'IUCN' Red List is a global list of threatened and endangered species.
    Functions cover all of the Red List 'API' routes. An 'API' key is required.
Version: 0.7.1.9000
Authors@R: 
    c(person(given = "William",
             family = "Gearty",
             role = c("aut", "cre"),
             email = "willgearty@gmail.com"),
      person(given = "Scott",
             family = "Chamberlain",
             role = c("aut"),
             email = "myrmecocystus@gmail.com"),
      person(given = "rOpenSci",
             role = "fnd",
             comment = "https://ropensci.org/"),
      person(given = "Maëlle",
             family = "Salmon",
             role = "ctb",
             email = "maelle.salmon@yahoo.se")
      )
License: MIT + file LICENSE
URL: https://docs.ropensci.org/rredlist/,
     https://github.com/ropensci/rredlist
BugReports: https://github.com/ropensci/rredlist/issues
Roxygen: list(markdown = TRUE)
Encoding: UTF-8
Language: en-US
Imports:
    crul (>= 0.3.8),
    jsonlite (>= 1.1),
    lifecycle
Suggests:
    spelling,
    testthat,
    vcr (>= 0.4.0),
    knitr,
    rmarkdown
RoxygenNote: 7.3.2
VignetteBuilder: knitr
X-schema.org-applicationCategory: Biodiversity
X-schema.org-keywords: IUCN, biodiversity, API, web-services, traits, habitat, species, conservation
X-schema.org-isPartOf: https://ropensci.org

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • data retrieval
  • data extraction
  • data munging
  • data deposition
  • data validation and testing
  • workflow automation
  • version control
  • citation management and bibliometrics
  • scientific software wrappers
  • field and lab reproducibility tools
  • database software bindings
  • geospatial data
  • text analysis

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

Package retrieves data from the IUCN Red List.

• Who is the target audience and what are scientific applications of this package?

The IUCN Red List is used by a broad range of users, including biologists, ecologists, conservationists, activists, etc. It has many uses including

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

There are no other packages, to my knowledge, that perform the same function.

• (If applicable) Does your package comply with our guidance around Ethics, Data Privacy and Human Subjects Research?

N/A

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

N/A

• Explain reasons for any pkgcheck items which your package is unable to pass.

The pkgcheck package says my package only has 11.2% coverage, but my own coverage checks calculate the coverage to be ~94%.

Technical checks

Confirm each of the following by checking the box.

• I have read the rOpenSci packaging guide.
• I have read the author guide and I expect to maintain this package for at least 2 years or to find a replacement.

This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions, created with roxygen2.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage.

Publication options

• Do you intend for this package to go on CRAN?
  Package is already on CRAN.

• Do you intend for this package to go on Bioconductor?

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

• The package is novel and will be of interest to the broad readership of the journal.
• The manuscript describing the package is no longer than 3000 words.
• You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)
• (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no guarantee that your manuscript will be within MEE scope.)
• (Although not required, we strongly recommend having a full manuscript prepared when you submit here.)
• (Please do not submit your package separately to Methods in Ecology and Evolution)

Code of conduct

• I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[ropensci-review-bot]

Thanks for submitting to rOpenSci, our editors and @ropensci-review-bot will reply soon. Type @ropensci-review-bot help for help.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for rredlist (v0.7.1.9000)

git hash: 4fd92778

• ✔️ Package is already on CRAN.
• ✔️ has a 'codemeta.json' file.
• ✔️ has a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Package has continuous integration checks.
• ✔️ Package coverage is 94.4%.
• ✔️ R CMD check found no errors.
• ✔️ R CMD check found no warnings.

Package License: MIT + file LICENSE

---

1. Package Dependencies

Details of Package Dependency Usage (click to open)

The table below tallies all function calls to all packages ('ncalls'), both internal (r-base + recommended, along with the package itself), and external (imported and suggested packages). 'NA' values indicate packages to which no identified calls to R functions could be found. Note that these results are generated by an automated code-tagging system which may not be entirely accurate.

type	package	ncalls
internal	base	160
internal	utils	128
internal	rredlist	114
internal	stats	3
imports	jsonlite	1
imports	crul	NA
imports	lifecycle	NA
suggests	spelling	NA
suggests	testthat	NA
suggests	vcr	NA
suggests	knitr	NA
suggests	rmarkdown	NA
linking_to	NA	NA

Click below for tallies of functions used in each package. Locations of each call within this package may be generated locally by running 's <- pkgstats::pkgstats(<path/to/repo>)', and examining the 'external_calls' table.

base

list (56), all (40), paste (24), parse (14), class (3), order (3), c (2), drop (2), if (2), is.null (2), lapply (2), subset (2), any (1), args (1), Filter (1), names (1), Negate (1), Sys.getenv (1), url (1), vapply (1)

utils

page (128)

rredlist

rr_GET (47), check_key (3), ct (2), rl_actions_ (2), rl_categories_ (2), rl_class_ (2), rl_comp_groups_ (2), rl_countries_ (2), rl_extinct_ (2), rl_extinct_wild_ (2), rl_family_ (2), rl_faos_ (2), rredlist_ua (2), assert_is (1), assert_n (1), assert_not_na (1), combine_assessments (1), err_catcher (1), page_assessments (1), release_questions (1), rl_actions (1), rl_api_version (1), rl_assessment (1), rl_assessment_ (1), rl_categories (1), rl_citation (1), rl_class (1), rl_common_names (1), rl_common_names_ (1), rl_comp_groups (1), rl_countries (1), rl_extinct (1), rl_extinct_wild (1), rl_family (1), rl_faos (1), rl_green (1), rl_green_ (1), rl_growth_forms_ (1), rl_habitats_ (1), rl_kingdom_ (1), rl_order_ (1), rl_parse (1), rl_phylum_ (1), rl_pop_trends_ (1), rl_realms_ (1), rl_research_ (1), rl_scopes_ (1), rl_sis (1), rl_species (1), rl_stresses_ (1), rl_systems_ (1), rl_threats_ (1), rl_use_and_trade_ (1), rr_base (1), space (1)

stats

family (3)

jsonlite

fromJSON (1)

NOTE: Some imported packages appear to have no associated function calls; please ensure with author that these 'Imports' are listed appropriately.

---

2. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 19 files) and
• 2 authors
• 2 vignettes
• no internal data file
• 3 imported packages
• 84 exported functions (median 12 lines of code)
• 112 non-exported functions in R (median 8 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	19	78.3
files_vignettes	3	89.3
files_tests	183	99.9
loc_R	899	62.7
loc_vignettes	206	47.9
loc_tests	1510	89.2
num_vignettes	2	85.5
n_fns_r	196	88.1
n_fns_r_exported	84	93.5
n_fns_r_not_exported	112	84.0
n_fns_per_file_r	5	73.3
num_params_per_fn	6	77.5
loc_per_fn_r	12	36.9
loc_per_fn_r_exp	12	28.3
loc_per_fn_r_not_exp	8	27.4
rel_whitespace_R	18	63.1
rel_whitespace_vignettes	50	62.2
rel_whitespace_tests	3	94.0
doclines_per_fn_exp	62	74.4
doclines_per_fn_not_exp	0	0.0	TRUE
fn_call_network_size	336	92.5

---

2a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

3. goodpractice and other checks

Details of goodpractice checks (click to open)

3a. Continuous Integration Badges

GitHub Workflow Results

id	name	conclusion	sha	run_number	date
11183436924	lint.yaml	success	4fd927	43	2024-10-04
11183436931	R-CMD-check.yaml	success	4fd927	47	2024-10-04
11183436929	revdep-check	success	4fd927	38	2024-10-04
11183436923	test-coverage.yaml	success	4fd927	43	2024-10-04

---

3b. goodpractice results

R CMD check with rcmdcheck

rcmdcheck found no errors, warnings, or notes

Test coverage with covr

Package coverage: 94.4

Cyclocomplexity with cyclocomp

No functions have cyclocomplexity >= 15

Static code analyses with lintr

lintr found no issues with this package!

---

Package Versions

package	version
pkgstats	0.1.6.17
pkgcheck	0.1.2.58

---

Editor-in-Chief Instructions:

This package is in top shape and may be passed on to a handling editor

[willgearty]

I should mention that rredlist was originally developed by @sckott and is already a part of ropensci. However, the IUCN Red List API has recently changed dramatically, so I basically rewrote the entire package to work with the new API. I thought now was as good a time as any to have the package finally go through ropensci review (with the intent to submit to JOSS afterwards).

[adamhsparks]

@ropensci-review-bot assign @robitalec as editor

[ropensci-review-bot]

Assigned! @robitalec is now the editor

[robitalec]

Editor checks:

• Documentation: The package has sufficient documentation available online (README, pkgdown docs) to allow for an assessment of functionality and scope without installing the package. In particular,
  • Is the case for the package well made?
  • Is the reference index page clear (grouped by topic if necessary)?
  • Are vignettes readable, sufficiently detailed and not just perfunctory?
• Fit: The package meets criteria for fit and overlap.
• Installation instructions: Are installation instructions clear enough for human users?
• Tests: If the package has some interactivity / HTTP / plot production etc. are the tests using state-of-the-art tooling?
• Contributing information: Is the documentation for contribution clear enough e.g. tokens for tests, playgrounds?
• License: The package has a CRAN or OSI accepted license.
• Project management: Are the issue and PR trackers in a good shape, e.g. are there outstanding bugs, is it clear when feature requests are meant to be tackled?

---

Editor comments

Thanks for the submission @willgearty, I am keen to help on this review!

All above looks good to me. Some minor comments below, the authors could consider working on while we are looking for reviewers.

• The README has a great introductory paragraph, installation instructions, and meta information. It could use a brief demonstration of usage, see here.

• The introductory vignette covers installation, authentication, high level and low level interface and best practices. It might be helpful to have a general overview of the available functions or groups of functions in {rredlist}.

• Good to see tests for {rredlist} use {vcr} for HTTP testing. In CONTRIBUTING.md, the authors could consider including a note about how testing is different in {rredlist} due to HTTP requests, maybe by linking to {vcr} and HTTP testing in R? This might help interested contributors to get familiar with HTTP testing.

• One minor note from {goodpractice}:

  tests/testthat/test-rl_threats.R
  Line 82 avoid sapply(), it is not type safe.
        It might return a vector, or a list, depending on the
        input data. Consider using vapply() instead.
  

[robitalec]

@ropensci-review-bot seeking reviewers

[ropensci-review-bot]

Please add this badge to the README of your package repository:

[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/663_status.svg)](https://github.com/ropensci/software-review/issues/663)

Furthermore, if your package does not have a NEWS.md file yet, please create one to capture the changes made during the review process. See https://devguide.ropensci.org/releasing.html#news

[robitalec]

Oh @willgearty, one more thing. I missed this in the editor checks under Statistical Properties. I see doclines_per_fn_not_exp ("median number of lines of documentation for each non-exported R function") is 0. Looking through your R/ directory, I found these non-exported R functions without any documentation.

release.R:

• release_questions

zzz.R:

• ct
• rredlist_ua
• rr_GET
• err_catcher
• rl_parse
• check_key
• rr_base
• space
• assert_is
• assert_n
• assert_not_na
• combine_assessments
• page_assessments

I would suggest adding some internal documentation for anyone trying to debug an issue when using {rredlist}, or to help potential contributors understand how {rredlist} works. You can use the #' @noRd tag (roxygen2 help, dev guide) to prevent .Rd generation. I would think eg. rr_GET, rr_base, rredlist_ua could be good candidates for brief documentation given they are quite central to the package (network of calls). Thanks!