# Inspecting a name list with inspect()

## The problem

A field list reaches you as a column of strings, and some of those strings are wrong. A genus is misspelled, an animal is sitting in a list of plants, a synonym slipped in from an old data sheet, the same species appears under two spellings. `taxify()` will resolve what it can and mark the rest, but it returns a row for every name, matched or not, so the problems are spread through a wide table. Before committing a list to analysis it helps to see only the names that look off, each with a short note on why.

`inspect()` returns one row per anomalous name, ordered most-notable first, each labelled with what stands out and, where known, the name to use instead. Clean names are dropped, so a short report means a clean list.

## A first look, without matching

By default `inspect()` runs only the checks that need no backbone; it matches nothing unless you ask. On a plain character vector it asks the genus register whether each genus is a real one and compares each name against the rest of the batch. Both are fast and offline.

    names <- c(
      "Quercus robur",
      "Panthera leo",         # an animal among plants
      "Bogusia fakensis",     # not a real genus
      "Festuca rubra",
      "Festuca rubra",
      "Festuca rubraa",       # one stray letter
      "Pinus sylvestris",
      "Pinus abies"           # a synonym of Picea abies
    )

    inspect(names)

    #> ── taxify inspection ──────────────────────────────────────
    #>   8 names inspected  |  3 with anomalies
    #>   backbones: none (register + list checks only)
    #>   unresolved: 1   review: 2
    #>   ────────────────────────────────────────────────────────────
    #>   [unresolved] Bogusia fakensis  ->  ?               genus 'Bogusia' 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)

Three names surface. Bogusia fakensis uses a genus no backbone recognises. Festuca rubraa is one letter off Festuca rubra, which appears twice in the same list, so it looks like a slip of that name. Panthera leo is the lone animal among plants, and a cross-kingdom homonym typo often shows up exactly this way.

Pinus abies slips past this first pass. It is a well-formed binomial, and its synonymy with Picea abies surfaces only when a backbone is matched. That check is opt-in.

## The labels

Each flagged name carries one or more labels in its `anomalies` column. The list-only checks need no matching:

Label | Meaning
--- | ---
`unknown` | The genus is not in the register, the union of every backbone’s genera. No backbone recognises it.
`near_duplicate` | A near-twin of a more frequent name in the same list, so probably a misspelling of it. Caught from the list alone, even for names no backbone holds.
`outlier_group` | The name’s kingdom group is a tiny minority of an otherwise coherent list, typically a cross-kingdom homonym typo.

The remaining labels read from a `taxify()` result and only appear once matching has run:

Label | Meaning
--- | ---
`typo` | Resolved only after fuzzy correction. The input most likely contains a spelling error; `suggestion` holds the corrected name.
`synonym` | The input is an outdated synonym; `suggestion` holds the current accepted name.
`case` | Resolved only after ignoring case.
`ambiguous` | A homonym resolving to more than one accepted taxon.
`geographic` | The matched species is real but has no record in a declared region (vascular plants, via WCVP).
`out_of_range` | No region declared, yet the species’ range falls outside the list’s main continents.

## Tiers

Every flagged row also gets a `tier`. A tier names the action a row needs before analysis, from a required decision down to optional cleanup:

- `unresolved`: no usable name came back, so the row needs a decision before analysis. `unknown` lands here.
- `review`: a name is there, but its identity is uncertain. The identity checks (`typo`, `near_duplicate`, `ambiguous`, `geographic`, `out_of_range`, `outlier_group`) land here.
- `note`: the name is correct, the change is optional cleanup. `case` and `synonym` land here.

An anomaly can be intended. A list may genuinely include one animal among plants, or deliberately keep a synonym. The tier is a triage hint, so treat it as a starting point.

## Turning on matching

To pick up typos, synonyms, and ambiguity, let `inspect()` match. The simplest route is `backbones = TRUE`, which runs the names through every installed backbone and records which ones it used in the report header.

    inspect(names, backbones = TRUE)

    #> ── taxify inspection ──────────────────────────────────────
    #>   8 names inspected  |  4 with anomalies
    #>   backbones: COL, GBIF, ITIS
    #>   unresolved: 1   review: 2   note: 1
    #>   ────────────────────────────────────────────────────────────
    #>   [unresolved] Bogusia fakensis  ->  ?              genus 'Bogusia' 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)
    #>   [note      ] Pinus abies       ->  Picea abies    outdated synonym

Now Pinus abies is recognised as a synonym and resolved to Picea abies, and Festuca rubraa carries both its list-context label and the fuzzy `typo` label that confirms it. Panthera leo now matches in GBIF, so the candidate-typo label drops. It stays a kingdom-group outlier in a plant list.

If you have already matched the list, inspect the result instead of asking `inspect()` to match again. This reuses the exact backbone, region, and options of your original call.

    taxify(names, backbone = c("col", "gbif")) |>
      inspect()

The two routes return the same kind of report. Pass `backbones = TRUE` when you want a quick standalone check; pipe a result in when matching is already part of the workflow.

## Geographic checks

When a list is regionally coherent, a species whose range sits elsewhere is worth a second look. With a declared `region`, `inspect()` flags matched species that WCVP does not record there.

    alpine <- taxify(c("Gentiana lutea", "Primula veris", "Banksia serrata")) |>
      inspect(region = "Europe")

    #> ── taxify inspection ──────────────────────────────────────
    #>   3 names inspected  |  1 with anomalies
    #>   backbones: COL
    #>   review: 1
    #>   ────────────────────────────────────────────────────────────
    #>   [review] Banksia serrata  ->  Banksia serrata  outside region per WCVP

Banksia serrata is a real, well-matched name, so nothing else flags it. It is the geographic context that makes it stand out: an Australian shrub in a European list. The same check accepts `coords` instead of a region name, and a `range` argument to count only native or only introduced records. The geographic constraints vignette covers those inputs in full.

Without a declared region, the `out_of_range` check does the comparison from the list itself: it finds the continents that hold the bulk of the matched species and flags any species occurring on none of them. A globally spread list needs too many continents to reach that bulk, fails the coherence test, and flags nothing, so the check stays quiet unless the list is regionally tight. Both geographic checks use WCVP, which covers vascular plants only.

## Reporting fewer rows

On a long list even the `note` rows add up. `min_tier` raises the floor so the report keeps only what needs action.

    # only names that need a decision or a second look
    inspect(names, backbones = TRUE, min_tier = "review")

    #> ── taxify inspection ──────────────────────────────────────
    #>   8 names inspected  |  3 with anomalies
    #>   backbones: COL, GBIF, ITIS
    #>   unresolved: 1   review: 2
    #>   ────────────────────────────────────────────────────────────
    #>   [unresolved] Bogusia fakensis  ->  ?              genus 'Bogusia' 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)

`min_tier = "review"` drops the `note`-tier synonym; `min_tier = "unresolved"` would leave only the unknown name.

## What needs a batch, and what needs the register

The list-context labels (`near_duplicate`, `outlier_group`, `out_of_range`) weigh a name against the rest of the batch, so they cannot apply to a single name. `inspect()` on one name warns and reports only the per-name labels.

    inspect("Quercus robber", backbones = TRUE)
    #> Warning: list-context anomaly checks need a batch of names; with a single
    #> name only the per-name checks run.

The register checks (`unknown`, and the register-derived `outlier_group`) need the genus register installed. Without it they are skipped, with a message at `verbose = TRUE`, and the rest of the checks still run.

## The report is a data.frame

Printing is a convenience. The object underneath is an ordinary data.frame with columns `input_name`, `suggestion`, `anomalies`, `tier`, `reason`, `fuzzy_dist`, and `backbone`, so the report drops straight into a cleaning script.

    report <- inspect(names, backbones = TRUE)

    # the names that came back with a confident replacement
    fixes <- report[!is.na(report$suggestion), c("input_name", "suggestion")]
    fixes

    #>      input_name    suggestion
    #> 1 Festuca rubraa Festuca rubra
    #> 2    Pinus abies   Picea abies

`tier` is an ordered factor (`note` < `review` < `unresolved`), so `report[report$tier >= "review", ]` keeps the rows worth a person’s time. A typical loop is to run `inspect()`, apply the confident `suggestion`s, decide the handful of `unresolved` names by hand, then re-run `taxify()` on the corrected list.

## Where to go next

- Geographic constraints for the `region`, `coords`, and `range` arguments the geographic checks share with `taxify()`.

- Fuzzy matching for how the `typo` label is produced and tuned.

- Getting started for the matching pipeline `inspect()` sits on top of. ```