Package {wcvpmatch}

wcvpmatch: Taxonomic Name Reconciliation Against the 'WCVP' Backbone

Description

Standardizes and reconciles scientific plant names against a World Checklist of Vascular Plants ('WCVP')-style taxonomic backbone. The package parses names into taxonomic components and applies staged exact and fuzzy matching for binomial and trinomial inputs, including infraspecific rank-aware checks. It also returns accepted-name context and row-level matching flags to support reproducible, auditable preprocessing for downstream biodiversity, spatial, and trait analyses. A user-supplied backbone can be passed through 'target_df'; when the optional companion package 'wcvpdata' is installed, its default checklist can also be used.

Author(s)

Maintainer: Paul Efren Santos Andrade paulefrens@gmail.com [copyright holder]

Authors:

• Paul Efren Santos Andrade paulefrens@gmail.com [copyright holder]

See Also

Useful links:

• https://paulesantos.github.io/wcvpmatch/

• https://github.com/PaulESantos/wcvpmatch

• Report bugs at https://github.com/PaulESantos/wcvpmatch/issues

Build a Genus Index for Fast Prefiltering

Description

Creates a compact genus-level index from the target backbone. The index stores one row per genus and a list-column with candidate plant_name_id values associated with each genus.

If plant_name_id is not present in target_df, a surrogate integer ID is created to keep the index usable with custom backbones.

Usage

build_genus_index(target_df = NULL)

Arguments

Value

A tibble with columns:

genus

Genus name (character).

plant_name_id

List-column of unique IDs per genus.

n_records

Number of IDs per genus.

genus_nchar

Number of characters in the genus name.

Examples

target <- data.frame(genus = "Opuntia", species = "ficus-indica", plant_name_id = 1)
wcvpmatch:::build_genus_index(target)

Classify Scientific Plant Names into Taxonomic Components

Description

Parse and classify scientific plant names into taxonomic components: genus, specific epithet, infraspecific rank, infraspecific epithet, and author.

Output is aligned to a backbone convention:

• Orig.Genus in Title Case (first letter uppercase, rest lowercase).

• Orig.Species and Orig.Infraspecies epithets in lowercase.

• Infra.Rank in lowercase (subsp., var., subvar., f., subf.).

• Author is recovered from the input and preserved in its original casing/punctuation (no forced uppercasing).

• Orig.Name is reconstructed as: genus + species + (rank + infra) + author.

Robustness rules:

• cf. / aff. are removed from parsing but preserved as flags (has_cf, has_aff).

• Hybrid markers (x/⁠\u00D7⁠) as standalone tokens are removed with had_hybrid = TRUE.

• sp. / spp. triggers genus-only classification (Rank = 1, Orig.Species = NA) and sets is_sp/is_spp.

• If an infraspecific rank is present but the infraspecific epithet is missing, sets rank_missing_infra = TRUE and keeps Infra.Rank while Orig.Infraspecies = NA.

• If rank appears "late" (after author-like tokens), parsing is best-effort and rank_late = TRUE.

• If there is no explicit rank and a third token exists, the function can infer an unranked infraspecific epithet when the third token looks epithet-like (all lowercase), and does not look like the start of an author. In that case implied_infra = TRUE, Orig.Infraspecies is filled, Infra.Rank = NA, and Rank = 3.

Usage

classify_spnames(splist)

Arguments

Value

A tibble with one row per input name and standardized columns/flags:

sorter

Numeric index of original order.

Input.Name

Original input string as provided by user.

Orig.Name

Reconstructed standardized name aligned to backbone + original-cased author.

Orig.Genus

Genus in Title Case.

Orig.Species

Specific epithet in lowercase, or NA for genus-only (sp./spp.).

Author

Recovered author string (original casing/punctuation) or "".

Orig.Infraspecies

Infraspecific epithet in lowercase (ranked or implied), or NA.

Infra.Rank

Infraspecific rank in lowercase (subsp., var., subvar., f., subf.), or NA.

Rank

Numeric level: 1 genus-only, 2 genus+species, 3 includes infraspecific epithet.

has_cf,has_aff,is_sp,is_spp,had_hybrid,rank_late,rank_missing_infra,had_na_author,implied_infra

Logical flags.

Examples

library(wcvpmatch)
classify_spnames(c("Opuntia sp.", "Rosa canina subsp. coriifolia (Fr.) Leffler"))
classify_spnames(c("Cydonia japonica tricolor")) # implied unranked infra epithet

Direct Match Infraspecific Rank within Species

Description

Direct Match Infraspecific Rank within Species

Usage

direct_match_infra_rank_within_species(df, target_df = NULL)

Cleaned Master Tree Species List from FIA

Description

A cleaned dataset containing tree species recorded by the Forest Inventory and Analysis (FIA) program of the U.S. Forest Service. This dataset is used in the examples and README of the wcvpmatch package. The data was downloaded in November 2022 from the official webpage of the Forest Inventory and Analysis National Program, available at the following link, and was originally used during the development of the treemendous package. For wcvpmatch, the variable names have been standardized to Orig.Genus and Orig.Species.

Usage

fia

Format

A data frame with 2169 rows and 2 variables:

Orig.Genus

Genus name of the species binomial

Orig.Species

Specific epithet of the species binomial

Fuzzy Match Infraspecific Epithet within Species

Description

Fuzzy Match Infraspecific Epithet within Species

Usage

fuzzy_match_infraspecies_within_species(
  df,
  target_df = NULL,
  max_dist = 1,
  method = "osa"
)

Prefilter Target Backbone by Input Genera (Exact + Fuzzy)

Description

Reduces the target backbone to genera relevant for the current input names. This is designed as a pre-step before wcvp_matching() to reduce search space.

Strategy:

• Exact genus candidates are always included.

• Optional fuzzy genus candidates are included when include_fuzzy = TRUE.

• Returned object preserves the standard target schema used by the package.

Usage

prefilter_target_by_genus(
  df,
  target_df = NULL,
  genus_index = NULL,
  include_fuzzy = TRUE,
  max_dist = 1,
  method = "osa"
)

Arguments

Value

A prefiltered target_df tibble compatible with wcvp_matching(target_df = ...). Attributes:

candidate_genera

Character vector of selected genera.

exact_genera

Character vector of exact matched genera.

fuzzy_genera

Character vector of fuzzy matched genera.

Examples

df <- data.frame(Genus = "Opuntia", Species = "yanganucensis")
target <- data.frame(genus = "Opuntia", species = "yanganucensis", plant_name_id = 1)
wcvpmatch:::prefilter_target_by_genus(df, target_df = target)

Direct Match Species & Genus Binomial or Trinomial names

Description

Tries to directly match Genus + Species | Genus + Species + Rank + Infraspecies to ⁠WCVP data⁠.

Usage

wcvp_direct_match(df, target_df = NULL)

Arguments

Value

Returns a tibble with the additional logical column direct_match, indicating whether the binomial was successfully matched (TRUE) or not (FALSE). Returns original columns plus Matched.Genus, Matched.Species, Matched.Infra.Rank, and Matched.Infraspecies.

Examples

df_parsed <- classify_spnames("Opuntia yanganucensis")
target <- data.frame(genus = "Opuntia", species = "yanganucensis", plant_name_id = 1)
wcvpmatch:::wcvp_direct_match(df_parsed, target_df = target)

Direct Match Species within Genus

Description

Tries to directly match the specific epithet within an already matched genus in 'WCVP'.

Usage

wcvp_direct_match_species_within_genus(df, target_df = NULL)

Arguments

Value

Returns a tibble with the additional logical column direct_match_species_within_genus, indicating whether the specific epithet was successfully matched within the matched genus (TRUE) or not (FALSE).

Retrieve Tabular WCVP Distribution by Taxonomic Rank

Description

Usage

wcvp_distribution(
  taxon,
  taxon_rank = c("species", "genus", "family", "order", "higher"),
  native = TRUE,
  introduced = TRUE,
  extinct = TRUE,
  location_doubtful = TRUE,
  wcvp_names = NULL,
  wcvp_distributions = NULL,
  prefilter_genus = TRUE,
  fallback_to_genus = TRUE,
  summarise_by_input = FALSE,
  max_dist = NULL,
  method = "osa",
  output = c("standard", "full", "spatial", "summary")
)

Arguments

Details

Queries distribution records by matching a taxon name against the WCVP names table and then resolving the corresponding rows in the WCVP distribution table. The function is designed around wcvpdata::wcvp_matching_names() and wcvpdata::wcvp_distribution(), but custom tables with the same schema can also be supplied.

Matching is performed with fozziejoin, using compact lookup tables and length-based prefiltering to keep the candidate set small. Species queries are resolved in two stages: genus candidates are matched first, then species names are searched only within those candidate genera.

If species-level matches resolve to synonyms and the names table contains accepted_plant_name_id, distribution is recovered from the accepted taxon. For queries above species, accepted names are preferred to avoid double counting synonym records.

The result deliberately contains no geometry and does not require sf. area_code_l3 is the stable WGSrpd level-3 key intended for a later join to a user-supplied spatial object.

Default names and distribution tables are cached for the current R session. Exact species queries use a direct lookup; lowercase strings and species keys over the full backbone are only built when a fuzzy query needs them.

Value

A non-spatial tibble. The default output = "standard" returns one row per matched query-area combination with the submitted and resolved taxa, geographic hierarchy, and four occurrence flags (12 columns). output = "full" additionally returns matching provenance and identifiers. output = "spatial" returns only the taxon-area fields needed for a later spatial join. output = "summary" returns one row per input taxon with collapsed text fields such as distribution, areas, area_codes, regions, continents, and n_areas.

Examples

library(wcvpmatch)

wcvp_distribution("Opuntia ficus-indica", taxon_rank = "species")
wcvp_distribution("Opuntia", taxon_rank = "genus")
wcvp_distribution("Cactaceae", taxon_rank = "family")
# When `order` is present in a custom names table:
# \dontrun{wcvp_distribution("Caryophyllales", taxon_rank = "order", wcvp_names = custom_names)}

Fuzzy Match Genus Name

Description

Tries to fuzzy match the genus name to the 'WCVP' table (using the optional wcvpdata checklist by default when available).

Usage

wcvp_fuzzy_match_genus(df, target_df = NULL, max_dist = 1, method = "osa")

Arguments

Value

Returns a tibble with the additional logical column fuzzy_match_genus, indicating whether the genus was successfully matched (TRUE) or not (FALSE). Further, the additional column fuzzy_genus_dist returns the distance for every match.

Examples

df <- data.frame(Orig.Genus = "Opuntiaa", Orig.Species = "yanganucensis")
target <- data.frame(genus = "Opuntia", species = "yanganucensis", plant_name_id = 1)
wcvpmatch:::wcvp_fuzzy_match_genus(df, target_df = target)

Fuzzy Match Species within Genus

Description

Tries to fuzzy match the species epithet within a matched genus against 'WCVP' (using the optional wcvpdata checklist by default when available).

Usage

wcvp_fuzzy_match_species_within_genus(
  df,
  target_df = NULL,
  max_dist = 1,
  method = "osa"
)

Arguments

Value

Returns a tibble with the additional logical column fuzzy_match_species_within_genus, indicating whether the specific epithet was successfully fuzzy matched within the matched genus (TRUE) or not (FALSE).

Match Genus name

Description

Tries to match the genus name to the 'WCVP' table (using the optional wcvpdata checklist by default when available).

Usage

wcvp_genus_match(df, target_df = NULL)

Arguments

Value

Returns a tibble with the additional logical column genus_match, indicating whether the genus was successfully matched (TRUE) or not (FALSE).

Match Scientific Names Against WCVP

Description

Runs a matching pipeline with exact and partial matching for binomial and trinomial names, including infraspecific rank validation.

When the default WCVP backbone is used, its normalized representation and compact genus lookup are cached for the current R session. Prepared custom backbones are also recognized inside the pipeline so internal matching nodes do not normalize or deduplicate the same table repeatedly.

Usage

wcvp_matching(
  df,
  target_df = NULL,
  prefilter_genus = TRUE,
  allow_duplicates = FALSE,
  max_dist = 1,
  method = "osa",
  add_name_distance = FALSE,
  name_distance_method = "osa",
  profile = FALSE,
  output_name_style = c("snake_case", "legacy"),
  output = c("standard", "full")
)

Arguments

Value

A tibble with parsed input fields and matched/accepted taxonomic context. The standard output contains input_index, input and matched name components, authorship, matched and accepted IDs/names, status, and matched. Use output = "full" for matching diagnostics.

Examples

library(wcvpmatch)
# Match a single name
wcvp_matching(data.frame(Genus = "Opuntia", Species = "yanganucensis"))

# Match multiple names with snake_case output
names <- c("Aniba heterotepala", "Anthurium quipuscoae")
df <- classify_spnames(names)
wcvp_matching(df, output_name_style = "snake_case")

# Attach per-stage timings for profiling
out <- wcvp_matching(df, output_name_style = "snake_case", profile = TRUE)
attr(out, "timings")

Check Default Backbone Setup

Description

Usage

wcvp_setup_info(inform = TRUE)

Arguments

Details

Reports whether the optional companion package wcvpdata is available for use as the default WCVP backbone and, if not, explains how to install it from r-universe.

Value

Invisibly returns a named list with setup status fields: default_backbone_available, wcvpdata_installed, wcvpdata_has_backbone, wcvpdata_version, repository, and install_command.

Examples

library(wcvpmatch)
wcvp_setup_info()

Suffix Match Species within Genus

Description

Tries to match the specific epithet by exchanging common suffixes within an already matched genus in 'WCVP'. The following suffixes are captured: c("a", "i", "is", "um", "us", "ae").

Usage

wcvp_suffix_match_species_within_genus(df, target_df = NULL)

Arguments

Value

Returns a tibble with the additional logical column suffix_match_species_within_genus, indicating whether the specific epithet was successfully matched within the matched genus (TRUE) or not (FALSE).

Examples

df <- data.frame(Orig.Genus = "Opuntia", Orig.Species = "yanganucensa", Matched.Genus = "Opuntia")
target <- data.frame(genus = "Opuntia", species = "yanganucensis", plant_name_id = 1)
wcvpmatch:::wcvp_suffix_match_species_within_genus(df, target_df = target)

Retrieve Synonyms Resolved Through the WCVP Backbone

Description

Usage

wcvp_synonyms(
  taxon,
  target_df = NULL,
  prefilter_genus = TRUE,
  max_dist = 2,
  method = "osa",
  include_accepted = FALSE,
  output = c("compact", "full")
)

Arguments

Details

Resolves submitted species names with wcvp_matching() and retrieves every WCVP record with taxon_status = "Synonym" that points to the resolved accepted name. This means that an accepted name, a synonym, or a minor spelling variant can all be used as the query.

Exact submitted names use a direct lookup before invoking the fuzzy matching pipeline. The accepted-name lookup and normalized default backbone are cached for the current R session and shared with the other package functions.

Value

A tibble with one row per input name and retrieved synonym. The default compact result contains submitted_name, accepted_taxon_name, accepted_taxon_authors, name_role, synonym_name, synonym_authors, and homotypic_synonym. Inputs without a match or without recorded synonyms are retained with missing synonym fields.

Examples

wcvp_synonyms("Nopalea cochenillifera")