Load released taxonomic reference data
Source:R/load_taxonomic_resources.R
load_taxonomic_resources.RdDownloads one or more taxonomic reference datasets from a dated taxonAlign data release, ready to
pass to create_taxonomic_update_lookup(), align_taxa() or prepare_taxonomic_resources().
Naming the release (version) makes an alignment reproducible. Downloaded files are cached, so each
is only downloaded once.
Usage
load_taxonomic_resources(
datasets,
version = NULL,
include_extinct = FALSE,
path = NULL,
refresh_cache = FALSE,
cache_dir = tools::R_user_dir("taxonAlign", "cache"),
quiet = FALSE
)Arguments
- datasets
Character vector of datasets to load, e.g.
c("NSL_animals", "GBIF_AU").- version
Data release to load, a date (
"YYYY-MM-DD"); seedata_release_versions(). Defaults to the latest release, or, with no internet connection, the newest release already downloaded.- include_extinct
Logical; if
TRUE, also keep taxa flagged as extinct, and their synonyms. Defaults toFALSE.- path
Optional directory holding your own copy of a release's files (
manifest.csvand the<dataset>.parquetfiles).versionis then ignored.- refresh_cache
Logical; if
TRUE, re-downloads the files even if they're cached. Defaults toFALSE.- cache_dir
Directory downloaded release files are cached in. Defaults to
tools::R_user_dir("taxonAlign", "cache").- quiet
Logical; suppress progress messages. Defaults to
FALSE.
Value
A named list of tibbles, one per dataset, each in taxonAlign's reference format (see
taxonomic_reference_schema()). The release it came from is recorded in each tibble's
"data_release" attribute.
Details
The datasets in the first release are the Australian National Species List exports –
"NSL_animals" (the Australian Faunal Directory), "NSL_algae", "NSL_bryophytes", "NSL_fungi"
and "NSL_lichens" – and "GBIF_AU", every animal taxon in the GBIF Backbone with occurrence
records in Australia, plus its synonyms. GBIF has since replaced its Backbone with the Catalogue of
Life Extended Release, so later releases have "CatalogueOfLife_AU" instead: that release's animal
names GBIF has Australian records of, plus their synonyms. data_release_datasets() lists what a
release holds, with each dataset's source, retrieval date, licence and citation.
When several datasets are loaded, they're returned in the order given, which is the order they're preferred in when a name appears in more than one.
Some datasets flag extinct taxa (an extinct column; "GBIF_AU"). ("CatalogueOfLife_AU" has no
flag; it leaves out names GBIF knows only from fossil specimens instead.) GBIF's occurrence
records include fossil specimens, so these are left out by default, as they only produce spurious
matches against modern names. GBIF's flag doesn't distinguish fossils from recent extinctions,
though – the thylacine (Thylacinus cynocephalus) is flagged extinct too – so
include_extinct = TRUE keeps everything, with the extinct column showing which are which.
The releases are built by the taxonAlign.dataprep package, which also has the functions for
building a reference from other sources (a live GBIF fetch, taxadb, the AFD's own export, APC).
Examples
# \donttest{
# needs the internet: the lichen list from the National Species List (a few MB), into a
# temporary cache; a misspelling ("inermsi") is corrected
if (curl::has_internet()) {
lichens <- load_taxonomic_resources("NSL_lichens", version = "2026-11-14", cache_dir = tempfile())
create_taxonomic_update_lookup(c("Cladia aggregata", "Usnea inermsi"), lichens)
}
#> Downloading manifest.csv (data release 2026-11-14)...
#> Downloading NSL_lichens.parquet (data release 2026-11-14)...
#> Summary of 2 names:
#> -> 2 aligned to a species or infraspecific taxon (2 in ALC)
#> -> 0 aligned only to a genus and 0 only to a family
#> -> 0 could not be aligned
#> -> 0 aligned names were updated to a different name (e.g. a synonym to its accepted name, or an outdated genus to the current one)
#> # A tibble: 2 × 20
#> original_name aligned_name accepted_name suggested_name genus taxon_rank
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Cladia aggregata Cladia aggrega… Cladia aggre… Cladia aggreg… Clad… species
#> 2 Usnea inermsi Usnea inermis Usnea inermis Usnea inermis Usnea species
#> # ℹ 14 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
#> # scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
#> # number_of_collapsed_taxa <int>, taxon_ID <chr>, taxon_ID_genus <chr>,
#> # scientific_name_ID <chr>, family <chr>, taxonomic_status_aligned <chr>,
#> # alternative_possible_names <chr>, chars_changed <int>, identifier <chr>
# }