soilKey ships an interactive Shiny app that drives the
whole pipeline from a browser – no R code required. It is meant for
agronomists, students and field workers who want to classify a profile,
inspect the deterministic key trace, and download a report without
scripting.
Launching the app
library(soilKey)
# The professional multi-tab app (default).
run_classify_app()
# Equivalent, explicit:
run_classify_app(ui = "pro")
# The original single-page CSV uploader (v0.9.39 layout):
run_classify_app(ui = "classic")The pro interface needs the optional packages
bslib, shinyWidgets and
plotly in addition to shiny and
DT. If any are missing, run_classify_app()
stops with a copy-pasteable install.packages() line. The
classic interface needs only shiny and
DT.
install.packages(c("shiny", "DT", "bslib", "shinyWidgets", "plotly"))The eight tabs
Pedon
Seed a profile three ways:
- Fixture – pick one of the 44 canonical profiles (31 WRB reference soil groups + 13 SiBCS ordens). These are the same fixtures the test suite uses, so they are guaranteed to classify cleanly.
-
Upload CSV – one row per horizon. Columns are
matched against the canonical horizon schema; unknown columns are kept,
missing ones are filled with
NA. A starter CSV is available from the sidebar. - Blank – start from an empty template and build the profile by hand.
Every horizon cell is editable in place – click a cell, type, press Enter. The depth-profile plot on the right updates live; switch the plotted attribute with the dropdown. When the table looks right, fill in the site metadata (ID, latitude, longitude, country, parent material) and press Build / update pedon.
Classify
Runs WRB 2022, SiBCS 5 and USDA Soil Taxonomy 13 side-by-side. Each result card shows the full classification name, the bare RSG / order, the principal and supplementary qualifiers, and the provenance-aware evidence grade.
The Decision detail panel exposes:
- Key trace – every RSG tested, in key order, with pass / fail / indeterminate status. Failed and passed rows are colour-coded.
- Ambiguities – RSGs that nearly satisfied; useful hints for follow-up measurement.
- Missing data – attributes whose measurement would refine or resolve the result.
Photo
Drives the vision-language extraction pipeline. A profile photograph
yields Munsell colour per horizon; a field-sheet image yields site
metadata. The taxonomic key is never delegated to a
model – extraction only fills the PedonRecord.
The default Demo (mock) provider returns a canned, schema-valid response so the pipeline runs offline with no API key. To use a live model, configure an ellmer chat object before launching:
options(soilKey.vlm_chat = ellmer::chat_anthropic())
run_classify_app()Spectra
Attach a Vis-NIR spectrum (one row per horizon, one column per
wavelength) and gap-fill missing horizon attributes against the Open
Soil Spectral Library. Filled values enter the provenance ledger tagged
predicted_spectra. The first gap-fill downloads an OSSL
cache, which needs network access.
Spatial
Queries a SoilGrids “MostProbable WRB” raster around the profile coordinates and reports the spatial distribution of reference soil groups – a prior to sanity-check the deterministic classification against. Point the Raster path or URL field at a SoilGrids GeoTIFF, or set a local raster for demos:
options(soilKey.test_raster = "/path/to/a/wrb_raster.tif")Uncertainty
A Monte-Carlo robustness analysis: each run perturbs texture, pH and organic carbon within typical analytical error, then re-classifies. The robustness percentage tells you how often the class holds; the bar chart shows which alternative classes the profile flipped to. (From v0.9.100 this tab upgrades to a provenance-weighted posterior distribution.)