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

Arguments

ref

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

taxon

Character vector of taxon names to keep, such as "Polypodiaceae" or c("Polypodiaceae", "Dryopteridaceae"). Rows for all of them are kept.

rank

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.

col_map

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.

Value

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.

Details

How members are found depends on the columns in ref:

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

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

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

Examples

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