How to be more reproducible with APCalign

The article will show you how to use APCalign to update and align your plant taxonomic names in a more reproducible manner. The tips offered below will be particularly useful if you used our package and will share your code and data in your research paper or report.

There are two components that we need to cited and their versions determined:

• The APCalign package itself
• The taxonomic resources used by APCalign for aligning and updating your plant taxon names

Both of these components are updated for bug fixes, or to incorporate new taxonomic information and decisions.

First let’s load APCalign

library(APCalign)

APCalign R package version

To determine the version of the APCalign package itself:

packageVersion("APCalign")

Taxonomic Resources

APCalign allows users to load static downloads of taxonomic resources the APC and APNI or the latest version from the National Species List website. This functionality is specified using the stable_or_current_data argument of load_taxonomic_resources().

If you want your taxonomic alignment and update to be reproducible, we recommend to always use stable_or_current_data = "stable". The default value is stable_or_current_data = "stable". These static downloads are version controlled and stored in our repository as releases.

load_taxonomic_resources(stable_or_current_data = "stable")

By default, load_taxonomic_resources() will load the latest version of the static downloads.

load_taxonomic_resources(
  stable_or_current_data = "stable",
  version = default_version()
)

In order to be more transparent, we recommend you to check what is the latest default_version before each alignment

default_version()
#> [1] "2024-10-11"

Then copying and pasting the output into load_taxonomic_resources() directly. This way makes the version of taxonomic resources more explicit in your code.

To ensure the specific version of taxonomic resources is available for subsequent functions make sure to assign them to an object:

resources_0.0.4.9000 <- load_taxonomic_resources(
  stable_or_current_data = "stable",
  version = "0.0.4.9000"
)

Then during alignment and update, make sure you supply your version of taxonomic resources using the resources argument:

# Align taxa
aligned_taxa <- align_taxa(gbif_lite$species, resources = resources_0.0.4.9000)

# Update taxonomy 
updated_taxa <- update_taxonomy(aligned_taxa, resources = resources_0.0.4.9000)

# Align and update all-in-one
aligned_updated_taxa <- create_taxonomic_update_lookup(gbif_lite$species, resources = resources_0.0.4.9000)

Citing the R package

For completion, you can also cite the R package by calling citation(). We also have a research article introducing the APCalign, we will share the details of its citation when it is in press.

citation("APCalign")
#> To cite package 'APCalign' in publications use:
#> 
#>   Wenk E, Cornwell W, Fuchs A, Kar F, Monro A, Sauquet H, Stephens R,
#>   Falster D (2024). "APCalign: an R package workflow and app for
#>   aligning and updating flora names to the Australian Plant Census."
#>   _Australian Journal of Botany_. R package version: 1.0.1,
#>   <https://www.biorxiv.org/content/10.1101/2024.02.02.578715v1>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {APCalign: an R package workflow and app for aligning and updating flora names to the Australian Plant Census},
#>     journal = {Australian Journal of Botany},
#>     author = {Elizabeth Wenk and Will Cornwell and Ann Fuchs and Fonti Kar and Anna Monro and Herve Sauquet and Ruby Stephens and Daniel Falster},
#>     year = {2024},
#>     note = {R package version: 1.0.1},
#>     url = {https://www.biorxiv.org/content/10.1101/2024.02.02.578715v1},
#>   }