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
)

Arguments

source

Character; name of a source to download (see Details and ts_show_ref_sources()).

url

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.

file

Character; path to a file.

version

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.

cache_dir

Character; folder in which to keep downloaded files. Default NULL (see Details).

taxon, rank

Optional; keep only these taxa (and their synonyms), as in ts_subset_ref().

col_map, drop_ranks

Passed to ts_subset_ref() (col_map) and ts_format_ref() (both). Not needed for named sources.

keep_cols

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.

refresh

Logical; download again even if the file is already in cache_dir? Default FALSE.

Value

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

Details

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:

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

  2. The file is read.

  3. If taxon is given, ts_subset_ref() keeps only those taxa and their synonyms.

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

Examples

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