A species list can resolve differently after a database update. To repeat an analysis, keep a record of the data builds used for matching and enrichment. This article writes that record, checks it against an installation, and pins the installed builds so later sessions keep using them. The examples run offline with a temporary copy of the bundled miniature databases. Installation is covered in Get started.
- Pin the example builds and match a species list.
- Record the builds with
taxify_lock()and their citations withcite(). - Compare an installation with
taxify_restore(). - Inspect the stored builds and release their pins when updates are wanted.
library(taxify)
demo <- tempfile("taxify-reproducibility-")
dir.create(demo)
files <- list.files(taxify_example_data(), full.names = TRUE)
invisible(file.copy(files, demo, recursive = TRUE))
old <- options(taxify.data_dir = demo, taxify.offline = TRUE)The data directory is where taxify stores downloaded databases. Setting the R option above selects the temporary copy for this example. For a project, set that option to its data directory before matching; Choosing and combining backbones describes the directory settings and cleanup.
Pinning the installed builds
A backbone is a published taxonomic database used to resolve names. An enrichment is a dataset joined onto those names, such as woodiness. A pin keeps an installed build active during automatic version checks. Here the World Flora Online (WFO) backbone and the Zanne woodiness dataset are pinned:
pinned <- taxify_pin(c("wfo", "zanne"), verbose = FALSE)
pinned[, c("component", "type", "version", "pinned")]
#> component type version pinned
#> 1 wfo backbone example TRUE
#> 2 zanne enrichment example TRUEPins are stored in the data directory and persist across R sessions.
If a name is installed as both a backbone and an enrichment, supply
kind = "backbone" or kind = "enrichment". This
applies, for example, to the World Checklist of Vascular Plants, whose
name is "wcvp" in both roles.
The miniature WFO data include the oak Quercus robur and the fir Abies alba. Matching these names and adding woodiness gives a result whose data sources can be recorded:
res <- taxify(c("Quercus robur", "Abies alba"), backbone = "wfo",
verbose = FALSE)
res <- add_zanne(res, verbose = FALSE)
res[, c("input_name", "accepted_name", "zanne_woodiness")]
#> input_name accepted_name zanne_woodiness
#> 1 Quercus robur Quercus robur woody
#> 2 Abies alba Abies alba woody
#> Sources: WFO example, Zanne et al. 2014 example | cite() for full citationsWriting the record and citations
A lockfile is a JSON file listing the backbone and contributing enrichment builds. Each entry records a version and, when available, a content ID: the MD5 checksum identifying the database file’s bytes. Create the lock immediately after matching and enrichment, while those backbones are still active.
lock_path <- tempfile(fileext = ".json")
lock <- taxify_lock(res, file = lock_path, verbose = FALSE)
names(lock)
#> [1] "taxify_version" "created" "r_version" "backbones"
#> [5] "enrichments"
vapply(lock$backbones, function(x) x$name, character(1))
#> [1] "wfo"
vapply(lock$enrichments, function(x) x$name, character(1))
#> [1] "zanne"The lock records the backbones that matched rows and enrichments that
supplied values. Calling taxify_lock() without a result
records installed taxon backbones and leaves the enrichment list empty.
Writing a lock leaves the installation’s pin settings as they are.
Keep the input data, matching arguments and R package versions with the script. The lock describes backbone and enrichment assets; genus-register, coverage and region-boundary files need their own record when they affect the analysis. Backbone identities are read from the active installation when the lock is created, so activating another build before locking can record that newer build.
cite() prints the references for the sources used by the
result. Its file argument also writes BibTeX entries for a
manuscript:
bib_path <- tempfile(fileext = ".bib")
invisible(cite(res, file = bib_path))
#> ── taxify citations ────────────────────────────────────────────────────────────
#> [1] Colling G (2026). taxify: Offline Taxonomic Name Matching Against Darwin Core Backbones (version 0.7.1). doi:10.32614/CRAN.package.taxify
#> [2] Borsch T, Berendsohn W, Dalcin E, Delmas M, Demissew S, Elliott A, Fritsch P, Fuchs A, Geltman D, Guner A, et al. (2020). World Flora Online: Placing taxonomists at the heart of a definitive and comprehensive global resource on the world's plants. Taxon 69:1311-1341. doi:10.1002/tax.12373
#> [3] Zanne AE, Tank DC, Cornwell WK, Eastman JM, Smith SA, FitzJohn RG, McGlinn DJ, O'Meara BC, Moles AT, Reich PB, et al. (2014). Three keys to the radiation of angiosperms into freezing environments. Nature 506:89-92. doi:10.1038/nature12872
#> ────────────────────────────────────────────────────────────
#> BibTeX written to: C:\Users\GILLES~1\AppData\Local\Temp\Rtmpyk4twC\fileeb6c40a75966.bib
file.exists(bib_path)
#> [1] TRUESave the lockfile and citation file with the analysis. References
attached to individual trait values can also be resolved with
cite(), as shown in Attaching published
data.
Checking an installation
By default, taxify_restore() compares the lock with the
active installation and returns one row per recorded asset:
report <- taxify_restore(lock_path, verbose = FALSE)
report[, c("component", "type", "status")]
#> component type status
#> 1 wfo backbone ok
#> 2 zanne enrichment okThe status says what could be verified:
| Status | Meaning |
|---|---|
ok |
The comparable content IDs or versions agree. |
content_drift |
Both content IDs exist and differ. |
version_drift |
Versions differ, or a recorded identity has no comparable installed value. |
missing |
The asset file is absent. |
unverified |
The available metadata provide no identity that can be compared. |
The report compares recorded metadata. Its content-ID columns show shortened IDs for readability; the lock retains the full IDs. A matching version alone verifies the version label when comparable content IDs are unavailable.
An empty data directory produces a missing-asset report. The following chunk temporarily selects one and then returns to the example directory:
empty_dir <- tempfile("taxify-empty-")
dir.create(empty_dir)
options(taxify.data_dir = empty_dir)
missing <- taxify_restore(lock_path, verbose = FALSE)
missing[, c("component", "status")]
#> component status
#> 1 wfo missing
#> 2 zanne missing
options(taxify.data_dir = demo)With install = TRUE, restoration retrieves drifted or
missing builds by content ID, activates them, and pins every asset that
matches the lock afterwards. The example builds are already present, so
this call exercises the pinning step offline:
restored <- taxify_restore(lock_path, install = TRUE, verbose = FALSE)
restored[, c("component", "status", "restored", "pinned")]
#> component status restored pinned
#> 1 wfo ok FALSE TRUE
#> 2 zanne ok FALSE TRUEFor published data, the same call can download an absent build. Recovery requires the recorded content ID and an available immutable copy of that build; a local copy can also satisfy the request. Check the returned status after restoration, since a failed retrieval leaves the difference in the report. The miniature example files used here are local teaching data.
Inspecting builds and releasing pins
taxify_store() lists local builds. The
active column identifies the build in the
latest directory; pinned shows whether
automatic refresh leaves it in place. The listing also includes archived
builds kept during restoration or through the version-retention options
described in the function’s help page.
builds <- taxify_store(c("wfo", "zanne"))
builds[, c("component", "type", "active", "pinned", "size_mb")]
#> component type active pinned size_mb
#> 1 wfo backbone TRUE TRUE 0
#> 2 zanne enrichment TRUE TRUE 0Release a pin when the analysis is ready to use updates. Releasing permits the next version check to consider the published build; it leaves the current bytes in place:
released <- taxify_pin(c("wfo", "zanne"), pin = FALSE, verbose = FALSE)
released[, c("component", "pinned")]
#> component pinned
#> 1 wfo FALSE
#> 2 zanne FALSEThe final chunk restores the session’s directory settings and removes the temporary files created by this example.