Honest taxonomic-completeness report — coverage

Measures, by NAME, exactly which canonical taxa/qualifiers the package's deterministic rule base registers, replacing hand-maintained coverage claims with an auditable, reproducible diff. For "usda_subgroup" the canonical reference is the Soil Taxonomy 13th-edition subgroup set from kst13_codes; for "wrb_qualifiers" it is the WRB 2022 principal + supplementary qualifier set from wrb2022_canonical.

Usage

coverage_report(
  system = c("usda_subgroup", "usda_great_group", "usda_suborder", "wrb_qualifiers",
    "wrb_horizons", "wrb_properties", "wrb_materials", "wrb_rsg", "sibcs"),
  write = FALSE,
  report_dir = NULL
)

Arguments

system: Which axis to measure. USDA taxon levels against the Soil Taxonomy 13th-edition code set (kst13_codes): "usda_subgroup" (default), "usda_great_group", "usda_suborder". WRB 2022 against wrb2022_canonical and the canonical diagnostic reference (inst/extdata/canonical/wrb2022_diagnostics.csv): "wrb_qualifiers", "wrb_horizons" (40 diagnostic horizons), "wrb_properties" (17 diagnostic properties), "wrb_materials" (19 diagnostic materials), and "wrb_rsg" (32 Reference Soil Groups, diffed against inst/rules/wrb2022/key.yaml). For the qualifier and diagnostic axes "covered" means the mapped function exists and is a genuine implementation (not an unconditional passed = NA stub); the inert ones are returned in $stubs. "sibcs" has no external canonical class list, so it honestly reports registered class counts per level only (no percentage).
write: If TRUE, also write a Markdown summary to report_dir. Default FALSE.
report_dir: Directory for the Markdown report when write = TRUE. Defaults to inst/benchmarks/reports inside the installed package.

Value

Invisibly, a list with $overall (one-row data frame: system, level, canonical_n, registered_n, covered_n, missing_n, pct), $by_group (per order, or per principal/supplementary), $missing (canonical names not registered), $extra (registered names absent from the canonical set), and – for "wrb_qualifiers" – $stubs (functions that exist but are inert). A compact summary is printed as a side effect.

Examples

# WRB diagnostic horizons are measured against soilKey's own table, offline.
cov <- coverage_report("wrb_horizons")
#> 
#> ── Coverage: wrb2022 horizon (diagnostic) ──
#> 
#> ℹ 40 / 40 canonical horizon (diagnostic)s registered (100.0%); 0 missing.
#>     group canonical_n covered_n missing_n pct
#>  horizons          40        40         0 100
cov$overall
#>    system                level canonical_n registered_n covered_n missing_n pct
#> 1 wrb2022 horizon (diagnostic)          40           40        40         0 100
# \donttest{
# The USDA axes read the KST 13th edition from ncss-tech/SoilKnowledgeBase,
# downloaded on first use, so they need a connection the first time.
# Needs network access; skipped offline and in batch checks.
online <- interactive() && requireNamespace("httr", quietly = TRUE) &&
  !inherits(try(httr::HEAD("https://raw.githubusercontent.com", httr::timeout(5)),
                silent = TRUE), "try-error")
if (online) {
  usda <- try(coverage_report("usda_subgroup"), silent = TRUE)
  if (!inherits(usda, "try-error")) head(usda$missing)
}
# }