Gets a table of taxonomic names in Darwin Core format, by downloading it
(from a named source or a URL) or reading it from a local file, optionally
keeps only some taxa, and formats it with ts_format_ref(). The
result can be used directly as ref in ts_match_names() and
ts_resolve_names(), or passed to
ts_optimize_ref().
ts_load_ref(
source = NULL,
url = NULL,
file = NULL,
version = NULL,
cache_dir = NULL,
taxon = NULL,
rank = NULL,
col_map = NULL,
drop_ranks = ts_ranks_above_species(),
keep_cols = NULL,
refresh = FALSE
)Character; name of a source to download (see Details and
ts_show_ref_sources()).
Character; HTTPS URL of a file. It must be a direct link to the file itself, not to a web page about it. Links that redirect to the file are fine.
Character; path to a file.
Optional character. For source, the version to download,
such as "2026-06" for "wfo" (versions from "2022-12" on) or
"v2.1.0" for "ppg"; the default is the latest version (see
ts_show_ref_sources(versions = TRUE) for the versions you can use). For
url and file, a label for the version of the data, which is only
stored in the ts_source attribute of the result so the reference can be
cited.
Character; folder in which to keep downloaded files. Default
NULL (see Details).
Optional; keep only these taxa (and their synonyms), as in
ts_subset_ref().
Passed to ts_subset_ref() (col_map)
and ts_format_ref() (both). Not needed for named sources.
Passed to ts_format_ref(): names of other
columns to keep, such as "nomenclaturalStatus". For named sources that
only read some columns of the file (such as "wfo"), these are read too.
Logical; download again even if the file is already in
cache_dir? Default FALSE.
A dataframe as returned by ts_format_ref(), with the
ts_source attribute describing where the data came from (the source,
URL or file, version, license and citation if known, and the date it was
read).
Give the data in one of three ways, and only one:
source: the name of a source that taxastand knows how to download, such
as "wfo" (World Flora Online) or "itis" (the Integrated Taxonomic
Information System). See ts_show_ref_sources() for the
list, licenses and how to cite them. The latest version is used unless you
give a version, and the version that was used is recorded in the result.
url: a direct link (HTTPS) to a file, not to a web page about it.
file: the path to a file on your computer.
A file can be a comma- or tab-separated text file (such as .csv, .tsv or
.txt, also compressed as .gz), a zipped Darwin Core Archive (.zip), or
a Parquet file (which needs the nanoparquet or the duckdb package; "itis",
"col", "gbif", "ncbi", "ott", "fb" and "slb" are Parquet files
of the taxadb snapshots).
The type is found from the contents of the file, not its name. For a Darwin
Core Archive, the file with the taxa (the "core") and its columns are found
from the meta.xml file in the archive. All columns are read as text.
Steps:
The file is downloaded (for source and url). It is saved to a
temporary file first and moved into place only when complete, so an
interrupted download leaves nothing behind.
The file is read.
If taxon is given, ts_subset_ref() keeps only those taxa
and their synonyms.
The table is formatted with ts_format_ref().
Nothing is downloaded or written unless this function is called. Downloads
are kept in a folder for reuse: cache_dir if given, otherwise the folder
in the option taxastand.cache_dir if set, otherwise a folder in
tempdir(), which is removed when R closes. To keep downloads between R
sessions, give a cache_dir (or set the option). If the file is already
there, it is used and not downloaded again, unless refresh = TRUE. See
ts_show_ref_cache() and ts_clear_ref_cache() to
check and free the space. To silence the messages, set
options(taxastand.verbosity = "quiet") (see
taxastand-package).
Downloads from named sources can be large (World Flora Online is about
120 MB, and GBIF about 360 MB), so loading can take a few minutes. Large
tables also need a lot of memory (a few GB for GBIF). For Parquet files, if
the duckdb package is installed and taxon is given, only the rows for
taxon and their synonyms are read, which is much faster and needs much less
memory; the result is the same.
Checking that the data are what you expect is up to you: the dwctaxon package can validate Darwin Core taxonomic data. Check the license of the data before reusing it.
# Read a reference from a file (no download)
f <- tempfile(fileext = ".csv")
write.csv(
data.frame(
taxonID = c("1", "2"), acceptedNameUsageID = c("1", "1"),
taxonomicStatus = c("accepted", "synonym"),
scientificName = c(
"Polypodium vulgare L.", "Polypodium rotundatum Willd."
)
),
f,
row.names = FALSE
)
ts_load_ref(file = f, version = "example")
#> Loaded 2 names from /tmp/Rtmpr94jwr/file184c3c6665d1.csv (version example).
#> taxonID acceptedNameUsageID taxonomicStatus scientificName
#> 1 1 1 accepted Polypodium vulgare L.
#> 2 2 1 synonym Polypodium rotundatum Willd.
if (FALSE) { # interactive()
# Download a named source (needs internet) and keep only one family. The
# file goes to a temporary folder unless you give `cache_dir`, where it is
# kept so it is not downloaded again next time.
ref <- ts_load_ref(source = "wfo", taxon = "Polypodiaceae")
# A direct link (HTTPS) to a file works too:
# ts_load_ref(url = "https://example.org/taxonomy.zip")
}