occCite: Querying and Managing Large Biodiversity Occurrence Datasets

[hannahlowens]

Date accepted: 2022-03-11
Submitting Author Name: Hannah L. Owens
Submitting Author Github Handle: @hannahlowens
Repository: https://github.com/hannahlowens/occCite
Version submitted: 0.4.0
Editor: @karthik
Reviewers: @peterdesmet

Due date for @peterdesmet: 2020-12-21

Reviewer 2: @damianooldoni
Archive: TBD
Version accepted: TBD

---

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

Package: occCite
Type: Package
Title: Querying and Managing Large Biodiversity Occurrence Datasets
Version: 0.4.0
Authors@R: c(
  person(given = "Hannah L.", family = "Owens", ,"hannah.owens@gmail.com", role=c("aut","cre"),
    comment = c(ORCID = "0000-0003-0071-1745")),
  person(given = "Cory", family = "Merow",,,role="aut",
    comment = c(ORCID = "0000-0003-0561-053X")),
  person(given = "Brian", family = "Maitner", ,,,role="aut",
    comment = c(ORCID = "0000-0002-2118-9880")),
  person(given = "Jamie M.", family = "Kass", ,,,role="aut",
    comment = c(ORCID = "0000-0002-9432-895X")),
  person(given = "Vijay", family = "Barve",,"vijay.barve@gmail.com ",role="aut",
    comment = c(ORCID = "0000-0002-4852-2567")),
  person(given = "Robert P.", family = "Guralnick",,,role="aut",
    comment = c(ORCID = "0000-0001-6682-1504"))
  )
Author: Hannah L. Owens [aut, cre] (<https://orcid.org/0000-0003-0071-1745>), Cory Merow [aut] (<https://orcid.org/0000-0003-0561-053X>), Brian Maitner [aut] (<https://orcid.org/0000-0002-2118-9880>), Jamie M. Kass [aut] (<https://orcid.org/0000-0002-9432-895X>), Vijay Barve [aut] (<https://orcid.org/0000-0002-4852-2567>), Robert P. Guralnick [aut] (<https://orcid.org/0000-0001-6682-1504>)
Maintainer: Hannah L. Owens <hannah.owens@gmail.com>
Description: Facilitates the gathering of biodiversity occurrence data 
  from disparate sources. Metadata is managed throughout the process to facilitate 
  reporting and enhanced ability to repeat analyses.
License: GPL (>= 2)
URL: https://github.com/hannahlowens/occCite
BugReports: https://github.com/hannahlowens/occCite/issues
Encoding: UTF-8
LazyData: true
Language: en-US
Depends: R (>= 3.5.0)
Suggests:
  rmarkdown,
  RColorBrewer,
  viridis,
  remotes,
  RefManageR
Imports:
    bib2df,
    BIEN,
    bit64,
    dplyr,
    ape,
    lubridate,
    methods,
    rgbif (>= 3.1),
    taxize,
    stringr,
    knitr,
    stats,
    leaflet,
    htmltools,
    ggplot2,
    rlang,
    magrittr,
    tidyr,
    RPostgreSQL,
    DBI,
    waffle
VignetteBuilder: knitr
RoxygenNote: 7.1.1

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
  • 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):
  occCite retrieves species occurrence data from several aggregator databases, processes them into a single data object, creates primary data provider citations based on the results.

• Who is the target audience and what are scientific applications of this package?
  The target audience is primarily biogeographers and other researchers interested in the geographic distributions of biodiversity. occCite aims to close the gap in the citation cycle between primary data providers and final research products efficiently, allowing researchers to meet best-practice standards for biodiversity dataset documentation without sacrificing time and resources to the demands of providing increasing levels of detail on their datasets.

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

Tools in R do exist that enable researchers to document sources during the data collection
process—rgbif (Chamberlain et al. 2020a) for GBIF and BIEN (Maitner 2020) for the Botanical
Information and Ecology Network (BIEN) are both examples of API-interface packages that
include valuable features for citing data harvested from their aggregator databases. However, these
packages serve a single aggregator database are designed for specific use cases
tailored to their databases, and uniting aggregator results into a single dataset brings its own set of
challenges. Multi-platform occurrence aggregators do exist—searches using spocc (Chamberlain 2019)
can return occurrence information from up to 6 aggregator databases—but the process of combining data from these aggregators in each query results in the loss of key metadata, particularly accession date, primary data source, and, in the case of GBIF, dataset DOIs. Finally, to our knowledge, there does not yet exist a set of R tools that will manage metadata from an occurrence search and translate it into formatted citations for primary data providers that include accession dates and DOIs.

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

Yes

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

Technical checks

Confirm each of the following by checking the box.

• I have read the guide for authors and rOpenSci packaging guide.

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 using services such as Travis CI, Coveralls and/or CodeCov.

Publication options

• Do you intend for this package to go on CRAN?
• Do you intend for this package to go on Bioconductor?
• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Options

• The package has an obvious research application according to JOSS's definition.
  • The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
  • The package is deposited in a long-term repository with the DOI:
  • (Do not submit your package separately to JOSS)

• 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.

[melvidoni]

Hello @hannahlowens, your Handling Editor will be @karthik. He will get in touch soon with the initial checks.

[karthik]

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.
• Fit: The package meets criteria for fit and overlap
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service.
• License: The package has a CRAN or OSI accepted license
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

👋 @hannahlowens. Here are some general checks from the goodpractice package. As you resolve these issues, you can run goodpractice::gp() yourself to make sure they are resolved. I'll start looking for reviewers now but if you have suggestions for people who can objectively review without a conflict of interest, I'm open to suggestions.

I also noticed there are no tests. Please add test coverage for all your functions. Let us know if you need help or pointers to get started.

It is good practice to

  ✖ write unit tests for all functions, and all package code
    in general. 0% of code lines are covered by test cases.

    R/BIENtableCleanup.R:19:NA
    R/BIENtableCleanup.R:20:NA
    R/BIENtableCleanup.R:21:NA
    R/BIENtableCleanup.R:22:NA
    R/BIENtableCleanup.R:23:NA
    ... and 833 more lines

  ✖ use '<-' for assignment instead of '='. '<-' is the
    standard, and R users and developers are used it and it is easier
    to read your code for them if you use '<-'.

    R/occCitation.R:89:11
    R/occCitation.R:90:13
    R/occCitation.R:91:11
    R/occCitation.R:92:15

  ✖ avoid long code lines, it is bad for readability. Also,
    many people prefer editor windows that are about 80 characters
    wide. Try make your lines shorter than 80 characters

    inst/extdata/sampleScript.R:79:1
    R/data.R:3:1
    R/data.R:4:1
    R/data.R:11:1
    R/data.R:13:1
    ... and 149 more lines

  ✖ omit trailing semicolons from code lines. They are not
    needed and most R coding standards forbid them

    inst/extdata/sampleScript.R:1:17
    inst/extdata/sampleScript.R:21:47
    inst/extdata/sampleScript.R:27:16
    inst/extdata/sampleScript.R:37:59
    inst/extdata/sampleScript.R:44:59
    ... and 17 more lines

  ✖ avoid calling setwd(), it changes the global environment.
    If you need it, consider using on.exit() to restore the working
    directory.

    R/getGBIFpoints.R:34:11
    R/getGBIFpoints.R:71:3
    R/getGBIFpoints.R:88:3
    R/occQuery.R:80:11
    R/occQuery.R:165:7
    ... and 1 more lines

  ✖ avoid sapply(), it is not type safe. It might return a
    vector, or a list, depending on the input data. Consider using
    vapply() instead.

    R/occCite_plotting.R:28:20
    R/occCite_plotting.R:171:28

  ✖ avoid 1:length(...), 1:nrow(...), 1:ncol(...),
    1:NROW(...) and 1:NCOL(...) expressions. They are error prone and
    result 1:0 if the expression on the right hand side is zero. Use
    seq_len() or seq_along() instead.

    R/gbifRetriever.R:36:13
    R/occCitation.R:125:17
    R/occCitation.R:131:17
    R/occCitation.R:137:17
    R/occCitation.R:144:17
    ... and 9 more lines

  ✖ not import packages as a whole, as this can cause name
    clashes between the imported packages. Instead, import only the
    specific functions you need.
  ✖ fix this R CMD check ERROR: Package suggested but not
    available: 'RefManageR' The suggested packages are required for a
    complete check. Checking can be attempted without them by setting
    the environment variable _R_CHECK_FORCE_SUGGESTS_ to a false value.
    See section 'The DESCRIPTION file' in the 'Writing R Extensions'
    manual.

---

Reviewers:
Due date:

[hannahlowens]

Hi Karthik!
Thanks for the feedback. Before I start working through the goodpractice flags, I have what might be a naive question. What do you mean the package doesn't have any tests? Every public function has an example. If the test can't be completed in less than 5s or need user input (like user login information for GBIF), per CRAN guidelines, I flagged it with donttest. Perhaps on a related note, I've been having problems with GitHub Actions ignoring my _R_CHECK_DONTTEST_EXAMPLES_ : false argument.

[karthik]

Hello Hannah. By tests, I mean explicit tests for each functions in the tests folder. Examples are great and can be turned into tests. What you have are more along the lines of informal tests. For an introduction to writing tests, this chapter from the R packages book https://r-pkgs.org/tests.html might be useful.

[karthik]

👋 @poldham! Would you be able to serve as a reviewer for this submission?

[karthik]

👋 @peterdesmet Would you be able to as a second reviewer on this submission?

[peterdesmet]

Hi @karthik, my colleague @damianooldoni and I are happy share second reviewer duties if that is ok with you. Should we wait until tests are implemented in the pkg?

[hannahlowens]

Hi @karthik et al.!

Tests are now implemented in the package.

[karthik]

Hi @peterdesmet. Thank you! I'm happy to have the two of you as reviewers (no need to share duties). Is that ok with you @damianooldoni?

and thanks @hannahlowens! Perfect timing.

[KevCaz]

I saw @melvidoni's tweet today, I am an ecologist who works on occurrence data, and I am relatively comfortable with R packages, so I would be happy to review the package if you think I can be a suitable reviewer!

[Rekyt]

Similar to @KevCaz

I saw @melvidoni's tweet today, I am an ecologist who works on occurrence data, and I am relatively comfortable with R packages, so I would be happy to review the package if you think I can be a suitable reviewer!

I also saw @melvidoni's tweet and I'll be happy to review the package as I'm also a ecologist working with large biodiversity databases.