## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

## ----setup--------------------------------------------------------------------
library(TaxResolveR)

## ----example-names------------------------------------------------------------
scientific_names <- c(
  "Homo sapiens",
  "  Parastacus brasiliensis  ",
  "Chilina sp.",
  "",
  NA_character_
)

scientific_names

## ----cleaning-----------------------------------------------------------------
clean_scientific_names(scientific_names)

## ----parsing------------------------------------------------------------------
parse_scientific_names(scientific_names)

## ----classification-----------------------------------------------------------
classify_scientific_names(scientific_names)

## ----validation---------------------------------------------------------------
validate_species_names(scientific_names)

## ----standardisation----------------------------------------------------------
standardize_scientific_names(scientific_names)

## ----query-preparation--------------------------------------------------------
prepare_taxonomic_queries(scientific_names)

## ----resolution-example, eval=FALSE-------------------------------------------
# resolved <- resolve_taxonomy(
#   c("Homo sapiens", "Homo sapens", "Chilina sp."),
#   source = "gbif"
# )

## ----taxresolve-example, eval=FALSE-------------------------------------------
# results <- taxresolve(
#   c(
#     "Homo sapiens",
#     "Homo sapens",
#     "Chilina sp.",
#     "Parastacus brasiliensis"
#   ),
#   source = "gbif"
# )

## ----offline-resolution-------------------------------------------------------
resolved_example <- data.frame(
  source = rep("gbif", 7),
  query_name = c(
    "Homo sapiens",
    "Homo sapens",
    "Chilina",
    "Parastacus brasiliensis",
    NA_character_,
    NA_character_,
    "Xyzabc nonexistenttaxon"
  ),
  matched_name = c(
    "Homo sapiens",
    "Homo sapiens",
    "Chilina",
    "Parastacus brasiliensis",
    NA_character_, NA_character_, NA_character_
  ),
  accepted_name = c(
    "Homo sapiens",
    "Homo sapiens",
    "Chilina",
    "Parastacus brasiliensis",
    NA_character_, NA_character_, NA_character_
  ),
  taxonomic_status = c(
    "ACCEPTED", "ACCEPTED", "ACCEPTED", "ACCEPTED",
    NA_character_, NA_character_, NA_character_
  ),
  rank = c(
    "SPECIES", "SPECIES", "GENUS", "SPECIES",
    NA_character_, NA_character_, NA_character_
  ),
  kingdom = rep(NA_character_, 7),
  phylum = rep(NA_character_, 7),
  class = rep(NA_character_, 7),
  order = rep(NA_character_, 7),
  family = rep(NA_character_, 7),
  genus = rep(NA_character_, 7),
  taxon_id = c(
    2436436, 2436436, 3243720, 2224027,
    NA_real_, NA_real_, NA_real_
  ),
  match_type = c(
    "EXACT", "VARIANT", "EXACT", "EXACT",
    NA_character_, NA_character_, NA_character_
  ),
  match_confidence = c(
    99, 95, 94, 99, NA_real_, NA_real_, NA_real_
  ),
  resolution_success = c(
    TRUE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE
  ),
  stringsAsFactors = FALSE
)

resolved_example[c(
  "query_name",
  "matched_name",
  "rank",
  "match_type",
  "match_confidence",
  "resolution_success"
)]

## ----assessment---------------------------------------------------------------
assessed_example <- assess_taxonomic_match(resolved_example)

assessed_example[c(
  "query_name",
  "resolution_status",
  "match_quality",
  "accepted_status"
)]

## ----review-------------------------------------------------------------------
reviewed_example <- flag_taxonomic_review(assessed_example)

reviewed_example[c(
  "query_name",
  "resolution_status",
  "match_quality",
  "review_required",
  "review_reason"
)]

## ----summary------------------------------------------------------------------
summary_example <- summarize_taxonomic_resolution(reviewed_example)
summary_example

## ----report-------------------------------------------------------------------
report_example <- taxonomic_resolution_report(reviewed_example)

report_example$total_summary
report_example$resolution_status
report_example$match_quality
report_example$review_reasons

## ----export-example, eval=FALSE-----------------------------------------------
# export_taxonomic_results(
#   reviewed_example,
#   path = "taxonomic_results"
# )

## ----help-example, eval=FALSE-------------------------------------------------
# ?taxresolve
# ?resolve_taxonomy
# ?assess_taxonomic_match
# ?flag_taxonomic_review
# ?taxonomic_resolution_report