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")

What a reference needs

A reference is a data frame in Darwin Core format with these columns:

  • taxonID: a unique ID for each name
  • acceptedNameUsageID: for a synonym, the taxonID of its accepted name; for an accepted name, its own ID (or NA)
  • taxonomicStatus: "accepted" or a synonym status
  • scientificName: 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.

Named sources

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.0

PPG (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  4501

The 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().

Keep only part of a large source

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.13440

Then 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_fuzzy

Some 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().

Your own file or URL

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   Pteridaceae

Steps by hand

ts_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. Pteridaceae

Other packages and databases

Any 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] 309

This 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.

Check and edit

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.

Large references

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.

Reproducibility

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.