New R Tools to Acquire, Manage, Visualize, and Cite Occurrence Data
Submitted by editor on 23 October 2021. Get the paper!Protea cynaroides, King Protea. Our favorite test case as we developed occCite. Photo courtesy of Hannah Owens.
By Hannah L. Owens and Jamie M. Kass, on behalf of all co-authors
There are billions of species occurrence records served by aggregator databases. The Global Biodiversity Information Facility (GBIF) serves over 1.8 billion occurrence records for species from across the tree of life (GBIF Secretariat 2021), and the Botanical Information and Ecology Network (BIEN) serves over 200 million plant observations (Botanical Information and Ecology Network 2021). The primary datasets these aggregators serve are the result of millions of hours of work by museums and community science initiatives (among others) and are constantly updated as taxonomy changes and data are accrued. Citing the primary datasets that supply data to GBIF and BIEN, together with accession dates, facilitates reproducibility and scientific transparency. These citations also support primary data providers by acknowledging their role as an essential link in the research chain.
However, when researchers download occurrence datasets from multiple primary providers via aggregator databases (such as those used in broad-scale biogeographic and macroecological studies), managing and effectively communicating the metadata can be incredibly time-consuming. This is where our new R package, occCite, comes in. occCite is designed to facilitate searches of dataset aggregation services (currently, GBIF and BIEN) that store and manage metadata on primary data providers, database accession dates, DOIs, and taxonomic sources in a unified framework within the R environment. Search results are organized as single objects that can be passed to functions to generate visual and statistical summaries and generate formatted citations.
occCite’s Two Main Steps
-
1. Search. occQuery() provides several ways of generating and optimizing occurrence searches while storing detailed metadata. occQuery() returns an occCiteData object with information on the type of query made, date of the query, taxonomy used, species names used, database aggregators searched, and a named list of search results corresponding to each species.
-
2. Cite. The occCiteData object generated by occQuery() can be passed to occCitation() to automatically generate citations with accession dates and DOIs. occCitation() returns a named list with entries corresponding to the taxonomic names used to build a query. The print() method can be used to turn these results into a formatted and alphabetized set of references, either as a single block of text for all species, or as blocks of text for each species individually.
Additional Features
Taxonomic Rectification. By default, occQuery() checks species’ names against the GBIF backbone taxonomy. The user may instead elect to use studyTaxonList() to prepare a data object with the species’ names to be searched that has been checked against a taxonomy of their choice from the Global Names Index.
Text Summaries. When the print() method is used on an occCiteData object, tables summarizing taxonomic cleaning results, search results with counts of occurrences for each species from each dataset aggregator, and the GBIF DOIs associated with each species’ search are returned.
Summary Plots. occCite provides three types of plots for results from occQuery() when the plot() method is used on an occCiteData object: a histogram showing occurrences by year, a waffle plot showing the proportion of results supplied by GBIF versus BIEN, and a waffle plot showing the proportion of occurrences supplied by each primary data provider. These plots can be generated either for all search results or by species.
An example summary plot for a search of Protea cynaroides occurrence records from GBIF and BIEN.
Maps. Interactive leaflet maps can be generated from occCiteData objects via the occCiteMap() function, for all search results or by species. Users can specify occurrence point marker colors and symbologies. Hovering over a point in the interactive map provides information on the species name, coordinates, date, dataset, and dataset aggregator that supplied it.