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
)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.
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.
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.
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.
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.
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.
ts_format_ref() does these steps:
Renames columns according to col_map.
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.
Drops rows whose taxonRank is above species, such as genus or family
(see drop_ranks).
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).
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()).
# 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