R/ts_subset_ref.R
ts_subset_ref.RdSubsets a large table of taxonomic names to the members of one or more taxa
such as a family, so that a reference small enough for the task at hand can
be made. ref should be in Darwin Core format, or close to it (use col_map
for columns with other names). It can be used on the table before or after
ts_format_ref() (which keeps the hierarchy columns), with one
exception: if the table has only parentNameUsageID and no columns for
higher ranks, use ts_subset_ref() first. ts_format_ref() removes the rows
above species, which are needed to walk down from taxon.
ts_subset_ref(ref, taxon, rank = NULL, col_map = NULL)Dataframe of taxonomic names in Darwin Core format, or close to
it, with at least taxonID and acceptedNameUsageID, and either columns
for higher ranks or parentNameUsageID (and scientificName).
Character vector of taxon names to keep, such as
"Polypodiaceae" or c("Polypodiaceae", "Dryopteridaceae"). Rows for
all of them are kept.
Optional character; the rank of taxon, such as "family".
Use it when the same name is used at more than one rank. By default any
rank matches.
Named character vector to map columns of ref to Darwin Core
names, as in ts_format_ref(). The same col_map can be
given to both functions. Default NULL.
The rows of ref for the members of taxon and their synonyms, with
the same columns as ref. A warning is given for any name in taxon that
was not found; it is an error if none were found.
How members are found depends on the columns in ref:
If ref has columns for higher ranks (kingdom, phylum, class,
order, family, genus and a few others), rows are kept when one of
these columns is equal to taxon.
Otherwise, if ref has a parentNameUsageID column, the accepted name
taxon is looked up in scientificName (the author may follow it) and
all of its descendants are kept.
If ref has neither, there is no hierarchy to use and an error is raised.
Next, synonyms of the kept names are added (through
acceptedNameUsageID), because synonyms often have no hierarchy columns.
Last, the accepted names that kept synonyms point to are added, even if they
are outside taxon, so that every synonym in the result has its accepted
name.
x <- data.frame(
taxonID = c("1", "2", "3", "4", "5"),
acceptedNameUsageID = c("1", "2", "3", "1", "5"),
taxonomicStatus = c(
"accepted", "accepted", "accepted", "synonym", "accepted"
),
scientificName = c(
"Polypodium vulgare L.", "Pteris vittata L.", "Pteris cretica L.",
"Polypodium rotundatum Willd.", "Equisetum arvense L."
),
family = c(
"Polypodiaceae", "Pteridaceae", "Pteridaceae", NA, "Equisetaceae"
)
)
ts_subset_ref(x, "Pteridaceae")
#> taxonID acceptedNameUsageID taxonomicStatus scientificName family
#> 2 2 2 accepted Pteris vittata L. Pteridaceae
#> 3 3 3 accepted Pteris cretica L. Pteridaceae
ts_subset_ref(x, c("Polypodiaceae", "Equisetaceae"))
#> taxonID acceptedNameUsageID taxonomicStatus scientificName
#> 1 1 1 accepted Polypodium vulgare L.
#> 4 4 1 synonym Polypodium rotundatum Willd.
#> 5 5 5 accepted Equisetum arvense L.
#> family
#> 1 Polypodiaceae
#> 4 <NA>
#> 5 Equisetaceae