Turns a table of taxonomic names in (or close to) Darwin Core format, for example from a downloaded taxonomic database, into a reference that can be used by ts_match_names(), ts_resolve_names() and ts_optimize_ref().

ts_format_ref(
  ref,
  col_map = NULL,
  drop_ranks = ts_ranks_above_species(),
  keep_cols = NULL,
  source = NULL
)

Arguments

ref

Dataframe of taxonomic names. Needs columns for taxonID, acceptedNameUsageID, taxonomicStatus and scientificName (see ts_resolve_names() for what they mean), either with those names or mapped to them with col_map. May also have scientificNameAuthorship and taxonRank.

col_map

Named character vector to rename columns of ref. Each name is the Darwin Core name and each value is the column of ref that holds it. For example, c(taxonID = "taxon_id", scientificName = "canonical_name"). Columns that already have Darwin Core names need not be listed. Default NULL.

drop_ranks

Character vector; rows with a taxonRank in this list (ignoring case) are dropped. The default is the ranks above species rank (kingdom to genus, and the ranks between them such as subfamily, tribe, section and series). Use NULL to keep all rows. Ignored if ref has no taxonRank column.

keep_cols

Optional character vector of the names of other columns of ref to keep, such as "nomenclaturalStatus". They are kept as they are (after col_map has been applied), and must all be in ref. Default NULL: only the columns listed above are kept.

source

Optional list describing where the data came from, for example list(provider = "ITIS", version = "2026", license = "CC0"). It is stored in the ts_source attribute of the result.

Value

A dataframe with columns taxonID, acceptedNameUsageID, taxonomicStatus and scientificName (and taxonRank, if ref had it), plus any columns for the hierarchy of the names that ref had: higher ranks such as family and parentNameUsageID, and any columns named in keep_cols. Other columns are dropped. It has the ts_source attribute if source was given.

Details

ts_format_ref() does these steps:

  1. Renames columns according to col_map.

  2. Adds the author to the species name, if not already included. Matching uses the author, so it must be part of scientificName. Many databases keep the author in a separate column, scientificNameAuthorship; if so, these are combined.

  3. Drops rows whose taxonRank is above species, such as genus or family (see drop_ranks).

  4. Keeps the required columns, taxonRank and the columns that give the hierarchy (higher ranks such as family, and parentNameUsageID), and drops the rest, except for any columns named in keep_cols. This lets ts_subset_ref() be used after ts_format_ref() for most tables (see its documentation for the exception).

  5. Tidies values: taxonomicStatus is lower-cased and trimmed, empty strings become NA, and rows with no name and exact duplicate rows are removed. A missing taxonID (some databases give none to synonyms) is replaced by a made-up unique one, such as "taxastand:17", because ts_resolve_names() needs every name to have an ID.

There is no controlled vocabulary for taxonomic ranks, and databases differ in how many infraspecific ranks they use. Rows are therefore dropped using a list of ranks above species, not kept using a list of ranks to accept: a row with any other rank (including an unknown rank or none) is kept.

ts_format_ref() does not check that the table is valid Darwin Core taxonomic data (for example, that every acceptedNameUsageID points to an existing taxonID). The dwctaxon package can validate and edit such tables (see dwctaxon::dct_validate()).

Examples

# A table with its own column names, and the author in a separate column
x <- data.frame(
  id = c("1", "2", "3"),
  accepted_id = c("1", "1", "3"),
  status = c("Accepted", "Synonym", "Accepted"),
  name = c("Polypodium vulgare", "Polypodium rotundatum", "Polypodium"),
  author = c("L.", "Willd.", "L."),
  rank = c("species", "species", "genus")
)
ts_format_ref(
  x,
  col_map = c(
    taxonID = "id", acceptedNameUsageID = "accepted_id",
    taxonomicStatus = "status", scientificName = "name",
    scientificNameAuthorship = "author", taxonRank = "rank"
  ),
  source = list(provider = "Example", version = "1")
)
#>   taxonID acceptedNameUsageID taxonomicStatus               scientificName
#> 1       1                   1        accepted        Polypodium vulgare L.
#> 2       2                   1         synonym Polypodium rotundatum Willd.
#>   taxonRank
#> 1   species
#> 2   species