This article shows how to find the
names in a list that need a decision before analysis: a genus no
backbone knows, a misspelling, a species from another kingdom, a
synonym, a species outside the study region. inspect()
returns one row per such name, with a label for what stands out and,
where it can, the name to use instead. At the end the article compares a
whole checklist with a backbone’s current treatment using
reconcile(). Installation is covered in Get started.
Screen the raw names with
inspect(), which needs no matching.
Match them as well, with
backbones = TRUE or by passing a taxify()
result, to find misspellings, synonyms and names with several accepted
taxa.
Place the matched species against a
region.
Filter the report with min_tier,
and apply its suggestions.
Compare a checklist with a backbone’s treatment
with reconcile().
A list straight from field sheets can be screened before anything is
matched. Without matching, inspect() checks each genus
against the genus register, an index of the genera of every backbone,
and compares each name with the rest of the list. The list below is a
plant list with four problems: an animal, a genus that does not exist, a
name written with one extra letter, and an old synonym.
plants <- c(
"Quercus robur", "Panthera leo", "Xyzzia fakensis", "Festuca rubra",
"Festuca rubra", "Festuca rubraa", "Pinus sylvestris", "Pinus abies"
)
inspect(plants)
#> ── taxify inspection ──────────────────────────────────────────
#> 8 names inspected | 3 with anomalies
#> backbones: none (register + list checks only)
#> unresolved: 1 review: 2
#> ────────────────────────────────────────────────────────────
#> [unresolved] Xyzzia fakensis -> ? genus 'Xyzzia' is not in the taxonomic register
#> [review ] Festuca rubraa -> Festuca rubra near-duplicate of more frequent 'Festuca rubra'
#> [review ] Panthera leo -> ? animalia outlier (list is mostly plantae)Festuca rubraa is flagged because the correct spelling occurs twice in the same list. Pinus abies is a well-formed name of a real genus and passes these checks; its synonymy shows only when it is matched.
Some problems, such as an outdated synonym, show only once a name is
matched. backbones = TRUE matches the names against every
installed backbone, in the order of the default fallback chain of
taxify(), and adds the checks that read the match:
report <- inspect(plants, backbones = TRUE, verbose = FALSE)
report
#> ── taxify inspection ──────────────────────────────────────────
#> 8 names inspected | 4 with anomalies
#> backbones: colxr, col, worms, wcvp, euromed, lcvp, wfo, fungorum, algaebase, fishbase, sealifebase, reptiledb, mdd, avilist, lpsn, gbif, itis, ncbi, ott
#> unresolved: 1 review: 3
#> ────────────────────────────────────────────────────────────
#> [unresolved] Xyzzia fakensis -> ? genus 'Xyzzia' is not in the taxonomic register
#> [review ] Festuca rubraa -> Festuca rubra likely misspelling; near-duplicate of more frequent 'Festuca rubra'
#> [review ] Panthera leo -> Panthera leo animalia outlier (list is mostly plantae)
#> [review ] Pinus abies -> Picea abies ambiguous (targets: 4HPZF|4HQ46|8K9Y|6BRMR|4HQ4F|4HQ48); outdated synonymPinus abies is now recognised as a synonym of Picea abies, and as a name with more than one accepted taxon behind it. Festuca rubraa carries the label of the fuzzy match as well as the list check. Panthera leo matches a backbone, so it is reported only as the animal in a plant list.
A list that is already matched is passed to inspect()
directly, which keeps the backbones and options of that call:
Each row has one or more labels in anomalies. Three need
no matching:
unknown: the genus is in no backbone.
near_duplicate: a near-identical spelling of a name
that occurs more often in the same list.
outlier_group: the name’s kingdom is a small
minority in a list that is otherwise of one kingdom.
The others read the match:
typo: resolved only by fuzzy matching;
suggestion holds the corrected name.
synonym: an outdated synonym, or an unplaced name
whose basionym the backbone places; suggestion holds the
accepted name.
case: resolved only after capitals were
ignored.
rank_fallback: an infraspecific name no backbone
holds, resolved to its species.
ambiguous: a name with more than one accepted taxon,
which is not itself the accepted name.
geographic: the species has no record in the
declared region.
out_of_range: without a declared region, the species
occurs on none of the continents that hold most of the list.
The tier names the action a row needs.
unresolved means no usable name came back
(unknown). review means a name is there but
its identity is uncertain (typo,
near_duplicate, rank_fallback,
ambiguous, geographic,
out_of_range, outlier_group).
note means the name is correct and the change is optional
(case, synonym). A row takes the highest tier
of its labels, so Pinus abies is review because it
is also ambiguous. A label can describe something intended,
such as one animal kept on purpose in a plant list.
A species far from the study region is worth a second look even when
its name is correct. The list alpine holds two European
mountain plants and one Australian shrub. With a declared
region, inspect() reports matched species with
no record there in the World Checklist of Vascular Plants (WCVP):
alpine <- c("Gentiana lutea", "Primula veris", "Banksia serrata")
taxify(alpine, backbone = "wcvp", verbose = FALSE) |>
inspect(region = "Europe")
#> ── taxify inspection ──────────────────────────────────────────
#> 3 names inspected | 1 with anomalies
#> backbones: wcvp
#> review: 1
#> ────────────────────────────────────────────────────────────
#> [review] Banksia serrata -> Banksia serrata outside region per WCVPBanksia serrata is an Australian shrub. Its name is correct,
so only the region check reports it. coords and
range work as in taxify(), described in Matching within a region. Both geographic checks
cover vascular plants only, since they read WCVP.
Without a declared region, out_of_range compares each
species with the rest of the list: it finds the continents that hold
most of the matched species and reports a species found on none of them.
A list spread over many continents has no such core, and the check
reports nothing.
A report is used to decide what to change. It is a data frame with
the columns input_name, suggestion,
anomalies, tier, reason,
fuzzy_dist and backbone. min_tier
drops the lower tiers:
inspect(plants, backbones = TRUE, min_tier = "review", verbose = FALSE)
#> ── taxify inspection ──────────────────────────────────────────
#> 8 names inspected | 4 with anomalies
#> backbones: colxr, col, worms, wcvp, euromed, lcvp, wfo, fungorum, algaebase, fishbase, sealifebase, reptiledb, mdd, avilist, lpsn, gbif, itis, ncbi, ott
#> unresolved: 1 review: 3
#> ────────────────────────────────────────────────────────────
#> [unresolved] Xyzzia fakensis -> ? genus 'Xyzzia' is not in the taxonomic register
#> [review ] Festuca rubraa -> Festuca rubra likely misspelling; near-duplicate of more frequent 'Festuca rubra'
#> [review ] Panthera leo -> Panthera leo animalia outlier (list is mostly plantae)
#> [review ] Pinus abies -> Picea abies ambiguous (targets: 4HPZF|4HQ46|8K9Y|6BRMR|4HQ4F|4HQ48); outdated synonymNothing is dropped here: the one note label,
synonym on Pinus abies, sits beside the
review label ambiguous, and a row takes its
highest tier. tier is an ordered factor, so
report[report$tier >= "review", ] selects the same rows
from an existing report. The suggestions can replace the input names
before the list is matched again:
fixes <- report[!is.na(report$suggestion), c("input_name", "suggestion")]
fixes
#> input_name suggestion
#> 2 Festuca rubraa Festuca rubra
#> 3 Panthera leo Panthera leo
#> 4 Pinus abies Picea abiesPanthera leo keeps its own name as the suggestion: the outlier check questions whether it belongs in the list, not how it is spelt.
The checks that compare a name with the rest of the list need more
than one name; inspect() on a single name warns and runs
only the others. A check that could not run, such as the region check
without the WCVP range data, is named on a not checked line
in the header, so an empty report always means that the checks that ran
found nothing.
A checklist compiled years ago follows an older treatment.
reconcile() reports for each name whether the backbone
still accepts it, as one status, and which names now fall
together:
unchanged: the backbone accepts the name.
synonym: the backbone treats it as a
synonym.
misspelling: matched only by fuzzy
matching.
ambiguous: a synonym with more than one accepted
taxon.
unresolved: no match.
The checklist below holds a synonym and its accepted name, a misspelling and a genus name:
checklist <- c(
"Quercus robur", "Pinus abies", "Picea abies", "Festuca rubraa",
"Prunella"
)
rec <- reconcile(checklist, backbone = "col")
#> Matching 5 names...
#> Fuzzy matching 1 unmatched...
rec[, c("input_name", "accepted_name", "status", "merged_with")]
#> input_name accepted_name status merged_with
#> 1 Quercus robur Quercus robur unchanged <NA>
#> 2 Pinus abies Picea abies ambiguous Picea abies
#> 3 Picea abies Picea abies unchanged Pinus abies
#> 4 Festuca rubraa Festuca rubra misspelling <NA>
#> 5 Prunella Prunella unchanged <NA>Pinus abies and Picea abies now name the same
species, so each lists the other in merged_with.
Prunella is the accepted name of two genera and stays
unchanged; n_ids (not shown) counts them.
How names are matched: how the
fuzzy matches behind typo are made.
Matching within a region: the
region, coords and range
arguments.