---
title: "Choosing and combining backbones"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Choosing and combining backbones}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(eval = FALSE)
library(taxify)
```

taxify matches taxonomic names against locally stored Darwin Core backbone
databases. <!-- manifest:backbone-count -->19<!-- /manifest:backbone-count --> backbones are available, each compiled from a different
authoritative source. The backbone we choose determines which names can be
matched, what taxonomic opinion governs synonym resolution, and which extra
metadata columns are available downstream. This vignette walks through the
backbones, explains how to combine them in fallback chains, and offers
practical guidance on which combination to pick for a given project.

## Backend overview

The table below summarizes all <!-- manifest:backbone-count -->19<!-- /manifest:backbone-count -->. "Approx. names" is the total
number of name strings in the compiled backbone (accepted names plus
synonyms); the actual species count is lower because each accepted species
may have several synonym entries pointing to it.

| Backend | Full name | Scope | Approx. names | Source format |
|:--------|:----------|:------|:--------------|:--------------|
| `wfo` | World Flora Online | Vascular plants, bryophytes | ~1.6M | Zenodo ZIP (classification.txt) |
| `col` | Catalogue of Life | All kingdoms | ~5.3M | ChecklistBank DwC-A (Taxon.tsv) |
| `colxr` | Catalogue of Life Extended Release | All kingdoms | ~7.9M | ChecklistBank DwC-A export of the XR dataset |
| `gbif` | GBIF Backbone Taxonomy | All kingdoms | ~6.4M | GBIF simple.txt.gz (30 positional cols) |
| `itis` | Integrated Taxonomic Information System | All kingdoms, US focus | ~990k | SQLite dump from itis.gov |
| `ncbi` | NCBI Taxonomy | All life incl. viruses | ~2.7M | Pipe-delimited .dmp files (taxdump) |
| `ott` | Open Tree of Life | All life (synthetic) | ~3.7M | Pipe-delimited taxonomy.tsv + synonyms.tsv |
| `worms` | World Register of Marine Species | Marine and brackish | ~1.6M | ChecklistBank DwC-A |
| `euromed` | Euro+Med PlantBase | European/Mediterranean plants | ~147k | Semicolon-delimited CSV |
| `fungorum` | Species Fungorum Plus | Fungi | ~315k | ChecklistBank DwC-A |
| `algaebase` | AlgaeBase | Algae and cyanobacteria | ~170k | ChecklistBank DwC-A (CC BY-NC) |
| `fishbase` | FishBase | Fishes | ~100k | rfishbase (load_taxa + synonyms) |
| `sealifebase` | SeaLifeBase | Non-fish marine and aquatic | ~134k | rfishbase (load_taxa + synonyms) |
| `reptiledb` | Reptile Database | Reptiles | ~50k | reptarium taxa.csv + synonym/checklist XLSX |
| `lcvp` | Leipzig Catalogue of Vascular Plants | Vascular plants | ~1.3M | idiv-biodiversity tab_lcvp.rda (R data package) |
| `wcvp` | World Checklist of Vascular Plants (Kew) | Vascular plants | ~1.4M | Kew wcvp.zip (wcvp_names.csv) |
| `mdd` | Mammal Diversity Database | Mammals | ~62k | MDD.zip of CSVs (species + synonyms) |
| `avilist` | AviList (Global Avian Checklist) | Birds | ~41k | AviList extended .xlsx |
| `lpsn` | List of Prokaryotic names with Standing in Nomenclature | Bacteria and archaea | ~45k | ChecklistBank ColDP (NameUsage.tsv) |

A few things stand out. WFO is the standard reference for plant taxonomy,
maintained by the World Flora Online consortium and updated regularly. The
backbone includes all taxonomic ranks from kingdom down to form, with full
synonym resolution and authorship.

COL and GBIF both cover all kingdoms, but they differ in curation strategy.
COL is an expert-curated checklist assembled from over 160 sector databases,
each maintained by a taxonomic authority for its group. GBIF's backbone is
assembled algorithmically from COL, ITIS, and dozens of other sources, which
gives it broader raw coverage (~6.4M names vs COL's ~5.3M) at the cost of
occasional inconsistencies where source databases disagree. In practice, COL
tends to give cleaner synonym resolution; GBIF tends to match more names.

ITIS was originally developed for North American fauna and remains
particularly strong on freshwater invertebrates, insects, and US-listed
species. Its coverage of non-American taxa is uneven. The ITIS backbone is
distributed as a SQLite dump; building it from source requires the RSQLite
package. Pre-built `.vtr` backbones avoid this dependency.

NCBI Taxonomy is the gold standard for sequence-linked work. Every GenBank,
RefSeq, and BOLD sequence is linked to an NCBI tax_id, making this backbone
essential for molecular ecology and metagenomics. It is also the only backbone
that covers bacteria, archaea, and viruses in meaningful depth. However, NCBI
Taxonomy does not store authorship data, so the `authorship` column is always
`NA` for NCBI-matched rows.

OTT (Open Tree of Life) is a synthetic taxonomy that merges NCBI, GBIF,
WoRMS, IRMNG, and several other sources into a single tree. It has the
broadest coverage of any single source and provides cross-references to all
of its constituent databases via the `sourceinfo` field. The trade-off is
that synthetic taxonomies can carry conflicts and inconsistencies at the
edges, where source databases disagree about the placement of a taxon.

WoRMS is the authoritative source for marine species. It is curated by a
network of over 300 taxonomic editors and covers marine, brackish, and some
freshwater species. Beyond basic taxonomy, the WoRMS backbone stores habitat
flags (marine, brackish, freshwater, terrestrial) and extinction status, some
of which are accessible via the COL SpeciesProfile.

Euro+Med PlantBase is the taxonomic reference for the flora of Europe, the
Mediterranean, and the Caucasus. It covers all native and introduced vascular
plants in its geographic scope (~49k accepted names, ~83k synonyms). The
backbone is built from the 2020 bulk download, updated via a PESI API delta
refresh (April 2026) that resolved 1,014 reclassifications and synonym changes
cross-referenced against WFO and POWO. Euro+Med is particularly useful for
European vegetation surveys and datasets aligned with the European Vegetation
Archive (EVA). Its data is licensed CC BY-SA 3.0.

Species Fungorum Plus is the specialist reference for fungal taxonomy, with
~315k names curated by the Royal Botanic Gardens, Kew. It covers Ascomycota,
Basidiomycota, and other fungal phyla, including anamorphs and teleomorphs.
For purely mycological datasets, it gives better synonym resolution than
generalist databases.

AlgaeBase covers micro- and macroalgae, cyanobacteria, and some protists.
It is the only backbone licensed CC BY-NC (non-commercial use only). All other
backbones are open-access. taxify prints a license notice during AlgaeBase
download to make this visible.

FishBase and SeaLifeBase are the standard references for aquatic animals.
FishBase covers fishes; SeaLifeBase covers the non-fish marine and aquatic
groups (molluscs, crustaceans, marine mammals, and the rest). Both are compiled
from the rfishbase package rather than a file download, taking accepted species
from `load_taxa()` and synonym links from `synonyms()`. They carry species-rank
rows only, so their genera enter the genus register derived from those species.
The data is CC BY-NC 3.0.

The Reptile Database is the taxonomic reference for reptiles, with ~50k names
covering snakes, lizards, turtles, crocodilians, and the tuatara. It is built
from the reptarium bulk exports: the current accepted-species list, the periodic
synonym snapshot, and the family-to-order checklist. The source carries no
kingdom or class field, so the backbone stamps Animalia / Chordata / Reptilia on
every row. The data is CC BY 4.0.

The Mammal Diversity Database is the American Society of Mammalogists'
reference mammal taxonomy, distributed as a zip of CSVs holding the accepted
species with their full higher classification and every name ever applied to
them. The data is MIT-licensed.

AviList is the global bird checklist that merged the long-standing IOC,
Clements, and BirdLife split, shipped as one Excel workbook covering order
through subspecies. It publishes no synonym table, so the backbone derives
homotypic synonyms from the `Protonym` column: where a species has since moved
genus, its original combination is a synonym of the current name
(`Parus caeruleus` -> `Cyanistes caeruleus`). The data is CC BY 4.0.

LPSN is the nomenclatural authority for prokaryotes, hosted by DSMZ, and it
answers a question NCBI, GBIF, and OTT leave open: whether a bacterial or
archaeal name is validly published. LPSN's own download route sits behind a
free DSMZ account, so the backbone is built from the open ColDP mirror on GBIF
ChecklistBank. The data is CC BY-SA 4.0.

## Downloading backbones

taxify auto-downloads backbones on first use. When we call `taxify(names,
backbone = "wfo")` and no local WFO backbone exists, taxify fetches the
pre-built `.vtr` file from the taxifydb release it is published under, writes
it to `taxify_data_dir()`, and
caches the path for the remainder of the R session. Subsequent calls, whether
in the same session or future sessions, reuse the local copy without any
network access.

To download a backbone ahead of time (useful on a shared server or in a
Docker image), use `taxify_download()`:

```{r download-single}
# Download one backbone
taxify_download("wfo")

# Download several at once
taxify_download(c("wfo", "col", "worms"))
```

Pre-built `.vtr` files are published as GitHub Releases on
[taxifydb](https://github.com/gcol33/taxifydb), one tag per backbone
(`gbif-2026.06`, `algaebase-2026.06`), and range from 8 MB (AviList) to 2.0 GB
(COL), depending on the backbone. The files are
compiled from the raw Darwin Core sources with precomputed matching keys,
embedded synonym resolution, and genus-level indexes, so they are ready for
querying the moment the download completes.

taxify checks for backbone updates once per R session. The first `taxify()`
call in a session fetches the manifest from GitHub, compares each requested
backbone's local version against the latest available release, and downloads
a new version only if one exists. If the network is unavailable, taxify falls
back to the bundled manifest and uses whatever local copy is on disk. The
version check is logged to the console so there are no silent updates.

For backbones with large source files, the build-from-source path also exists.
`taxify_build("gbif")` downloads the raw 1.5 GB `simple.txt.gz` from
GBIF, parses all 30 positional columns, denormalizes the family hierarchy via
self-joins, and compiles the result into `.vtr` format. This is slower than
downloading the pre-built file but produces the same output. The
build-from-source path is mainly useful for CI pipelines or users who want to
customize the compilation step.

We can also pin a specific backbone version:

```{r download-pinned}
taxify_download("wfo", version = "2024.01")
```

Pinned versions are stored in their own directory
(`taxify_data_dir()/wfo/2024.01/`) and are never overwritten by future
updates. The "latest" slot (`taxify_data_dir()/wfo/latest/`) is always
overwritten when a newer version becomes available. Pinning is useful for
reproducibility: a project can lock a specific backbone version and produce
identical results regardless of when the analysis is re-run.

## Single-backbone matching

The simplest use case: match plant names against WFO.

```{r single-wfo}
plants <- c(
  "Quercus robur",
  "Quercus petraea",
  "Pinus sylvestris",
  "Acer pseudoplatanus",
  "Betula pendula",
  "Fagus sylvatica",
  "Picea abies"
)

result <- taxify(plants, backbone = "wfo")
result[, c("input_name", "accepted_name", "family", "match_type", "backbone")]
```

Every row in the output has 26 columns regardless of which backbone produced
it: `input_name`, `matched_name`, `accepted_name`, `taxon_id`, `accepted_id`,
`rank`, `family`, `genus`, `epithet`, `authorship`, `accepted_authorship`,
`is_synonym`, `is_hybrid`, `match_type`, `fuzzy_dist`, `is_ambiguous`,
`ambiguous_targets`, `backbone`, `backbone_version`, `kingdom_group`,
`taxon_group`, `life_form`, `qualifier`, `qualifier_position`,
`aggregate_fallback`, and `hybrid_type`. The `backbone`
column records `"wfo"` for matched rows and `NA` for unmatched ones. The
`backbone_version` column records the backbone name, version, and download date
(e.g., `"wfo:2024-12 (2026-04-01)"`) so we can cite the exact data snapshot
used.

When a name matches a synonym, taxify automatically resolves it to the
accepted name. The `matched_name` column shows the name string that actually
matched in the backbone (which may be a synonym), while `accepted_name` shows
the current accepted name after resolution. The `is_synonym` column is `TRUE`
for resolved synonyms, `FALSE` for direct matches.

Fuzzy matching is on by default with a normalized Damerau-Levenshtein
threshold of 0.2, roughly one edit per five characters. This catches common
typos like transposed letters or missing diacritics. We can tighten the
threshold for stricter matching:

```{r single-strict}
result <- taxify(plants, backbone = "wfo", fuzzy_threshold = 0.1)
```

Or disable fuzzy matching entirely to only accept exact and case-insensitive
matches:

```{r single-no-fuzzy}
result <- taxify(plants, backbone = "wfo", fuzzy = FALSE)
```

Two alternative distance metrics are available via the `fuzzy_method`
argument: `"levenshtein"` (standard Levenshtein, no transposition handling)
and `"jw"` (Jaro-Winkler, better for names that differ mainly in their
beginnings). The default `"dl"` (Damerau-Levenshtein) is a good all-rounder.

## Backend-specific output differences

All <!-- manifest:backbone-count -->19<!-- /manifest:backbone-count --> backbones produce the same 26-column output schema. This is a
deliberate design choice: downstream code does not need to know which backbone
produced a match. That said, the content of those columns varies in ways
worth knowing about.

**Authorship.** WFO's `scientificName` is already canonical (no authorship
appended), so the `authorship` column comes from a separate
`scientificNameAuthorship` field. COL and WoRMS store the full
`scientificName` with authorship included; taxify strips it at build time to
produce the canonical name used for matching, and the stripped authorship is
stored separately. NCBI and OTT have no authorship data at all, so the
`authorship` column is always `NA` for those backbones. GBIF and ITIS provide
authorship. Euro+Med provides authorship from its `AuthorString` field.
Species Fungorum and AlgaeBase provide authorship from their DwC-A archives.

**Taxon IDs.** Each backbone uses a different identifier system. WFO IDs look
like `"wfo-0000000123"`. COL IDs are opaque alphanumeric strings like
`"4LHBG"`. GBIF uses integer keys (`"2878688"`). ITIS uses TSN integers
(`"183671"`). NCBI uses NCBI Taxonomy IDs (`"9606"`). OTT uses OTT IDs
(`"770315"`). WoRMS uses AphiaIDs extracted from LSIDs; during build time,
taxify strips the `urn:lsid:marinespecies.org:taxname:` prefix and stores
just the numeric ID. Euro+Med uses `TaxonUsageID` integers from the
PlantBase export. Species Fungorum and AlgaeBase use ChecklistBank
dataset-specific IDs. All IDs are stored as character strings in the
`taxon_id` and `accepted_id` columns for consistency, but their format is
backbone-specific and meaningful only within that backbone's ecosystem. A
`taxon_id` from WFO cannot be looked up in the COL database, and vice versa.

**Classification depth.** The base output always includes `family` and
`genus`. WFO provides these directly from its classification file. COL stores
the full Linnaean hierarchy (kingdom through order) in the Taxon.tsv, though
these extra columns require `add_col_info()` to access. GBIF provides family
through a denormalized `family_key` self-join at build time. ITIS, NCBI, and
OTT resolve family and genus via parent-hierarchy walks during backbone
compilation; the walk traverses up to 25 levels of the taxonomic tree. WoRMS
has denormalized classification columns directly in its DwC-A. Euro+Med
resolves family and genus via a hierarchy walk on `IsChildTaxonOfID`. The genus
register (covered later in this vignette) fills in higher classification
fields (`kingdom_group`, `taxon_group`, `life_form`) for all backbones.

**Synonym handling.** The backbones represent synonymy in very different ways
internally. WFO and COL use the Darwin Core field `acceptedNameUsageID` to
point from a synonym row to its accepted name. GBIF encodes synonyms via
`parent_key` pointing to the accepted taxon. NCBI represents synonyms as
alternative name strings for the same `tax_id`; during build, taxify emits
these as separate rows with synthetic IDs of the form `"123456_syn_1"`,
`"123456_syn_2"`, etc. OTT uses a separate `synonyms.tsv` file with explicit
synonym-to-accepted mappings. All of these representations are normalized at
build time into the same `is_synonym` + `accepted_name` + `accepted_id`
schema, so the output looks the same regardless of source.

**Synonym chains.** Some backbones contain chained synonyms, where synonym A
points to synonym B, which points to accepted name C. taxify resolves these
chains at build time (up to 10 hops) so the `accepted_name` always points to
the terminal accepted name. This happens transparently during backbone
compilation and does not affect query-time performance.

## Multi-backbone fallback chains

When a species list spans multiple kingdoms, a single backbone may not cover
everything. A wetland monitoring dataset might contain vascular plants,
invertebrates, amphibians, algae, and fungi. No single backbone covers all of
these equally well. taxify's fallback chain handles this: we pass a vector of
backbone names, and names are matched against each backbone in order. A name
matched by an earlier backbone is never re-matched by a later one; it is
removed from the pool.

```{r multi-basic}
mixed <- c(
  "Quercus robur",       # plant
  "Panthera leo",        # animal
  "Amanita muscaria",    # fungus
  "Salmo trutta",        # fish
  "Escherichia coli"     # bacterium
)

result <- taxify(mixed, backbone = c("wfo", "col", "gbif"))
result[, c("input_name", "accepted_name", "match_type", "backbone")]
```

The console output during matching shows the chain in action:

```
Matching 5 names against 3 backbones: wfo -> col -> gbif
  [wfo] Matching 5 names...
  [col] Matching 4 remaining names...
  [gbif] Matching 1 remaining names...
```

`"Quercus robur"` matches in WFO and is removed from the pool. The remaining
four names go to COL. If any are still unmatched after COL (perhaps an
obscure bacterial name), they go to GBIF. The process continues until all
names have been tried against all backbones or all names have matched.

The order of backbones in the vector matters. It determines which taxonomic
opinion wins for each name. If `"Quercus robur"` exists in both WFO and COL,
putting WFO first means WFO's taxonomic opinion is used (its accepted name,
family assignment, synonym resolution). Putting COL first would give COL's
opinion. For names that exist in multiple backbones, the first backbone in the
chain always wins.

This has practical consequences. If we put GBIF first, everything would match
there (GBIF has ~6.4M names, the largest of any backbone) and the curated
opinions from WFO, COL, or WoRMS would never be consulted. For a plant-heavy
list with some non-plant taxa mixed in, `c("wfo", "col")` or `c("wfo",
"col", "gbif")` is a sensible ordering: we get WFO's curated plant taxonomy
for plants, and COL or GBIF picks up the rest.

If all names have been matched by earlier backbones, later backbones are
skipped entirely with a message:

```
  [gbif] Skipped (all names matched)
```

Fuzzy matching runs independently within each backbone in the chain. A name
that fails exact matching in WFO gets fuzzy-matched against WFO. If it still
fails, it moves to the next backbone and gets exact-matched, then
fuzzy-matched there. This means a misspelled plant name has the best chance
of matching in WFO (the plant-specialist backbone) before falling through to
COL or GBIF.

### Worked example: plants-only with WFO vs WFO + COL

WFO focuses on accepted vascular plant and bryophyte names. Its coverage is
excellent for current taxonomy, but names that appear only in older
literature, belong to genera not yet integrated into WFO, or are
nomenclaturally orphaned (no clear accepted name) may be absent. COL inherits
WFO's plant taxonomy as one of its sector databases but supplements it with
names from other sources, including historical synonyms and cultivar names.

```{r plants-wfo-only}
plants <- c(
  "Quercus robur",
  "Quercus petraea",
  "Pinus sylvestris",
  "Acer pseudoplatanus",
  "Coffea arabica",
  "Welwitschia mirabilis",
  "Lepidodendron aculeatum",   # extinct lycopsid
  "Nothofagus cunninghamii",
  "Dracaena draco"
)

# WFO alone
wfo_result <- taxify(plants, backbone = "wfo")
table(wfo_result$match_type)
```

If any names come back as `"none"`, we can add COL as a fallback:

```{r plants-wfo-col}
# WFO first, COL as fallback
both_result <- taxify(plants, backbone = c("wfo", "col"))
table(both_result$match_type)
both_result[, c("input_name", "accepted_name", "backbone")]
```

The `backbone` column now shows `"wfo"` for names matched by WFO and `"col"`
for names that only COL could resolve. This tells us exactly where each match
came from, which matters for reproducibility. In a paper's methods section,
we can state "plant names were resolved against WFO 2024-12, with unmatched
names resolved against COL 2025."

The two-backbone chain is especially valuable for large vegetation plot
datasets. Most names resolve in WFO with its plant-optimized taxonomy, but
the handful of edge cases (cultivars, historical names, genera recently moved
between families) that fall through to COL would otherwise require manual
resolution.

### Worked example: mixed-kingdom list with COL + GBIF + WoRMS

An ecological monitoring dataset from a coastal estuary might contain
vascular plants, invertebrates, fish, and marine algae. No single backbone
covers all of these well. COL has broad expert-curated coverage across
kingdoms. GBIF fills gaps with its larger name pool. WoRMS provides an
authoritative backstop for marine invertebrate synonymy, which can be
slow to propagate to generalist databases.

```{r mixed-kingdom}
estuary_species <- c(
  "Zostera marina",              # seagrass (plant)
  "Salicornia europaea",         # glasswort (plant)
  "Carcinus maenas",             # shore crab
  "Mytilus edulis",              # blue mussel
  "Platichthys flesus",          # European flounder
  "Nereis diversicolor",         # ragworm
  "Fucus vesiculosus",           # bladderwrack (brown alga)
  "Littorina littorea",          # common periwinkle
  "Arenicola marina",            # lugworm
  "Cerastoderma edule"           # common cockle
)

result <- taxify(estuary_species, backbone = c("col", "gbif", "worms"))
result[, c("input_name", "accepted_name", "family", "backbone")]
```

COL is a good first choice here because it covers all kingdoms with expert
curation. Most of these names will resolve there. GBIF catches anything COL
might miss, including names from national checklists that have not yet been
incorporated into COL. WoRMS serves as a final backstop specifically for
marine taxa, covering invertebrate synonyms that may lag in generalist
databases. The chain is ordered from highest curation to broadest coverage.

If the list were predominantly marine with only a few terrestrial taxa, we
might lead with WoRMS instead to ensure its authoritative marine taxonomy
takes precedence:

```{r marine-first}
result <- taxify(estuary_species, backbone = c("worms", "col"))
```

### Worked example: fungi with Species Fungorum + COL fallback

Mycological datasets benefit from using Species Fungorum Plus as the primary
backbone. It is curated specifically for fungi, with ~315k names including
anamorphs, teleomorphs, and the pleomorphic naming changes introduced by the
2011 Melbourne Code. Synonym coverage for fungal genera is better than in
generalist databases, where fungal taxonomy is often a secondary concern.

```{r fungi}
fungi <- c(
  "Amanita muscaria",
  "Boletus edulis",
  "Cantharellus cibarius",
  "Tuber melanosporum",
  "Saccharomyces cerevisiae",
  "Aspergillus niger",
  "Penicillium chrysogenum",
  "Agaricus bisporus",
  "Trametes versicolor",
  "Cordyceps militaris"
)

result <- taxify(fungi, backbone = c("fungorum", "col"))
result[, c("input_name", "accepted_name", "is_synonym", "backbone")]
```

Species Fungorum resolves the standard names. If any obscure, recently
described, or historically orphaned species fall through, COL picks them up.
For mixed datasets that include both fungi and plants, a three-backbone chain
works well:

```{r fungi-plants-mixed}
mixed <- c(
  "Quercus robur",              # plant
  "Amanita muscaria",           # fungus
  "Lactarius deliciosus",       # fungus
  "Pinus sylvestris",           # plant
  "Russula emetica"             # fungus
)

result <- taxify(mixed, backbone = c("wfo", "fungorum", "col"))
```

WFO handles plants, Species Fungorum handles fungi, and COL serves as a
catch-all for anything that falls through both specialist backbones. The genus
register (see below) helps taxify skip backbones that cannot possibly match a
given name. When taxify encounters `"Amanita muscaria"` and the genus
`Amanita` is not in WFO's coverage table, the name is marked out-of-scope
for WFO immediately and passed to the next backbone without wasting time on
fuzzy matching.

### Worked example: algae

For algal taxonomy, AlgaeBase is the specialist source. It covers micro- and
macroalgae, cyanobacteria, and some protists. Its curation is particularly
strong for freshwater and marine microalgae where generalist databases often
have thin coverage and outdated synonymy.

```{r algae}
algae <- c(
  "Chlamydomonas reinhardtii",
  "Chlorella vulgaris",
  "Ulva lactuca",
  "Fucus vesiculosus",
  "Sargassum muticum"
)

result <- taxify(algae, backbone = c("algaebase", "col"))
result[, c("input_name", "accepted_name", "backbone")]
```

AlgaeBase is licensed CC BY-NC. taxify prints a license notice during
download so users are aware of the restriction before incorporating the data
into a workflow. For commercial applications, COL or WoRMS can serve as
alternatives, though with less specialized algal coverage.

### Worked example: molecular ecology with NCBI

When reconciling species lists from metabarcoding or eDNA studies, names are
often linked to NCBI accessions. Using the NCBI backbone ensures that taxify's
accepted names align with the same taxonomy used in GenBank and BOLD.

```{r ncbi-molecular}
edna_hits <- c(
  "Salmo trutta",
  "Phoxinus phoxinus",
  "Anguilla anguilla",
  "Cottus gobio",
  "Lampetra planeri",
  "Chironomus riparius",     # midge (insect)
  "Potamopyrgus antipodarum" # New Zealand mud snail
)

result <- taxify(edna_hits, backbone = c("ncbi", "col"))
result[, c("input_name", "accepted_name", "taxon_id", "backbone")]
```

The `taxon_id` values for NCBI-matched rows are NCBI tax_ids, which can be
used directly to link back to GenBank records or NCBI taxonomy pages. For
names not found in NCBI (e.g., taxa without sequenced representatives), COL
provides a fallback.

## The backbone column

The `backbone` column in taxify's output is a plain character column. For
single-backbone calls, every matched row shows the same backbone name. For
multi-backbone chains, the column records which backbone produced each match.
Unmatched rows have `backbone = NA`.

We can use this column to count how many names each backbone resolved:

```{r backbone-tally}
result <- taxify(species_list, backbone = c("wfo", "col", "gbif"))
table(result$backbone, useNA = "ifany")
```

Or filter to rows matched by a specific backbone:

```{r backbone-filter}
wfo_matches <- result[result$backbone == "wfo" & !is.na(result$backbone), ]
col_matches <- result[result$backbone == "col" & !is.na(result$backbone), ]
```

This is useful for quality control. If we expected a purely plant-based list
but see many names matched by COL instead of WFO, that tells us the list
contains names outside WFO's scope (perhaps algae classified as plants in
older literature, or animal-associated organisms like plant parasites).

The `backbone_version` column gives the full provenance string for each row,
combining the backbone name, version, and download date. For a paper's methods
section, we can extract the unique versions used:

```{r backbone-versions}
unique(result$backbone_version[!is.na(result$backbone_version)])
# e.g., c("wfo:2024-12 (2026-04-01)", "col:2025 (2026-04-01)")
```

These provenance strings identify both the taxonomic source and the exact
snapshot used, making results fully reproducible even if the backbone releases
a new version between when we run the analysis and when a reviewer checks it.

## Backend-specific extras

Three backbones have dedicated enrichment functions that join additional
backbone-specific columns to a taxify result. These functions only enrich rows
that were matched by the corresponding backbone; rows from other backbones get
`NA` in the new columns.

### WFO extras: `add_wfo_info()`

Adds WFO-specific columns: `scientificNameID`, `parentNameUsageID`,
`namePublishedIn`, `higherClassification`, `taxonRemarks`, and
`infraspecificEpithet`. The `namePublishedIn` field is particularly useful
for citing original descriptions, and `higherClassification` provides the
full taxonomic hierarchy as a semicolon-separated string.

```{r add-wfo}
result <- taxify(plants, backbone = "wfo") |>
  add_wfo_info()

result[, c("input_name", "accepted_name", "namePublishedIn")]
```

### COL extras: `add_col_info()`

Adds COL classification columns (`kingdom`, `phylum`, `col_class`, `order`),
nomenclatural metadata (`notho`, `nomenclaturalCode`, `nomenclaturalStatus`,
`namePublishedIn`), `infraspecificEpithet`, and SpeciesProfile flags
(`is_extinct`, `is_marine`, `is_freshwater`, `is_terrestrial`). The `class`
column is renamed to `col_class` to avoid conflict with R's `class()`
function.

The SpeciesProfile flags come from a separate file in the COL DwC-A archive.
They are especially useful for filtering: we can, for instance, exclude
extinct species from a contemporary biodiversity analysis, or separate marine
from terrestrial taxa in an estuarine dataset.

```{r add-col}
result <- taxify(species_list, backbone = "col") |>
  add_col_info()

# Check which species are marine
result[result$is_marine == TRUE & !is.na(result$is_marine),
       c("input_name", "accepted_name", "kingdom", "is_marine")]
```

### GBIF extras: `add_gbif_info()`

Adds GBIF-specific columns: `notho_type` (hybrid type), `nom_status`
(nomenclatural status), `bracket_authorship` (basionym author),
`bracket_year`, `gbif_year`, `name_published_in`, `origin` (how the name
entered the GBIF backbone), and `infra_specific_epithet`. The `origin`
field is useful for understanding provenance: values like `"SOURCE"`,
`"DENORMED_CLASSIFICATION"`, or `"VERBATIM_ACCEPTED"` indicate how GBIF
ingested the name.

```{r add-gbif}
result <- taxify(species_list, backbone = "gbif") |>
  add_gbif_info()

result[, c("input_name", "accepted_name", "origin", "nom_status")]
```

### Combining extras in a multi-backbone result

In a multi-backbone result, we can pipe through multiple enrichment functions.
Each one only touches rows from its own backbone; the others are left alone.

```{r multi-extras}
result <- taxify(species_list, backbone = c("wfo", "col", "gbif")) |>
  add_wfo_info() |>
  add_col_info() |>
  add_gbif_info()
```

This produces a wide data.frame with the union of all extra columns. For a
given row, only the columns from its backbone are populated; the rest are `NA`.
Whether this is useful depends on the analysis. For most workflows, the base
26 columns are sufficient, and backbone-specific extras are only needed when
we require nomenclatural details, habitat flags, or publication references
that the standard output does not include.

## The genus register

The genus register is a unified index of the genera across every supported
backbone. It holds 503,262 genera, each with its family, higher classification
(kingdom through order, where available), and a `life_form` label (e.g.,
`"vascular plant"`, `"animal"`, `"fungus"`). Where two backbones disagree
about which family a genus belongs to, the classification is resolved by
priority: WoRMS, COL Extended Release, COL, WCVP, Reptile Database, MDD,
AviList, LPSN, GBIF, Euro+Med, LCVP, ITIS, NCBI, OTT, WFO, FishBase,
SeaLifeBase, Species Fungorum, AlgaeBase. If COL and WFO disagree, COL's
assignment wins.

The register is built by taxifydb over that fixed backbone set and published
as a versioned asset, the same way each backbone is, so it arrives by download
rather than by a local build. taxify resolves it on first use: local disk, then
the manifest download, then a local build through
`taxify_build_register()` (equivalently `taxify_download("register")`) if
taxifydb is installed. Building it from whichever backbones a given machine
happened to have installed is what the published asset replaced, because it
made the same code report different `kingdom_group` and `life_form` labels on
two machines.

A `backend_coverage` asset ships alongside it, one row per genus and backbone,
which is what `taxify_register_coverage()` reads.

The register serves two purposes in taxify's matching pipeline. First, it
provides `life_form`, `kingdom_group`, and `taxon_group` columns in taxify
output for every matched name, regardless of which backbone matched it. These
columns make it possible to stratify results by broad taxonomic group without
needing to look up each family manually.

Second, the register enables out-of-scope detection. Before fuzzy matching
begins, taxify checks whether an unmatched name's genus is in the register.
If the genus is known (it appears in the register) but not covered by any of
the requested backbones (it does not appear in the backbone coverage table),
taxify marks the name as `"out_of_scope"` immediately. This avoids wasting
time on fuzzy matching against a backbone that could never produce a match,
and gives the user a more informative signal than a plain `"none"`.

### Looking up a genus

`lookup_genus()` returns the register row for a single genus. The register is
loaded into memory on first call and cached for the session.

```{r lookup-genus}
lookup_genus("Quercus")
#   genus   kingdom phylum class   order   family   life_form
# 1 Quercus Plantae ...    ...     Fagales Fagaceae vascular plant
```

```{r lookup-genus-animal}
lookup_genus("Panthera")
#   genus    kingdom  phylum   class    order     family  life_form
# 1 Panthera Animalia Chordata Mammalia Carnivora Felidae animal
```

### Checking backbone coverage

`taxify_register_coverage()` shows which backbones contain a given genus and
at what version. This is useful when diagnosing match failures: if the genus
does not appear in the coverage table for the requested backbone, the name is
genuinely out of scope for that backbone.

```{r register-coverage}
taxify_register_coverage("Quercus")
#     genus   backbone version date_added
# 1 Quercus  col     2025    2026-04-01
# 2 Quercus  gbif    current 2026-04-01
# 3 Quercus  wfo     2024-12 2026-04-01
```

A genus covered by all three backbones can be matched by any of them. A genus
covered only by GBIF (perhaps a recently described bacterial genus) will not
match against WFO or COL.

### Out-of-scope detection in practice

When taxify encounters an unmatched name whose genus appears in the register
but is not covered by any of the requested backbones, it sets `match_type =
"out_of_scope"` instead of `"none"`. This distinction carries information:
an out-of-scope result means the name likely exists in a different backbone
rather than being a misspelling or invalid name.

```{r out-of-scope}
# Trying to match a marine invertebrate against WFO (plants only)
result <- taxify("Carcinus maenas", backbone = "wfo")
result$match_type
# [1] "out_of_scope"

result$life_form
# [1] "animal"
```

The `life_form` column tells us the genus belongs to animals, confirming that
WFO is the wrong backbone for this name. In a pipeline, we can filter for
`"out_of_scope"` rows and re-run them against a broader backbone. Or, more
practically, we include the right backbones in the fallback chain from the
start, and the out-of-scope mechanism saves time by skipping the fuzzy
matching step for names that cannot possibly match.

The taxify result's `print()` method includes a tally of out-of-scope names
broken down by `taxon_group`, making it easy to see at a glance what kinds of
organisms were outside the requested backbone's scope.

## Practical guidance: choosing backbones

The right backbone depends on the taxonomic scope of the data. Here is a
decision tree organized by the most common use cases.

**Pure vascular plant lists.** Use `backbone = "wfo"`. WFO is the standard
reference, well-curated, and updated regularly. If some names fall through
(e.g., horticultural cultivars, nomenclaturally complex genera, or names from
older floras that use outdated synonymy), add COL: `backbone = c("wfo",
"col")`.

**European vegetation data.** Use `backbone = c("euromed", "wfo")`. Euro+Med
PlantBase is the taxonomic reference used by EVA and covers all native and
introduced vascular plants of Europe, the Mediterranean, and the Caucasus.
Leading with Euro+Med ensures European synonym resolution follows Euro+Med's
taxonomic opinion, with WFO as fallback for non-European taxa or names outside
Euro+Med's scope. Note that Euro+Med data is CC BY-SA 3.0.

**Pure marine/aquatic lists.** Use `backbone = "worms"`. WoRMS is the
authoritative source for marine taxonomy, curated by domain experts, and
includes habitat and extinction flags. For estuarine or transitional lists
that include some terrestrial taxa, add COL: `backbone = c("worms", "col")`.

**Pure fungal lists.** Use `backbone = "fungorum"`. Species Fungorum Plus is
the specialist reference for fungi. Add COL as fallback for obscure or
recently described species: `backbone = c("fungorum", "col")`.

**Pure algal lists.** Use `backbone = "algaebase"`. Add COL or WoRMS as
fallback: `backbone = c("algaebase", "col")`. Remember AlgaeBase is CC BY-NC.

**Mixed-kingdom ecological datasets.** Use `backbone = c("col", "gbif")`, or
lead with a specialist backbone for the dominant taxon group. For a
plant-dominated dataset with some animals and fungi: `backbone = c("wfo",
"col")`. For a marine biodiversity survey: `backbone = c("worms", "col",
"gbif")`. For a forest inventory that includes trees, fungi, insects, and
epiphytes: `backbone = c("wfo", "fungorum", "col")`.

**Molecular/sequence-linked work.** Use `backbone = "ncbi"`. NCBI Taxonomy is
the reference for GenBank, BOLD, and other sequence databases. It covers
bacteria, archaea, and viruses that other backbones lack. For mixed molecular
and ecological work: `backbone = c("ncbi", "col")`.

**Phylogenetic studies.** Use `backbone = "ott"`. OTT is the backbone of the
Open Tree of Life and merges multiple source taxonomies. Its cross-references
to NCBI, GBIF, WoRMS, and IRMNG make it a good bridge between different
identifier systems.

**Maximum coverage / catch-all.** Use `backbone = c("col", "gbif")`. COL
provides expert-curated taxonomy for ~5.3M names. GBIF's backbone adds ~6.4M
names from additional sources. Together they cover virtually all described
species with a nomenclatural record. This combination is a reasonable default
when the taxonomic composition of the dataset is unknown.

**General rule.** Specialist backbones first, generalist backbones second. Lead
with the backbone whose taxonomic opinion we trust most for the dominant taxon
group, and add broader backbones as fallbacks for the remainder. The `backbone`
column in the output lets us audit exactly which taxonomic opinion was applied
to each name.

### Performance considerations

Backend size affects download time and, to a lesser extent, matching speed.
WFO (~1.6M names) matches faster than GBIF (~6.4M names) for the same query.
However, taxify uses index-accelerated genus-blocked joins at the C level
(via vectra), so even GBIF matching is fast for typical species lists. A
list of 5,000 names resolves against GBIF in under a second on modern
hardware. The performance difference only becomes noticeable at scale (100k+
names) or with heavy fuzzy matching against a large backbone.

For large lists with a multi-backbone chain, putting the most likely backbone
first saves time. Names matched by the first backbone skip all later backbones
entirely. If 90% of a list is plants, `c("wfo", "col")` is faster than
`c("col", "wfo")` because WFO is smaller and resolves most names on the
first pass. The remaining 10% of names go to COL, which is larger but only
processes the small residual.

Fuzzy matching is the most expensive step. It runs a genus-blocked fuzzy join
with multi-threaded string distance computation. For names with misspelled
genera (where genus blocking cannot help), taxify falls back to a 2-character
prefix block that catches most genus-level typos while keeping the search
space manageable.

### Reproducibility

The `backbone_version` column encodes the exact data snapshot used. For a
published analysis, we recommend recording these strings in the methods
section or supplementary material. taxify pins the backbone version at
download time and does not update mid-session. Version checks happen
once per R session, and any update is logged to the console with the old and
new version numbers.

To lock a specific backbone version for a project:

```{r reproducibility}
taxify_download("wfo", version = "2024.01")
```

Pinned versions live in their own directories and are never overwritten. The
"latest" slot continues to track new releases independently. A project that
needs exact reproducibility can pin all backbones at specific versions and
never use the "latest" slot. A project that prefers to stay current can rely
on the default "latest" behavior and cite the `backbone_version` strings from
the output.

The manifest, which maps backbone names to their download URLs and latest
versions, is cached per session and can be refreshed with
`taxify_refresh_manifest()`. For offline use, taxify falls back to the
bundled manifest shipped with the package.
