TaxResolveR

TaxResolveR provides reproducible tools for cleaning, validating, resolving, assessing, and documenting scientific names used in ecological and biodiversity datasets.

The package is designed around a simple workflow in which scientific names are prepared, resolved against a taxonomic source, evaluated for match quality, flagged when manual review is advisable, and summarised for reporting or export.

Installation

TaxResolveR is currently under development.

Once installed, the package can be loaded with:

library(TaxResolveR)

Installation instructions for the public release will be added when the package repository and release version are available.

Quick start

The main user-facing workflow is taxresolve(). It accepts a character vector of scientific names and returns the original taxonomic resolution information together with assessment and review fields.

names <- c(
  "Homo sapiens",
  "Homo sapens",
  "Chilina sp.",
  "Parastacus brasiliensis"
)

results <- taxresolve(
  names,
  source = "gbif"
)

results

Taxonomic resolution currently uses GBIF as the implemented external taxonomic source. Because this step queries an external service, results may depend on service availability and the taxonomy returned by the source at the time of the query.

Understanding the results

taxresolve() combines taxonomic resolution, match assessment, and review flagging in a single result.

Important output fields include:

• query_name: the name submitted for taxonomic resolution.
• matched_name: the name matched by the taxonomic source.
• accepted_name: the accepted taxonomic name returned by the source.
• taxonomic_status: taxonomic status returned by the source.
• rank: taxonomic rank of the match.
• match_type: type of taxonomic match.
• match_confidence: confidence information returned for the match.
• resolution_success: whether a taxonomic match was obtained.
• resolution_status: overall resolution category.
• match_quality: interpretation of match quality.
• accepted_status: interpretation of taxonomic acceptance.
• review_required: whether manual review is recommended.
• review_reason: reason why manual review is recommended.

This distinction is useful because a name may be technically resolved while still requiring review. For example, a non-exact or higher-rank match may be returned successfully but should not necessarily be treated as equivalent to an exact species-level match.

Summarising taxonomic resolution

A compact summary can be generated with:

summarize_taxonomic_resolution(results)

For a more detailed report containing counts and proportions by resolution status, match quality, and review reason, use:

report <- taxonomic_resolution_report(results)

report$total_summary
report$resolution_status
report$match_quality
report$review_reasons

Exporting results

Resolved results and their associated summaries can be exported with:

export_taxonomic_results(
  results,
  path = "taxonomic_results"
)

This creates five CSV files:

• taxonomic_results.csv
• taxonomic_summary.csv
• resolution_status.csv
• match_quality.csv
• review_reasons.csv

Existing managed output files are not overwritten by default. Use overwrite = TRUE only when replacement is intended.

Modular workflow

Users who require greater control can access the individual stages of the workflow directly.

Scientific-name preparation:

• clean_scientific_names()
• parse_scientific_names()
• classify_scientific_names()
• validate_species_names()
• standardize_scientific_names()
• prepare_taxonomic_queries()

Taxonomic resolution:

• resolve_taxonomy()

Assessment and review:

• assess_taxonomic_match()
• flag_taxonomic_review()

Summary, reporting, and export:

• summarize_taxonomic_resolution()
• taxonomic_resolution_report()
• export_taxonomic_results()

For most analyses, however, taxresolve() provides the simplest entry point to the complete resolution and review workflow.

Reproducibility

TaxResolveR separates taxonomic resolution from the interpretation of the resulting matches. This makes it possible to retain the information returned by the taxonomic source while explicitly documenting uncertain, non-exact, unresolved, or non-queryable records.

Users should retain exported results together with the source and date of taxonomic resolution when preparing reproducible biodiversity datasets or scientific analyses.

Documentation

Detailed workflow documentation is provided in the package vignette:

vignette("introduction", package = "TaxResolveR")

Individual function documentation is available through the standard R help system, for example:

?taxresolve
?resolve_taxonomy
?taxonomic_resolution_report