taxastand matches names against a reference taxonomy
that you supply. This vignette shows the ways to set one up, from a
named source to your own table.
library(taxastand)
library(dplyr)
# Downloads go here. By default they go to a temporary folder.
cache_dir <- file.path(tempdir(), "taxastand-vignette")A reference is a data frame in Darwin Core format with these columns:
taxonID: a unique ID for each nameacceptedNameUsageID: for a synonym, the
taxonID of its accepted name; for an accepted name, its own
ID (or NA)taxonomicStatus: "accepted" or a synonym
statusscientificName: the name with its
author, such as "Polypodium vulgare L."
The author must be part of scientificName, because
taxastand matches on it. Many databases keep the author in
a separate column, scientificNameAuthorship;
ts_format_ref() combines them.
ts_show_ref_sources() lists the sources that
ts_load_ref() can download, with their licenses:
ts_show_ref_sources() |>
select(source, name, license)
#> source name license
#> 1 wfo World Flora Online Plant List CC0 1.0
#> 2 ppg Pteridophyte Phylogeny Group classification (PPG II) CC BY 4.0
#> 3 itis Integrated Taxonomic Information System (ITIS) CC0 1.0
#> 4 col Catalogue of Life (COL) CC BY 4.0
#> 5 gbif GBIF Backbone Taxonomy CC BY 4.0
#> 6 ncbi NCBI Taxonomy CC0 1.0
#> 7 ott Open Tree Taxonomy (OTT) CC0 1.0
#> 8 fb FishBase CC BY-NC 4.0
#> 9 slb SeaLifeBase CC BY-NC 4.0PPG (the Pteridophyte Phylogeny Group classification of ferns and lycophytes) is small, so it makes a good first try:
ppg <- ts_load_ref(source = "ppg", cache_dir = cache_dir)
#> Downloading https://raw.githubusercontent.com/pteridogroup/ppg/v2.1.0/data/ppg.csv
#> Loaded 74784 names from Pteridophyte Phylogeny Group classification (PPG II) (version v2.1.0), license CC BY 4.0.
#> Please cite: Pteridophyte Phylogeny Group. PPG taxonomic database. https://doi.org/10.5281/zenodo.22760360
count(ppg, taxonomicStatus)
#> taxonomicStatus n
#> 1 accepted 15219
#> 2 synonym 55064
#> 3 unchecked 4501The file is downloaded once and kept in cache_dir; later
calls reuse it. The source of the data is stored with the result, for
citing:
attr(ppg, "ts_source")[c("name", "version", "license", "url")]
#> $name
#> [1] "Pteridophyte Phylogeny Group classification (PPG II)"
#>
#> $version
#> [1] "v2.1.0"
#>
#> $license
#> [1] "CC BY 4.0"
#>
#> $url
#> [1] "https://raw.githubusercontent.com/pteridogroup/ppg/v2.1.0/data/ppg.csv"To get an older version, use
ts_show_ref_sources(versions = TRUE) to see what is
available, and provide your selection to the version
argument of ts_load_ref().
Large sources have millions of names. Specify taxon (and
optionally rank) to keep only a family or other group, with
its synonyms:
itis <- ts_load_ref(source = "itis", taxon = "Polypodiaceae", cache_dir = cache_dir)
#> Downloading https://data.source.coop/cboettig/taxadb/2026/dwc_itis_part_0.parquet
#> Loaded 309 names from Integrated Taxonomic Information System (ITIS) (version 2026), license CC0 1.0.
#> Please cite: Integrated Taxonomic Information System (ITIS), https://www.itis.gov/ Accessed through taxadb: Norman, K.E.A., Chamberlain, S. & Boettiger, C. (2020) taxadb: A high-performance local taxonomic database interface. Methods in Ecology and Evolution 11: 1153-1159. https://doi.org/10.1111/2041-210X.13440Then use the reference as usual (see
vignette("basics")):
queries <- c(
"Polypodium vulgare L.",
"Phymatodes scolopendria (Burm. f.) Ching",
"Microsorum scolopendria",
"Polypodium pelucidum Kaulf."
)
res <- ts_resolve_names(queries, itis)
res[match(queries, res$query), c("query", "resolved_name", "matched_status", "match_type")]
#> query
#> 1 Polypodium vulgare L.
#> 4 Phymatodes scolopendria (Burm. f.) Ching
#> 2 Microsorum scolopendria
#> 3 Polypodium pelucidum Kaulf.
#> resolved_name matched_status match_type
#> 1 Polypodium vulgare L. accepted exact
#> 4 Microsorum scolopendria (Burm. f.) Copel. synonym exact
#> 2 Microsorum scolopendria (Burm. f.) Copel. accepted auto_canon
#> 3 Polypodium pellucidum Kaulf. accepted auto_fuzzySome sources are Parquet files. These need the nanoparquet or duckdb package; with duckdb,
taxon is applied while reading, which is faster for very
large files. ts_load_ref() says which package to install if
neither is available.
Downloaded files can be listed with ts_show_ref_cache()
and deleted with ts_clear_ref_cache().
ts_load_ref() also reads a CSV or TSV file
(file =) or downloads one from an HTTPS address
(url =). If the columns have other names, map them to
Darwin Core names with col_map; each name is the Darwin
Core name and each value is your column:
f <- tempfile(fileext = ".csv")
write.csv(
data.frame(
id = c("1", "2", "3"), accepted_id = c("1", "1", "3"),
status = c("Accepted", "Synonym", "Accepted"),
name = c("Polypodium vulgare", "Polypodium rotundatum", "Pteris vittata"),
author = c("L.", "Willd.", "L."),
family = c("Polypodiaceae", NA, "Pteridaceae")
),
f,
row.names = FALSE
)
own <- ts_load_ref(
file = f,
col_map = c(
taxonID = "id", acceptedNameUsageID = "accepted_id",
taxonomicStatus = "status", scientificName = "name",
scientificNameAuthorship = "author"
),
version = "my-table"
)
own
#> taxonID acceptedNameUsageID taxonomicStatus scientificName
#> 1 1 1 accepted Polypodium vulgare L.
#> 2 2 1 synonym Polypodium rotundatum Willd.
#> 3 3 3 accepted Pteris vittata L.
#> family
#> 1 Polypodiaceae
#> 2 <NA>
#> 3 Pteridaceaets_load_ref() combines two steps that you can also use
on any data frame, for example one you made yourself or got from another
package:
ts_subset_ref(ref, taxon) keeps the members of a taxon
and their synonyms. It uses columns for higher ranks (such as
family) if there are any, otherwise walks down from the
taxon using parentNameUsageID.ts_format_ref(ref) formats the data so that
taxastand can use it for name matching and resolution: it
applies col_map, adds the author to the name, drops rows
above species rank, keeps the needed columns and tidies values.If your table has only parentNameUsageID and no columns
for higher ranks, subset first, because formatting drops the rows above
species that are needed to find the members of a taxon.
own |>
ts_subset_ref("Pteridaceae") |>
select(taxonID, scientificName, family)
#> taxonID scientificName family
#> 3 3 Pteris vittata L. PteridaceaeAny other source works the same way: get a data frame, then pass it
to ts_format_ref(). As an example, the taxadb package provides
versioned snapshots of several databases (Catalog of Life, GBIF, NCBI, Open Tree of Life and
others). Ask taxadb for the Darwin Core (dwc) schema:
library(taxadb)
taxadb_itis <- taxa_tbl(provider = "itis", schema = "dwc") |>
filter(family == "Polypodiaceae") |>
collect() |>
ts_format_ref(source = list(provider = "ITIS", version = "2026 (via taxadb)"))
nrow(taxadb_itis)
#> [1] 309This gives the same names as
ts_load_ref(source = "itis"). Use taxadb for providers that
ts_load_ref() does not list; check colnames()
of the table first, since columns differ between databases.
ts_format_ref() does not check that the table is valid;
for example, a synonym could point to an accepted name that is missing.
The dwctaxon package
can validate Darwin Core taxonomic data
(dwctaxon::dct_validate()) and edit it, for example to add
a name that your source lacks.
Before matching, taxastand parses the reference names
and builds the keys it compares them with. With a reference the size of
PPG or WFO this takes longer than the matching itself. If you will match
several batches of queries against the same reference, optimize it once
with ts_optimize_ref() and pass the result in place of the
reference:
itis_prepared <- ts_optimize_ref(itis)
res <- ts_resolve_names(queries, itis_prepared)The results are the same as without optimizing. The genus of every
name is found up front, and each genus is parsed the first time a query
needs it, so the first batch pays for the genera it uses and later
batches reuse them. The optimized reference therefore grows as it is
used. If you optimize a reference with
strip_qualifiers = TRUE, the qualifiers are removed from
the reference names when they are parsed.
Record the source and version with your results, so that the
reference is the same the next time you run the analysis.
ts_load_ref() stores them in the ts_source
attribute (see above). Give version = to get the same
snapshot again, and cite the database and, if you used it, taxadb. Check
each source’s license before reusing a table.
The results in this vignette were made with taxastand 2.0.0.9000, ITIS snapshot 2026, and taxadb 0.3.0.