taxonAlign aligns a list of raw taxon names against a
taxonomic reference – matching misspellings, synonyms, and names only
identifiable to a higher rank (genus sp.) – and then
updates each match to its current accepted name. The reference can be
one of the dated reference lists taxonAlign publishes (the Australian
National Species List lists, and GBIF’s Australian animals), your own
table, or any mix of these.
It’s inspired by APCalign’s approach to aligning taxon names to the Australian Plant Census, generalised so the reference doesn’t have to be APC/APNI and the taxa don’t have to be plants – every function here works for any taxonomic rank present in your reference, not just species. A real list of raw names is rarely all species anyway – some identifications only ever make it to genus, family, or a “morphospecies” code – so every example below deliberately mixes ranks, not just species names.
Building a reference from other sources – the World Checklist of Vascular Plants, the Catalogue of Life, a live GBIF fetch, a taxadb snapshot, the Australian Plant Census, or your own table with different column names – is the job of the companion package taxonAlign.dataprep, which also builds the released lists. You only need it if you’re building a reference yourself.
This vignette walks through every exported function, in the order you’d typically use them, then puts them together into the workflow you’d actually run on a real list of names.
library(taxonAlign)
library(dplyr)
#>
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#>
#> filter, lag
#> The following objects are masked from 'package:base':
#>
#> intersect, setdiff, setequal, unionChoosing a taxonomic reference
Every matching/aligning function needs a taxonomic reference to match against: a released list, a global taxonomic resource, your own table, or several combined.
A released reference list
The simplest starting point is one of the reference lists published as taxonAlign data releases: dated, fixed copies of each list, so that an alignment can be repeated exactly later by naming the release it used. The releases contain:
| Dataset | Reference | Source |
|---|---|---|
"NSL_animals" |
Animals (Australian Faunal Directory) | The AFD’s National Species List (NSL) export |
"NSL_algae" |
Algae | NSL export (AAL taxa, AANI names) |
"NSL_bryophytes" |
Bryophytes | NSL export (CAB taxa, ABNI names) |
"NSL_fungi" |
Fungi | NSL export (AFL taxa, AFNI names) |
"NSL_lichens" |
Lichens | NSL export (ALC taxa, ALNI names) |
"GBIF_AU" |
Animals recorded in Australia (GBIF) | GBIF Backbone taxonomy: taxa with Australian occurrence records,
plus their synonyms. In the 2026-10-07 release; replaced by
"CatalogueOfLife_AU" from the next one, as GBIF has
replaced its Backbone with the Catalogue of Life Extended Release |
"CatalogueOfLife_AU" |
Animals recorded in Australia (Catalogue of Life) | Catalogue of Life Extended Release (COL26.10 XR): animal names with
Australian records. From the 2026-11-14 release. |
data_release_versions() lists the releases available,
most recent first, and data_release_datasets() lists what’s
in one, with each dataset’s source, retrieval date, licence and
citation:
data_release_versions()
#> [1] "2026-11-14" "2026-10-07"
data_release_datasets("2026-11-14")load_taxonomic_resources() loads one or more datasets.
Each is downloaded the first time you use it and stored on your computer
(in tools::R_user_dir("taxonAlign", "cache")), so after
that it loads without downloading again, and works offline. The result
can go straight into any of the matching functions:
animals <- load_taxonomic_resources(c("NSL_animals", "CatalogueOfLife_AU"))
create_taxonomic_update_lookup(c("Pardalotus striatus", "Cynthia cardui"), animals)When you load more than one dataset, the order you name them in is
their priority: a name found in "NSL_animals" is matched
there, and "CatalogueOfLife_AU" is only used for names the
AFD doesn’t have.
GBIF’s occurrence records include fossil specimens, so taxa GBIF
flags as extinct are left out by default, as they would otherwise
produce spurious matches. GBIF’s flag doesn’t distinguish fossils from
recent extinctions, though (the thylacine is flagged extinct too), so
include_extinct = TRUE keeps everything, with an
extinct column showing which are which.
Each NSL list combines the group’s two NSL exports: the taxon file (accepted names and their synonyms, with links between them) and the names file (every name recorded for the group). The taxon file always takes priority; names found only in the names file are added so they can still be recognised, but they’re never “updated” to anything, since the names file doesn’t link them to an accepted name. Each release also holds the NSL exports themselves, unchanged, so every list can be traced back to exactly what was supplied.
Naming the release. Without version,
the latest release is used. To make an analysis reproducible, name the
release instead – the same release always gives the same result:
animals <- load_taxonomic_resources("NSL_animals", version = "2026-10-07")Working offline. A named release that has already
been downloaded is loaded straight from your computer, without going
online at all. Without version, taxonAlign checks GitHub
once per session (with a short time limit) for the latest release; if it
can’t (no internet, a slow connection), it uses the most recent release
already on your computer. Releases are only published when a source
actually changes, so an older release isn’t necessarily out of date.
Download global taxonomic resources
For taxa the released lists don’t cover, or a reference that covers
the whole world, the companion package taxonAlign.dataprep
downloads the major global taxonomic resources and reshapes them into
taxonAlign’s format. Install it with
pak::pak("traitecoevo/taxonAlign.dataprep").
| Function | Reference | Best for |
|---|---|---|
load_CatalogueOfLife() |
Catalogue of Life, from ChecklistBank | A reference to every taxon in every kingdom (~5.5 million names);
extended = TRUE for its Extended Release (~8.5 million),
GBIF’s own taxonomy |
load_WCVP() |
World Checklist of Vascular Plants (Royal Botanic Gardens, Kew) | Every vascular plant name worldwide (~1.45 million) |
filter_to_country() |
Any of the above | Keeping only the taxa GBIF has occurrence records of in one or more countries |
Each returns one table in taxonAlign’s format, which goes straight into the matching functions:
library(taxonAlign.dataprep)
# every vascular plant name worldwide, then only those GBIF has Australian records of
wcvp_au <- load_WCVP() |> filter_to_country("AU")
create_taxonomic_update_lookup(my_plant_names, wcvp_au)
# the Catalogue of Life, pinned to one release (COL26.10) so the alignment can be repeated
col <- load_CatalogueOfLife(316595)
# GBIF's own taxonomy (the Catalogue of Life Extended Release), only the animals GBIF has
# Australian records of
col_xr_au <- load_CatalogueOfLife(extended = TRUE) |> filter_to_country("AU", gbif_taxon = "Animalia")A few things worth knowing:
-
The WCVP and Catalogue of Life are large downloads
(~90MB and ~170MB). Each is downloaded once and cached, so later calls
load from your computer, offline. Name a version
(
load_WCVP(16),load_CatalogueOfLife(316595)) to make an alignment repeatable. -
A worldwide list matches more names than you may
want: a misspelt Australian plant name can fuzzy-match a
species that only grows in South America.
filter_to_country()avoids this. It keeps each taxon’s accepted name and all its synonyms, even where GBIF and the reference disagree on which name is accepted, so old names in your list still update. -
taxadb’s own GBIF snapshot can be several years
old. Pass
gbif_snapshot_urlto query a current GBIF snapshot instead. taxadb is only needed for this one function: install it withinstall.packages("taxadb"). -
For Australian vascular plants,
load_APC()loads the Australian Plant Census, the National Species List for vascular plants.
taxonAlign.dataprep’s own getting-started vignette covers each of these in detail.
Your own reference table
If you already have a taxonomic reference table – your own species
list, an export from a museum database, whatever – taxonAlign will take
it as long as it’s in taxonAlign’s reference format: eight required
columns, canonical_name, scientific_name,
taxon_rank, taxonomic_status,
taxonomic_dataset, genus,
taxon_ID and accepted_name_usage_ID.
taxonomic_reference_schema() describes each:
taxonomic_reference_schema() |> filter(required) |> select(column, description)
#> # A tibble: 8 × 2
#> column description
#> <chr> <chr>
#> 1 canonical_name "The name without authorship, e.g. \"Boronia serrulata…
#> 2 scientific_name "The name with authorship, e.g. \"Boronia serrulata Sm…
#> 3 taxon_rank "The record's rank, e.g. \"species\", \"genus\", \"fam…
#> 4 taxonomic_status "\"accepted\" for a currently accepted name; anything …
#> 5 taxonomic_dataset "The reference the record comes from, e.g. \"APC\", \"…
#> 6 genus "The genus of a genus-rank or narrower record (for a s…
#> 7 taxon_ID "An identifier for the record, unique within the table…
#> 8 accepted_name_usage_ID "The taxon_ID of the accepted name the record leads to…Here’s a small, hand-built example spanning several ranks: two genera, a family, a subgenus, a species with two synonyms (one under a different genus entirely – a real, common pattern when a species is reclassified over its taxonomic history), and a subspecies.
my_reference <- tibble::tribble(
~scientific_name, ~canonical_name, ~taxon_rank, ~taxonomic_status, ~taxonomic_dataset, ~genus, ~taxon_ID, ~accepted_name_usage_ID,
"Aporocera t-viride Blackburn, 1899", "Aporocera t-viride", "species", "accepted", "MY_DATA", "Aporocera", "sp1", "sp1",
"Aporocera viridipennis Lea, 1915", "Aporocera viridipennis", "species", "synonym", "MY_DATA", "Aporocera", "sp2", "sp1",
"Chalcolampra viridis Blackburn, 1897", "Chalcolampra viridis", "species", "synonym", "MY_DATA", "Chalcolampra", "sp3", "sp1",
"Aporocera Blackburn", "Aporocera", "genus", "accepted", "MY_DATA", NA, "g1", "g1",
"Aporocera (Aporocera) Blackburn", "Aporocera", "subgenus", "accepted", "MY_DATA", "Aporocera", "sg1", "sg1",
"Chrysomelidae Latreille", "Chrysomelidae", "family", "accepted", "MY_DATA", NA, "f1", "f1",
"Xylotoles Pascoe", "Xylotoles", "genus", "accepted", "MY_DATA", NA, "g2", "g2",
"Xylotoles costatus Pascoe, 1859", "Xylotoles costatus", "species", "accepted", "MY_DATA", "Xylotoles", "sp4", "sp4",
"Xylotoles costatus mixtus Someone, 1920", "Xylotoles costatus mixtus", "subspecies", "accepted", "MY_DATA", "Xylotoles", "sp5", "sp5"
)
check_taxonomic_reference(my_reference)check_taxonomic_reference() confirms the table is in the
format (it errors, listing every problem, if it isn’t) – worth running
on any reference you’re going to share.
You can pass a table like this straight to the matching functions,
but for repeated use it’s worth preparing it once with
prepare_taxonomic_resources(), which the matching functions
otherwise do themselves on every call:
resources <- prepare_taxonomic_resources(my_reference)
names(resources)
#> [1] "species" "genus" "subgenus" "subgenus_v2" "family"prepare_taxonomic_resources() splits the combined table
into a nested list – one element per taxonomic rank present (here:
species, genus, subgenus,
family), with species further split into
accepted/synonym sub-tables. This is the shape
every other function in the package works on.
Note that my_reference above gives an explicit
"genus"-rank row for both "Aporocera" and
"Xylotoles" – but you don’t actually have to. Naming a
genus in the genus column of a species row is enough on its
own: prepare_taxonomic_resources() automatically adds a
genus-rank row for any genus (or any other rank you record in its own
column, e.g. family) that’s implied this way but doesn’t
yet have an explicit row of its own, so "Xylotoles sp. 1"
would still align to genus rank even if the "Xylotoles" row
above were deleted. Synthesised rows get a placeholder ID
(taxonomic_dataset_taxon_rank_canonical_name,
e.g. "MY_DATA_genus_Xylotoles") since there’s no natural ID
to reuse.
If your table’s columns have other names,
taxonAlign.dataprep::build_taxonomic_reference() walks you
through mapping them onto the format (in the style of
traits.build’s metadata_add_traits()).
Combining several references
prepare_taxonomic_resources() (and the matching
functions) also accept a list of tables, combining them with a priority
order: when the same name appears in more than one table, whichever
table is listed first wins, whatever taxonomic status each
gives it (within one table, the most reliable status wins). This is how
you’d combine released lists with your own data:
# your own list first, then the AFD, then GBIF for anything neither of those has
resources <- prepare_taxonomic_resources(c(
list(mine = my_reference),
load_taxonomic_resources(c("NSL_animals", "CatalogueOfLife_AU"))
))Matching raw names: align_taxa()
align_taxa() takes one or more raw taxon names and
matches each against resources, trying (in order) exact
matches, then progressively more lenient fuzzy matches, at species level
first and then at each higher rank present in
resources.
align_taxa("Aporocera viridipennis", resources) # exact match, a synonym
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera viridipennis NA Aporocera vi… Aporocera v… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>
align_taxa("Aporocera viridipenis", resources) # one letter missing -- fuzzy match
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera viridipenis NA Aporocera vir… Aporocera v… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>
align_taxa("Xylotoles costatus mixtus", resources) # a subspecies
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Xylotoles costatus mix… NA Xylotoles c… Xylotoles c… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>
align_taxa("Chrysomelidae", resources) # family only
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Chrysomelidae NA Chrysomelidae Chrysomelidae sp. [C… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>A subgenus can be written into a name or left out; either way matches, whichever way your reference writes it:
align_taxa(c("Aporocera t-viride", "Aporocera (Aporocera) t-viride"), resources) |>
select(original_name, aligned_name, taxon_rank)
#> # A tibble: 2 × 3
#> original_name aligned_name taxon_rank
#> <chr> <chr> <chr>
#> 1 Aporocera t-viride Aporocera t-viride species
#> 2 Aporocera (Aporocera) t-viride Aporocera t-viride speciesA name that can’t be resolved to anything is left NA,
not an error:
align_taxa("Completely unrelated nonsense", resources)
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Completely unrelated n… NA Completely … NA NA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>Matching more than one name at once
align_taxa() is vectorised – pass as many names as you
like in one call, spanning as many different ranks as your raw data
actually has:
align_taxa(
c("Aporocera t-viride", "Aporocera viridipenis", "Xylotoles costatus mixtus", "Chrysomelidae", "Xylotoles sp. 1"),
resources
) |>
select(original_name, aligned_name, taxon_rank)
#> # A tibble: 5 × 3
#> original_name aligned_name taxon_rank
#> <chr> <chr> <chr>
#> 1 Aporocera t-viride Aporocera t-viride species
#> 2 Aporocera viridipenis Aporocera viridipennis species
#> 3 Xylotoles costatus mixtus Xylotoles costatus mixtus subspecies
#> 4 Chrysomelidae Chrysomelidae sp. [Chrysomelidae] family
#> 5 Xylotoles sp. 1 Xylotoles sp. [Xylotoles sp. 1] genusIn practice your names usually live in a column of a data frame, not a bare vector – just pass that column straight in:
field_data <- tibble(
name = c("Aporocera t-viride", "Chalcolampra viridis", "Xylotoles sp. 1", "Totally unknown beetle"),
site = c("Site A", "Site B", "Site C", "Site B")
)
align_taxa(field_data$name, resources) |>
select(original_name, aligned_name, taxon_rank, taxonomic_status)
#> # A tibble: 4 × 4
#> original_name aligned_name taxon_rank taxonomic_status
#> <chr> <chr> <chr> <chr>
#> 1 Aporocera t-viride Aporocera t-viride species accepted
#> 2 Chalcolampra viridis Chalcolampra viridis species synonym
#> 3 Xylotoles sp. 1 Xylotoles sp. [Xylotoles s… genus accepted
#> 4 Totally unknown beetle NA NA NATwo opt-in parameters handle names that structurally can’t specify a species at all, resolving them to genus rank instead of leaving them to (possibly mis-)match a species-level pattern:
align_taxa("Aporocera x hybridname", resources, hybrids = TRUE)
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera x hybridname NA Aporocera x … Aporocera x… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>
align_taxa("Aporocera aff. viridipennis", resources, intergrades_affinis = TRUE)
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera aff. viridip… NA Aporocera a… Aporocera s… MY_DATA
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>hybrids catches Genus x species-style
hybrid names; intergrades_affinis catches intergrades
(--), a collector’s indecision between two taxa
(/), and graded/uncertain identifications
(aff./cf.). Both default to
FALSE.
A third opt-in parameter, consider_english_name_endings,
recognises an informal vernacular ending
(e.g. "Coccinellid" for family Coccinellidae,
"Curculionoid" for superfamily Curculionoidea) and tries an
exact match on the formal Latin equivalent before falling back to fuzzy
matching – useful for the kind of morphospecies/voucher code that names
a broader group this way rather than a genus:
align_taxa("Chrysomelid sp. 1", resources, consider_english_name_endings = TRUE) |>
select(original_name, aligned_name, taxon_rank)
#> # A tibble: 1 × 3
#> original_name aligned_name taxon_rank
#> <chr> <chr> <chr>
#> 1 Chrysomelid sp. 1 Chrysomelidae sp. [Chrysomelid sp. 1] familyFor a large list, progress = TRUE prints a text progress
bar tracking how many names have been resolved so far.
Every result also includes chars_changed – how many
characters differed between the name and whatever it matched:
0 for an exact match, the actual edit distance for a fuzzy
one, NA if nothing matched:
align_taxa("Aporocera viridipenis", resources) |> # one letter missing
select(original_name, aligned_name, chars_changed)
#> # A tibble: 1 × 3
#> original_name aligned_name chars_changed
#> <chr> <chr> <int>
#> 1 Aporocera viridipenis Aporocera viridipennis 1Resolving to current names: update_taxa()
align_taxa() tells you what a name matched –
update_taxa() takes that result and resolves it forward to
whatever the current accepted name is, following synonym links
via accepted_name_usage_ID. This works the same way
regardless of rank – a species-level synonym and a higher-rank one both
resolve via the same lookup:
aligned <- align_taxa(c("Chalcolampra viridis", "Xylotoles sp. 1"), resources)
update_taxa(aligned, resources) |>
select(original_name, aligned_name, accepted_name, taxonomic_status)
#> # A tibble: 2 × 4
#> original_name aligned_name accepted_name taxonomic_status
#> <chr> <chr> <chr> <chr>
#> 1 Chalcolampra viridis Chalcolampra viridis Aporocera t-… accepted
#> 2 Xylotoles sp. 1 Xylotoles sp. [Xylotoles … Xylotoles acceptedaccepted_name is the current accepted name
(NA if it couldn’t be resolved);
suggested_name falls back to aligned_name when
there’s no accepted_name, so it’s never NA for
anything that matched at all.
A synonym of more than one taxon
Sometimes a name is listed as a synonym of two or more accepted taxa
– for example, when a species has since been split into several. The
name alone can’t say which is meant. Following APCalign’s convention,
update_taxa() suggests the most likely one (by the
synonyms’ taxonomic status, then a few tie-breaking rules) and lists the
others in brackets, and in alternative_possible_names:
split_reference <- tibble::tribble(
~canonical_name, ~scientific_name, ~taxon_rank, ~taxonomic_status, ~genus, ~taxon_ID, ~accepted_name_usage_ID,
"Newgenus alba", "Newgenus alba (Smith, 1900)", "species", "accepted", "Newgenus", "a1", "a1",
"Newgenus pallida", "Newgenus pallida Jones, 1950", "species", "accepted", "Newgenus", "a2", "a2",
"Oldgenus alba", "Oldgenus alba Smith, 1900", "species", "nomenclatural synonym", "Oldgenus", "s1", "a1",
"Oldgenus alba", "Oldgenus alba Smith, 1900", "species", "misapplied", "Oldgenus", "s2", "a2"
) |>
mutate(taxonomic_dataset = "EXAMPLE")
create_taxonomic_update_lookup("Oldgenus alba", prepare_taxonomic_resources(split_reference)) |>
select(original_name, suggested_name, alternative_possible_names)
#> Summary of 1 names:
#> -> 1 aligned to a species or infraspecific taxon (1 in EXAMPLE)
#> -> 0 aligned only to a genus and 0 only to a family
#> -> 0 could not be aligned
#> -> 0 aligned names were updated to a different name (e.g. a synonym to its accepted name, or an outdated genus to the current one)
#> -> 1 names could refer to more than one currently accepted taxon. With `taxonomic_splits = "most_likely_species"`, `suggested_name` gives the most likely species and lists the alternatives in square brackets.
#> # A tibble: 1 × 3
#> original_name suggested_name alternative_possible…¹
#> <chr> <chr> <chr>
#> 1 Oldgenus alba Newgenus alba [alternative possible name… Newgenus pallida (mis…
#> # ℹ abbreviated name: ¹alternative_possible_namesWith taxonomic_splits = "collapse_to_higher_taxon", a
name whose candidates all share a genus is reported at genus rank
instead ("Newgenus sp. [collapsed names: ...]").
The one-call pipeline:
create_taxonomic_update_lookup()
Most of the time you want both steps together.
create_taxonomic_update_lookup() runs
align_taxa() then update_taxa() in one
call:
create_taxonomic_update_lookup(
c("Aporocera viridipennis", "Aporocera viridipenis", "Chalcolampra viridis", "Xylotoles costatus mixtus", "Chrysomelidae"),
resources
) |>
select(original_name, aligned_name, accepted_name, taxonomic_status, update_reason)
#> Summary of 5 names:
#> -> 4 aligned to a species or infraspecific taxon (4 in MY_DATA)
#> -> 0 aligned only to a genus and 1 only to a family
#> -> 0 could not be aligned
#> -> 3 aligned names were updated to a different name (e.g. a synonym to its accepted name, or an outdated genus to the current one)
#> # A tibble: 5 × 5
#> original_name aligned_name accepted_name taxonomic_status update_reason
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera viridipen… Aporocera v… Aporocera t-… accepted Updated to t…
#> 2 Aporocera viridipen… Aporocera v… Aporocera t-… accepted Updated to t…
#> 3 Chalcolampra viridis Chalcolampr… Aporocera t-… accepted Updated to t…
#> 4 Xylotoles costatus … Xylotoles c… Xylotoles co… accepted Aligned name…
#> 5 Chrysomelidae Chrysomelid… Chrysomelidae accepted Updated to t…Putting it together: updating a list of names
Here’s the workflow you’d actually run on a real list of raw names – say, taxon names recorded in a field dataset that need reconciling against a reference before analysis, spanning several ranks and including a couple of names nothing will match.
field_data <- tibble(
original_name = c(
"Aporocera viridipennis", # a synonym
"Aporocera viridipenis", # typo
"Xylotoles costatus mixtus", # a subspecies
"Chrysomelidae", # family only
"Aporocera sp. 1", # morphospecies code -- genus known, species not
"Totally unknown beetle" # won't resolve to anything
),
site = c("Site A", "Site B", "Site A", "Site C", "Site B", "Site B")
)
lookup <- create_taxonomic_update_lookup(field_data$original_name, resources, identifier = field_data$site)
#> Summary of 6 names:
#> -> 3 aligned to a species or infraspecific taxon (3 in MY_DATA)
#> -> 1 aligned only to a genus and 1 only to a family
#> -> 1 could not be aligned
#> -> 2 aligned names were updated to a different name (e.g. a synonym to its accepted name, or an outdated genus to the current one)
lookup |> select(original_name, identifier, suggested_name, taxonomic_status, update_reason)
#> # A tibble: 6 × 5
#> original_name identifier suggested_name taxonomic_status update_reason
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera viridipenn… Site A Aporocera t-v… accepted Updated to t…
#> 2 Aporocera viridipenis Site B Aporocera t-v… accepted Updated to t…
#> 3 Xylotoles costatus m… Site A Xylotoles cos… accepted Aligned name…
#> 4 Chrysomelidae Site C Chrysomelidae… accepted Updated to t…
#> 5 Aporocera sp. 1 Site B Aporocera sp.… accepted Updated to t…
#> 6 Totally unknown beet… Site B NA unknown NAidentifier (here, site) is threaded through
so that a name only ever resolvable to genus rank (like the
morphospecies code above) is disambiguated per dataset/location in its
aligned name, rather than collapsing two genuinely different
unidentified morphospecies from different sites into one.
Join the lookup back onto your original data by
original_name to get an updated name for every row:
field_data |> left_join(lookup, by = "original_name")
#> # A tibble: 6 × 21
#> original_name site aligned_name accepted_name suggested_name genus taxon_rank
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Aporocera vi… Site… Aporocera v… Aporocera t-… Aporocera t-v… Apor… species
#> 2 Aporocera vi… Site… Aporocera v… Aporocera t-… Aporocera t-v… Apor… species
#> 3 Xylotoles co… Site… Xylotoles c… Xylotoles co… Xylotoles cos… Xylo… subspecies
#> 4 Chrysomelidae Site… Chrysomelid… Chrysomelidae Chrysomelidae… NA family
#> 5 Aporocera sp… Site… Aporocera s… Aporocera Aporocera sp.… NA genus
#> 6 Totally unkn… Site… NA NA NA NA NA
#> # ℹ 14 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
#> # scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
#> # number_of_collapsed_taxa <int>, taxon_ID <chr>, taxon_ID_genus <chr>,
#> # scientific_name_ID <chr>, family <chr>, taxonomic_status_aligned <chr>,
#> # alternative_possible_names <chr>, chars_changed <int>, identifier <chr>From here, the rows worth a closer look are the ones where
taxonomic_status is "unknown" (nothing matched
at all) or suggested_name is NA – everything
else resolved to something, even if only at a higher rank.
Reviewing exactly those rows (rather than the whole list) is usually the
fastest way to find the handful of names that need a manual look – a
real typo not caught by fuzzy matching, a name missing from your
reference entirely, or a genuinely new/undescribed taxon.
lookup |> filter(is.na(suggested_name) | taxonomic_status == "unknown")
#> # A tibble: 1 × 20
#> original_name aligned_name accepted_name suggested_name genus taxon_rank
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Totally unknown be… NA NA NA NA NA
#> # ℹ 14 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
#> # scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
#> # number_of_collapsed_taxa <int>, taxon_ID <chr>, taxon_ID_genus <chr>,
#> # scientific_name_ID <chr>, family <chr>, taxonomic_status_aligned <chr>,
#> # alternative_possible_names <chr>, chars_changed <int>, identifier <chr>