Package {soilKey}

Type:	Package
Title:	Automated Soil Profile Classification per WRB 2022, 'SiBCS' 5 and USDA Soil Taxonomy 13
Version:	0.9.155
Date:	2026-06-21
Description:	Implements deterministic classification keys for the World Reference Base for Soil Resources 2022 (4th edition) and the Brazilian System of Soil Classification ('SiBCS', 5th edition). Provides a unified profile representation with explicit per-attribute provenance, multimodal extraction from field reports and photos via vision-language models, spatial priors from 'SoilGrids' and national soil maps, and gap-filling of soil attributes from Vis-NIR or MIR spectra via the Open Soil Spectral Library ('OSSL'). The taxonomic key itself is never delegated to a language model; LLMs are restricted to schema-validated extraction. Each classification result reports a key trace, a provenance-aware evidence grade, and ambiguities that further measurement would resolve.
License:	MIT + file LICENSE
URL:	https://github.com/HugoMachadoRodrigues/soilKey, https://hugomachadorodrigues.github.io/soilKey/
BugReports:	https://github.com/HugoMachadoRodrigues/soilKey/issues
Encoding:	UTF-8
LazyData:	true
LazyDataCompression:	xz
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1)
Imports:	R6, data.table, yaml, cli, rlang
Suggests:	aqp, SoilTaxonomy, mpspline2, terra, foreign, sf, chromote, munsellinterpol, pls, prospectr, resemble, ellmer, httr, jsonlite, jsonvalidate, pdftools, magick, shiny (≥ 1.7.0), DT, bslib, shinyWidgets, plotly, leaflet, htmltools, withr, DBI, RSQLite, testthat (≥ 3.0.0), knitr, rmarkdown
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-06-21 21:40:44 UTC; rodrigues.h
Author:	Hugo Rodrigues [aut, cre]
Maintainer:	Hugo Rodrigues <rodrigues.machado.hugo@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-22 06:50:02 UTC

soilKey: Automated Soil Profile Classification per WRB 2022 and SiBCS

Description

soilKey implements deterministic classification keys for the World Reference Base for Soil Resources 2022 (4th edition) and the Brazilian System of Soil Classification (SiBCS, 5th edition). It separates concerns strictly: the taxonomic key is a pure function of structured profile data, while optional modules provide vision-language extraction, spatial priors from SoilGrids, and gap-filling of soil attributes from Vis-NIR or MIR spectra via the Open Soil Spectral Library (OSSL).

Design principle

never delegate the key. Vision-language models are restricted to schema-validated extraction of soil attributes from unstructured sources (PDFs, photos, field sheets). The taxonomic key itself is always evaluated by deterministic R code driven by versioned YAML rules.

Core types

• PedonRecord — site, horizons, spectra, images, documents, and a per-attribute provenance log.

• DiagnosticResult — return type of every diagnostic function (e.g. argic, ferralic, mollic); always carries the sub-test evidence and missing-attribute report alongside the boolean.

• ClassificationResult — return type of classify_wrb2022; carries the full key trace, ambiguities, missing-data hints, and a provenance-aware evidence grade.

Provenance and evidence grade

Every attribute used by the key carries a provenance tag from c("measured", "extracted_vlm", "predicted_spectra", "inferred_prior", "user_assumed"). The final classification evidence grade is one of c("A", "B", "C", "D") where A is fully laboratory-measured and unambiguous and D is tentative or multimodal.

v0.1 scope

v0.1 implements three WRB 2022 horizon diagnostics — argic, ferralic, mollic — and the Ferralsols path of the WRB key end-to-end. The full 32-RSG key, 202 qualifiers, the SiBCS key, and the multimodal extraction, spatial-prior, and OSSL-spectroscopy modules are scheduled for subsequent releases. See ARCHITECTURE.md.

Author(s)

Maintainer: Hugo Rodrigues rodrigues.machado.hugo@gmail.com (ORCID)

References

IUSS Working Group WRB (2022). World Reference Base for Soil Resources, 4th edition. International Union of Soil Sciences, Vienna.

Embrapa (2018). Sistema Brasileiro de Classificação de Solos, 5ª edição. Embrapa Solos, Brasília.

Beaudette, D. E., Roudier, P., & O'Geen, A. T. (2013). Algorithms for Quantitative Pedology: A toolkit for soil scientists. Computers & Geosciences, 52, 258–268.

See Also

Useful links:

• https://github.com/HugoMachadoRodrigues/soilKey

• https://hugomachadorodrigues.github.io/soilKey/

• Report bugs at https://github.com/HugoMachadoRodrigues/soilKey/issues

Canonical mapping from BDsolos column-name variants to soilKey schema

Description

BDsolos exports use Portuguese column names with variable casing and diacritic handling. This table records the regex patterns that identify each soilKey horizon column. Patterns are matched case-insensitively, after stripping diacritics and the underscore between word fragments.

Usage

.BDSOLOS_COLUMN_PATTERNS

Format

An object of class list of length 41.

Site-level columns (BDsolos full export). Mapped at the site, not horizon, level.

Description

Site-level columns (BDsolos full export). Mapped at the site, not horizon, level.

Usage

.BDSOLOS_SITE_PATTERNS

Format

An object of class list of length 21.

Map FEBR layer-table columns to soilKey horizon attributes

Description

The FEBR camada (layer) table uses standardised variable codes documented in the FEBR data dictionary (see https://www.pedometria.org/febr/ for the project home; the dictionary path moved during 2024 – the codes themselves are stable). This internal table records the regex patterns that map the most useful FEBR codes onto the soilKey horizon schema. Multi-method codes (e.g.\ clay determined by hydrometer vs sieve) are collapsed onto the single soilKey column.

Usage

.FEBR_TO_HORIZON_MAP

Format

An object of class list of length 25.

Gleyic Munsell hue patterns (WRB 2022, Ch 3.1.13 redoximorphic features)

Description

Hues consistent with Fe reduction (gleyic / reductimorphic). Used by test_gleyic_features as a secondary evidence path when redoximorphic_features_pct is not reported (e.g. BDsolos perfis where the surveyor recorded Munsell colors but not mottle percent). Per WRB 2022 Ch 3.1.13: hues N (neutral), 10Y, 5GY, 10GY, 5G, 10G, 5BG, 10BG, 5B, 10B (any value, chroma <= 2 inferred).

Usage

.GLEYIC_HUE_REGEX

Format

An object of class character of length 1.

Package-level cache for the parsed KST 13ed JSON files

Description

v0.9.65 (Copilot review #5): kst13_criteria() previously parsed the full ~3.1 MB criteria JSON on every call. Looping over a few hundred codes was crippling. This cache loads each JSON once per session.

Usage

.KST13_CACHE

Format

An object of class environment of length 0.

Details

Kept in a private environment so package-internal code can reach the cached objects via .KST13_CACHE$<filename> but external callers must go through kst13_codes / kst13_criteria.

Embrapa Redape Dataverse API endpoint

Description

Embrapa Redape Dataverse API endpoint

Usage

.REDAPE_API_BASE

Format

An object of class character of length 1.

Default DOI for the Vaz et al. 2023 curated GeoTab dataset

Description

Default DOI for the Vaz et al. 2023 curated GeoTab dataset

Usage

.REDAPE_GEOTAB_DOI

Format

An object of class character of length 1.

Pre-2018 SiBCS Order names -> SiBCS 5a edicao plural Title Case map

Description

Internal lookup applied by normalise_febr_sibcs() when level = "order". BDsolos exports collected before the SiBCS 5a edicao (2018) carry historical Order names that the modern classifier does not emit.

Usage

.SIBCS_LEGACY_ORDER_MAP

Format

An object of class character of length 4.

Details

BDsolos exports collected before the SiBCS 5a edicao (2018) carry historical Order names that the modern classifier does not emit. The most common cases observed on RJ.csv (722 perfis):

• Podzolicos (54 perfis em RJ) -> Argissolos (post-2018 a Order Argissolos absorveu o Podzolico Vermelho- Amarelo, Podzolico Vermelho-Escuro, etc.)

• Gleis (44 perfis em RJ) -> Gleissolos (Gleis Humico, Gleis Pouco Humico colapsaram em Gleissolos)

• Aluviais (13 perfis em RJ) -> Neossolos (Solos Aluviais foram reclassificados para Neossolos Fluvicos no SiBCS 5a edicao, mas a normalisacao aqui emite apenas a Ordem moderna Neossolos – a Subordem Neossolos Fluvicos nao eh recuperavel do label legado antigo ALUVIAIS (a granularidade de Subordem se perde). Para benchmark Order-level isso e suficiente; para Subordem o legado nao se mapeia.)

• Solos -> NA ("Solos Halomorficos", "Solos Hidromorficos", e fragmentos de label do UI antigo do BDsolos onde a Ordem nao foi registrada). NA aqui significa "fora de scope para a comparacao".

Aplicado em normalise_febr_sibcs(level = "order") apos a pluralisacao normal. Para subordem o legacy mapping ainda nao e aplicado (ver TODO no v0.9.61: estender para Subordem com "Podzolico Vermelho-Amarelo" -> "Argissolos Vermelho-Amarelos").

SmartSolos drainage class scale (DRENAGEM, 1-8)

Description

SiBCS / Embrapa drainage scale used by the SmartSolosExpert API: 1 excessivamente drenado .. 8 muito mal drenado. soilKey does not have a canonical drainage column yet; user supplies via drenagem argument when known.

Usage

.SMARTSOLOS_DRAINAGE_SCALE

Format

An object of class integer of length 8.

Mapping of SoilGrids 250m property names to soilKey horizon columns

Description

SoilGrids stores nine soil properties at six standard depths; lookup_soilgrids returns them in conventional units after the published per-property scale factor. This table records the corresponding soilKey horizon column plus an optional secondary multiplier needed to align with soilKey unit conventions.

Usage

.SOILGRIDS_TO_HORIZON_MAP

Format

An object of class list of length 9.

Caches managed by the v0.9.94 lazy-fetch system

Description

Caches managed by the v0.9.94 lazy-fetch system

Usage

.SOILKEY_LAZY_FETCH_CACHES

Format

An object of class character of length 4.

Versioned GitHub Release tag where the lazy-fetch caches are pinned

Description

Versioned GitHub Release tag where the lazy-fetch caches are pinned

Usage

.SOILKEY_LAZY_FETCH_RELEASE

Format

An object of class character of length 1.

WRB Reference Soil Group code-to-name table

Description

The ESDB WRBLV1.tif raster encodes RSGs as 2-letter codes (e.g. "FL" for Fluvisols). classify_wrb2022 returns the English plural name (e.g. "Fluvisols"). This table maps between the two. Codes follow IUSS Working Group WRB (2022); the legacy "AB" (Albeluvisols, WRB 2006) is mapped to NA as it does not exist in WRB 2022.

Usage

.WRB_LV1_NAME_BY_CODE

Format

An object of class character of length 31.

Horizonte B espodico (SiBCS Cap 2, p 62-65; v0.7)

Description

Subsuperficial com acumulo iluvial de Al + Fe + materia organica; espessura \>= 2.5 cm. Tipos: Bs, Bhs, Bh, ortstein. Reuso de spodic (WRB) que ja codifica criterios essencialmente identicos.

Usage

B_espodico(pedon, ...)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Horizonte B incipiente (SiBCS Cap 2, p 59-61; v0.7)

Description

Subsuperficial sob A/Ap/AB com alteracao fisica e quimica incipiente, NAO satisfazendo a B textural / latossolico / nitico / espodico / planico, com:

• espessura \>= 10 cm;

• textura francoarenosa ou mais fina;

• < 50% estrutura da rocha original;

• evidencias de pedogenese (cor mais viva OR remocao de carbonatos OR designation Bw/Bi);

• NAO satisfaz: argic, ferralic, espodic, planic, e nao tem duripa/petrocalcico/fragipa.

Usage

B_incipiente(pedon, min_thickness = 10)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Horizonte B latossolico (SiBCS Cap 2, p 57-59; v0.7 strict)

Description

Adicionalmente a ferralic (WRB), o B latossolico SiBCS exige:

• Espessura minima de 50 cm;

• Textura francoarenosa ou mais fina;

• Estrutura granular muito pequena/pequena ou em blocos subangulares fraco/moderado;

• < 5% volume mostrando estrutura da rocha original;

• Ki \<= 2.2 (geralmente \<= 2.0);

• Cerosidade no maximo pouca e fraca.

v0.7 enforce thickness, texture, e ausencia de estrutura primaria herdada via designation e clay; Ki/Kr quantitativos sao v0.8 (precisa de SiO2/Al2O3 lab-data nao no schema).

Usage

B_latossolico(
  pedon,
  min_thickness = 50,
  max_cec_per_clay = NULL,
  engine = NULL,
  ...
)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Horizonte B nitico (SiBCS Cap 2, p 61-62; v0.7)

Description

Subsuperficial nao hidromorfico, textura argilosa/muito argilosa (clay \>= 35% desde a superficie), com pequeno incremento de argila (B/A \<= 1.5), estrutura em blocos sub/angulares ou prismatica grau moderado/forte, cerosidade no minimo comum + moderada, espessura \>= 30 cm. Argila ativ baixa OR ativ alta + carater aluminico.

Usage

B_nitico(
  pedon,
  min_thickness = 30,
  min_clay_pct = 35,
  max_b_a_ratio = 1.5,
  min_cerosidade = c("common", "many", "abundant", "strong")
)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Horizonte B planico (SiBCS Cap 2, p 65-66; v0.7)

Description

Tipo especial de B textural com mudanca textural abrupta + permeabilidade lenta + cores neutras/escurecidas + cromas baixos.

Usage

B_planico(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Horizonte B textural (SiBCS Cap 2, p 54-57; v0.7 strict)

Description

Horizonte mineral subsuperficial com incremento de argila + cerosidade OR aumento gradativo, satisfazendo criterios de espessura e relacao textural B/A. v0.7 enforce as alternativas (a)-(j) do SiBCS por delegacao parcial ao WRB argic (criterios de clay-increase essencialmente identicos) acrescidos de:

• espessura \>= 7.5 cm OR \>= 10% da soma das espessuras dos sobrejacentes; e

• textura \>= francoarenosa.

Refinamentos pendentes para v0.8: cerosidade obrigatoria sob certas estruturas (criterio i.1 / i.2 / i.3); lamelas \>= 15 cm combinadas.

Usage

B_textural(pedon, ...)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

ClassificationResult: structured outcome of running a key

Description

ClassificationResult: structured outcome of running a key

ClassificationResult: structured outcome of running a key

Details

Returned by classify_wrb2022 (and the future classify_sibcs). Carries the full decision trace — which RSGs were tested, which passed, which failed, which were indeterminate because of missing data — plus the assigned class, qualifiers, ambiguities (RSGs that nearly satisfied), missing data that would refine the result, the provenance-aware evidence grade, and any biogeographical or prior-based warnings.

Public fields

Methods

Public methods

• ClassificationResult$new()

• ClassificationResult$print()

• ClassificationResult$summary()

• ClassificationResult$report()

• ClassificationResult$clone()

Method new()

Build a ClassificationResult.

Usage

ClassificationResult$new(
  system,
  name,
  rsg_or_order = NA_character_,
  qualifiers = list(),
  trace = list(),
  ambiguities = list(),
  missing_data = character(0),
  evidence_grade = NA_character_,
  prior_check = NULL,
  warnings = character(0)
)

Arguments

Method print()

Pretty-print the result with key trace, ambiguities, and warnings.

Usage

ClassificationResult$print(...)

Arguments

Method summary()

Compact summary list.

Usage

ClassificationResult$summary(...)

Arguments

Method report()

Render this classification as a self-contained report (delegates to the package-level report generic). HTML output is dependency-free; PDF requires rmarkdown and a working LaTeX engine.

Usage

ClassificationResult$report(
  file,
  format = c("auto", "html", "pdf"),
  pedon = NULL,
  ...
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ClassificationResult$clone(deep = FALSE)

Arguments

DiagnosticResult: structured outcome of a diagnostic test

Description

DiagnosticResult: structured outcome of a diagnostic test

DiagnosticResult: structured outcome of a diagnostic test

Details

Returned by every WRB or SiBCS diagnostic function (e.g. argic, ferralic, mollic). A DiagnosticResult never reduces to a bare TRUE/FALSE — it always carries (a) which layers satisfied the criteria, (b) the per-sub-test evidence, (c) which attributes would have been required but are missing, and (d) the literature reference for the diagnostic definition.

passed is TRUE/FALSE/NA; NA means the test could not be evaluated because critical attributes were missing. This three-valued semantics propagates through the rule engine — an indeterminate test does not silently fail.

Public fields

Methods

Public methods

• DiagnosticResult$new()

• DiagnosticResult$print()

• DiagnosticResult$as_list()

• DiagnosticResult$clone()

Method new()

Build a DiagnosticResult.

Usage

DiagnosticResult$new(
  name,
  passed = NA,
  layers = integer(0),
  evidence = list(),
  missing = character(0),
  reference = NA_character_,
  notes = NA_character_
)

Arguments

Method print()

Pretty-print the result with sub-test breakdown.

Usage

DiagnosticResult$print(...)

Arguments

Method as_list()

Return the result as a plain list (for serialization).

Usage

DiagnosticResult$as_list()

Method clone()

The objects of this class are cloneable with this method.

Usage

DiagnosticResult$clone(deep = FALSE)

Arguments

Classe S4-like para atributos de Familia (5o nivel SiBCS)

Description

Classe S4-like para atributos de Familia (5o nivel SiBCS)

Classe S4-like para atributos de Familia (5o nivel SiBCS)

Details

Estrutura categorica (em vez de booleana) que representa um adjetivo composto da Familia. value eh o adjetivo atribuido (string) ou NULL quando a dimensao nao se aplica ou nao foi possivel determinar.

Public fields

Methods

Public methods

• FamilyAttribute$new()

• FamilyAttribute$print()

• FamilyAttribute$clone()

Method new()

Build a FamilyAttribute.

Usage

FamilyAttribute$new(
  name,
  value = NULL,
  evidence = list(),
  missing = character(0),
  reference = ""
)

Arguments

Method print()

Pretty-print the attribute.

Usage

FamilyAttribute$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

FamilyAttribute$clone(deep = FALSE)

Arguments

Default GlobalSoilMap depth intervals (cm)

Description

GSM standard per Arrouays et al. (2014) "GlobalSoilMap: Toward a fine-resolution global grid of soil properties". Boundaries: 0-5, 5-15, 15-30, 30-60, 60-100, 100-200 cm.

Usage

GSM_DEPTHS

Format

An object of class numeric of length 7.

Mock VLM provider for testing

Description

Mock VLM provider for testing

Mock VLM provider for testing

Details

A stand-in for an ellmer chat object. Exposes the same $chat(prompt, ...) method, but instead of calling a model it pops the next response from a pre-loaded queue. Designed for testthat unit tests that exercise extraction logic without API keys or network access.

Each call to $chat() returns the next element of the responses list. If the call number matches validation_error_at, that response is replaced with a deliberately malformed JSON string, allowing tests to exercise the retry-on-validation-failure path implemented in validate_or_retry.

Example

good_json <- '{"horizons": [...]}'
mock <- MockVLMProvider$new(responses = list(good_json))
result <- mock$chat("any prompt")  # returns good_json

# Simulate one validation error before success.
mock <- MockVLMProvider$new(
  responses = list("not really json", good_json),
  validation_error_at = NULL  # already invalid as-is
)

# Or force an attempt to be invalid via the helper.
mock <- MockVLMProvider$new(
  responses = list(good_json, good_json),
  validation_error_at = 1L
)

Inspection

After use, the mock exposes $call_count (integer) and $prompts_received (list of every prompt passed to $chat()), which lets tests assert that retry prompts include the previous validation error.

Public fields

Methods

Public methods

• MockVLMProvider$new()

• MockVLMProvider$chat()

• MockVLMProvider$reset()

• MockVLMProvider$clone()

Method new()

Construct a mock provider.

Usage

MockVLMProvider$new(responses = list(), validation_error_at = NULL)

Arguments

Method chat()

Send a prompt; returns the next queued response.

Usage

MockVLMProvider$chat(prompt, ...)

Arguments

Returns

Character scalar with the response text.

Method reset()

Reset the mock (call count and prompt log).

Usage

MockVLMProvider$reset()

Method clone()

The objects of this class are cloneable with this method.

Usage

MockVLMProvider$clone(deep = FALSE)

Arguments

PedonRecord: structured representation of a single pedon

Description

PedonRecord: structured representation of a single pedon

PedonRecord: structured representation of a single pedon

Details

The central data carrier in soilKey. A PedonRecord bundles everything we know about one soil profile: site metadata, the horizons table (with a fixed canonical schema — see horizon_column_spec), optional Vis-NIR/MIR spectra, profile photographs, source documents, and a provenance log that records, per (horizon, attribute) pair, where each value came from (measured, extracted_vlm, predicted_spectra, inferred_prior, user_assumed).

All diagnostic functions (argic, ferralic, mollic, ...) consume a PedonRecord directly. The provenance log is what allows the final ClassificationResult to assign a meaningful evidence grade.

Value

An R6 object of class PedonRecord.

Public fields

Methods

Public methods

• PedonRecord$new()

• PedonRecord$validate()

• PedonRecord$to_aqp()

• PedonRecord$from_aqp()

• PedonRecord$add_measurement()

• PedonRecord$summary()

• PedonRecord$print()

• PedonRecord$clone()

Method new()

Construct a PedonRecord.

Usage

PedonRecord$new(
  site = NULL,
  horizons = NULL,
  spectra = NULL,
  images = NULL,
  documents = NULL,
  provenance = NULL
)

Arguments

Method validate()

Validate the record against soil-physical sanity rules.

Checks: top < bottom for every horizon; no overlapping depths; clay+silt+sand sum to 100 ± 2 where all three are reported; pH values plausible (1..12); CEC >= sum of exchangeable bases (Ca, Mg, K, Na); Munsell value/chroma in plausible ranges; coarse fragments percent in [0, 100]; OC geographic ranges. Returns a list with valid, errors, warnings, n_horizons.

Usage

PedonRecord$validate(strict = FALSE, verbose = TRUE)

Arguments

Returns

Invisibly, a list summarising the validation outcome.

Method to_aqp()

Coerce to an aqp SoilProfileCollection.

Usage

PedonRecord$to_aqp()

Returns

A SoilProfileCollection. Requires the aqp package.

Method from_aqp()

Populate this record from an aqp SoilProfileCollection.

Usage

PedonRecord$from_aqp(spc, top_col = "top_cm", bottom_col = "bottom_cm")

Arguments

Returns

Invisibly self (mutated in place).

Method add_measurement()

Add a measurement (or extracted/predicted value) and record its provenance.

Usage

PedonRecord$add_measurement(
  horizon_idx,
  attribute,
  value,
  source = "measured",
  confidence = 1,
  notes = NA_character_,
  overwrite = FALSE
)

Arguments

Returns

Invisibly self.

Method summary()

Compact summary list (for serialization or testing).

Usage

PedonRecord$summary(...)

Arguments

Method print()

Pretty-print the record.

Usage

PedonRecord$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

PedonRecord$clone(deep = FALSE)

Arguments

Examples

# The canonical fixtures return ready-built PedonRecords:
pedon <- make_ferralsol_canonical()
pedon$site$id
nrow(pedon$horizons)

Abrupt textural difference (WRB 2022 Ch 3.2.1)

Description

Sharp clay-content increase between two superimposed mineral layers meeting all of:

• underlying clay \>= 15% AND thickness \>= 7.5 cm;

• underlying starts \>= 10 cm below mineral soil surface;

• underlying has, vs overlying: 2x clay if overlying < 20%, OR \>= 20pp (absolute) more clay if overlying \>= 20%;

• transitional layer, if any, \<= 2 cm.

v0.3.3 enforces criteria 1, 2, 3. The transitional-layer check is deferred (the canonical horizon schema does not carry a "transitional" marker; it can be added later via boundary_distinctness inspection).

Usage

abrupt_textural_difference(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Acrisol RSG diagnostic (WRB 2022)

Description

Tests whether a profile satisfies the Acrisol RSG criteria: an argic horizon with low-activity clay (CEC < 24 cmol_c/kg clay) AND low base saturation (BS < 50%) within at least one argic layer.

Usage

acrisol(pedon, max_cec = 24, max_bs = 50)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Acrisols.

Aeolic material (WRB 2022 Ch 3.3.1)

Description

Wind-deposited material in the upper 20 cm: rounded matt-surfaced sand grains OR aeroturbation features, AND < 1% SOC in the upper 10 cm. v0.3.3 detects via rock_origin == "aeolian" OR layer_origin == "aeolic".

Usage

aeolic_material(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Albeluvic glossae (WRB 2022 Ch 3.2.2)

Description

Tongues of bleached, coarser-textured material penetrating an argic horizon. v0.3.3 detects via designation pattern glossic|albeluvic on a layer that overlies an argic-horizon-passing layer.

Usage

albeluvic_glossae(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Albic horizon (WRB 2022)

Description

A bleached eluvial horizon – claric material that has lost iron oxides and/or organic matter due to clay migration, podzolization, or redox under stagnant water. Diagnostic for parts of Podzols, Retisols and Planosols qualifiers.

Usage

albic(pedon, min_thickness = 1)

Arguments

Details

Sub-tests:

• test_claric_munsell – Munsell criteria of claric material (Ch 3.3.4).

Designation pattern E or Eg also serves as positive evidence when Munsell columns are missing (proxy path).

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Ch 3.1 – Albic horizon.

Alisol RSG diagnostic (WRB 2022)

Description

argic + CEC >= 24 cmol_c/kg clay + Al saturation >= 50%.

Usage

alisol(pedon, min_cec = 24, min_al_sat = 50)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Alisols.

Andic properties (WRB 2022)

Description

Tests for the andic property complex – volcanic-ash-derived allophanic / imogolitic / Al-humus material. Diagnostic of Andosols. Two alternative qualifying paths per WRB 2022 Ch 3.2:

1. Al-Fe oxalate + low BD: (Al_ox + 0.5*Fe_ox) >= min_alfe (default 2.0%) AND bulk_density <= max_bd (default 0.9 g/cm^3) on the same layer.

2. Phosphate retention: phosphate_retention_pct >= min_p_retention (default 70%).

Either path qualifies. The volcanic-glass criterion is the separate vitric_properties diagnostic; Andosols key on (andic OR vitric) at the RSG-gate level (andosol).

Usage

andic_properties(
  pedon,
  min_alfe = 2,
  max_bd = 0.9,
  min_p_retention = 70,
  min_oc_proxy = 4,
  max_bd_proxy = 0.9
)

Arguments

Value

A DiagnosticResult.

v0.9.80 OC + BD proxy (opt-in)

Field-described volcanic-ash soils (e.g.\ AfSP, KSSL/NASIS, SOTER) routinely lack oxalate Al/Fe and phosphate retention measurements, so the canonical paths return NA and Andosols cascade to other RSGs. The genetic signature is still detectable from coarser data: very high SOC (>= 4-5%) plus low bulk density (<= 0.9 g/cm^3) typical of allophanic / Al-humus complexation.

With options(soilKey.andic_oc_bd_proxy = TRUE) the function adds a third path that fires when both canonical paths fail and the surface horizon shows oc_pct >= min_oc_proxy AND bulk_density_g_cm3 <= max_bd_proxy (or OC alone >= 5% when BD is missing). Default is FALSE (canonical behaviour preserved).

v0.9.85 proxy contiguous-layer extension (opt-in)

When options(soilKey.andic_oc_bd_proxy_extend = TRUE) (only meaningful with soilKey.andic_oc_bd_proxy = TRUE), iteratively extend the proxy layers to include contiguous deeper layers whose oc_pct >= min_oc_proxy / 2 AND whose bulk_density_g_cm3 is missing OR <= max_bd_proxy + 0.15. The extension stops at the first horizon failing either constraint, so a ferralic / argic subsoil cannot accidentally inflate the andic thickness. Default is FALSE – canonical proxy behaviour preserved.

References

IUSS Working Group WRB (2022), Chapter 3, Andic properties.

Andosol RSG gate (WRB 2022 Ch 4, p 104)

Description

WRB-canonical: layer(s) with andic OR vitric properties, combined thickness \>= 30 cm within 100 cm starting \<= 25 cm; OR \>= 60% of the entire soil thickness when a limiting layer starts 25-50 cm. Plus: no argic, ferralic, petroplinthic, pisoplinthic, plinthic or spodic horizon \<= 100 cm (unless buried below 50 cm).

Usage

andosol(
  pedon,
  min_thickness = 30,
  max_top_cm = 25,
  buried_below_cm = 50,
  strict = NULL
)

Arguments

Details

v0.3.4 enforces (1) andic OR vitric AND (2) combined thickness \>= 30 cm starting in the upper 25 cm AND (3) the negative-list exclusions on argic / ferralic / plinthic / spodic.

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

v0.9.85 buried-exclusion fix

WRB 2022 Ch 4 p 104 specifies the Andosol exclusion list (argic / ferralic / petroplinthic / pisoplinthic / plinthic / spodic) as "<= 100 cm unless buried below 50 cm". The earlier implementation excluded an Andosol whenever any of those diagnostics passed anywhere in the profile, including on layers starting deeper than 50 cm – which mis-fires on AfSP Andosol references like CM W3_0047, where an argic layer at 56-72 cm wrongly excluded the andic surface stack. v0.9.85 restricts the exclusion check to layers starting <= 50 cm: a buried argic / ferralic / plinthic / spodic at deeper levels no longer disqualifies the surface andic stack from Andosol.

Tier-3 strict mode (v0.9.98)

With strict = TRUE the v0.9.85 buried-exclusion tolerance is switched off: any argic / ferralic / plinthic / spodic horizon anywhere in the profile excludes the Andosol, regardless of depth.

Annotate KSSL/NASIS pedons with a derived WRB Reference Soil Group

Description

Applies usda_to_wrb_rsg to each pedon's USDA classification (preserved as site$reference_usda + site$reference_usda_suborder by load_kssl_pedons_gpkg) and writes the result to site$reference_wrb_from_usda – a "best-guess" expected WRB label for benchmark comparison.

Usage

annotate_wrb_from_usda(pedons)

Arguments

Details

Pedons that already have site$reference_wrb populated (e.g.\ from external sources) are left untouched.

Value

The same list, with site$reference_wrb_from_usda populated where USDA classification is present.

Anthraquic horizon (WRB 2022): puddled-rice / paddy plough layer. v0.3.3 detects via designation pattern Apl|Ap|Hh.

Description

Anthraquic horizon (WRB 2022): puddled-rice / paddy plough layer. v0.3.3 detects via designation pattern Apl|Ap|Hh.

Usage

anthraquic(pedon, min_thickness = 20, max_top_cm = 50)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Anthric horizons (WRB 2022)

Description

Tests for any of five anthropogenic surface horizons recognised by WRB 2022 (hortic, irragric, plaggic, pretic, terric). Diagnostic of Anthrosols. Two alternative paths qualify:

1. Designation: any layer's designation contains one of hortic|irragric|plaggic|pretic|terric.

2. Property-based: a surface layer (top_cm <= 5) at least min_thickness_cm cm thick (default 20) with elevated dark colour (Munsell value moist <= max_munsell_value, default 4) AND elevated plant-available P (p_mehlich3_mg_kg >= min_p_mg_kg, default 50).

Either path qualifies.

Usage

anthric_horizons(
  pedon,
  min_thickness_cm = 20,
  min_p_mg_kg = 50,
  max_munsell_value = 4
)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Anthrosols.

Fill missing horizon attributes from a SoilGrids depth prior

Description

For each horizon and each requested attribute, interpolates the value at the horizon's mid-depth from the six standard SoilGrids 2.0 depth slices (0-5, 5-15, 15-30, 30-60, 60-100, 100-200 cm) and writes it into the pedon with source = "inferred_prior". Existing values are preserved unless overwrite = TRUE; the PedonRecord authority order means a SoilGrids prior can never silently displace a measured, spectra-predicted or VLM-extracted value.

Usage

apply_soilgrids_depth_prior(
  pedon,
  attrs = NULL,
  depth_profiles = NULL,
  overwrite = FALSE
)

Arguments

Details

This is the depth-resolved companion to spatial_prior_soilgrids (which returns a site-level RSG probability vector, not horizon attributes), and the attribute-fill stage of classify_from_photos.

Value

Invisibly, the mutated pedon. An attribute "soilgrids_depth_fill" on the return value records how many cells were filled.

Examples

## Not run: 
p <- make_cambisol_canonical()
p$horizons$clay_pct <- NA_real_
# Offline: supply the six-slice profiles directly.
apply_soilgrids_depth_prior(
  p, attrs = "clay_pct",
  depth_profiles = list(clay_pct = c(18, 20, 24, 28, 30, 30)))

## End(Not run)

Arenic texture (WRB 2022)

Description

Tests whether the upper 100 cm is uniformly coarser than sandy loam (i.e., silt + 2 * clay < 30 in every layer). Diagnostic of Arenosols.

Usage

arenic_texture(pedon, max_top_cm = 100, engine = NULL)

Arguments

Details

Sub-test: test_coarse_texture_throughout.

v0.3 limitations: WRB 2022 Arenosol also requires that no other diagnostic horizon (argic, ferralic, etc.) is present, but those exclusions happen at the key level via canonical RSG order.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Arenosols.

Argic horizon (WRB 2022)

Description

Tests whether any horizon meets the argic horizon criteria per Chapter 3 of the WRB 2022 (4th edition). Argic is a subsurface horizon with distinctly higher clay content than the overlying horizon, qualified by three depth-conditional clay-increase rules; it must also have texture of sandy loam or finer, satisfy a minimum thickness, and not exhibit albeluvic glossic features (which would direct the profile to the Retisol path).

Usage

argic(
  pedon,
  min_thickness = 7.5,
  system = c("wrb2022", "usda"),
  engine = NULL,
  require_t = NULL
)

Arguments

Details

Sub-tests called (each a list with passed, layers, missing, details, notes):

• test_clay_increase_argic – the three-pronged WRB 2022 clay-increase rule.

• test_minimum_thickness – thickness >= 7.5 cm (configurable via min_thickness).

• test_texture_argic – texture of sandy loam or finer (silt + 2 * clay >= 30).

• test_not_albeluvic – excludes profiles with glossic tongues (Retisol path).

v0.1 limitations: clay-increase distance (<= 30 cm vertical, or <= 15 cm with abrupt textural change) is not yet enforced; that is scheduled for v0.2 and depends on horizon boundary descriptions.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022). World Reference Base for Soil Resources, 4th edition. International Union of Soil Sciences, Vienna. Chapter 3 – Argic horizon.

Argic / argillic horizon via aqp::getArgillicBounds()

Description

Wraps aqp::getArgillicBounds() (Beaudette et al.) in soilKey's DiagnosticResult contract. The aqp implementation is the canonical NRCS R port and uses the tiered USDA-NRCS clay-increase thresholds:

• Eluvial clay < 15\

• Eluvial clay 15-40\

• Eluvial clay \>= 40\

(vs. soilKey's hand-coded argic which uses the WRB 6/1.4/20 thresholds). For BDsolos / FEBR / KSSL profiles the aqp rule is closer to KST 13ed and BDsolos field practice.

Usage

argic_aqp(pedon, require_t = FALSE, ...)

Arguments

Details

By default aqp requires a "t" suffix in the horizon designation (require_t = TRUE); we expose this so callers can be permissive on datasets where designation is missing or non-conforming (BDsolos exports often drop the "t").

Value

A DiagnosticResult with name = "argic_aqp". $layers are the row indices of horizons in the argillic / argic depth interval. $evidence carries the raw aqp c(ubound, lbound) bounds for traceability.

See Also

argic (soilKey hand-coded; WRB 6/1.4/20), aqp::getArgillicBounds.

Test whether a pedon's argic horizon has strong clay films

Description

Wraps argic() and inspects the clay_films_amount field at the argic-passing layers. Returns a structured result that B_latossolico() uses to decide whether the SiBCS Cap 18 strong-films exclusion fires.

Usage

argic_with_strong_clay_films(pedon)

Arguments

Value

A list with:

• passed – logical, TRUE only when argic passes AND at least one argic-passing layer has a strong (comum / abundante) film qualifier.

• layers – integer vector of argic-passing layer indices (empty when passed is FALSE).

• argic – the underlying DiagnosticResult from argic().

• films – character vector of the clay_films_amount values at the argic-passing layers.

Test for clay-illuviation evidence (KST 13ed Ch 3 p 4)

Description

KST 13ed argillic horizon requires "evidence of illuvial accumulation of clay" alongside the clay-increase rule. Acceptable evidence:

• oriented clays bridging sand grains in >= 1% of the horizon;

• clay films lining pores or coating ped faces;

• lamellae more than 5 mm thick.

Usage

argillic_clay_films_test(pedon)

Arguments

Details

This test reads three complementary slots, in order of evidence strength:

1. pedon$site$nasis_diagnostic_features – the NASIS pediagfeatures.featkind vector. The surveyor's explicit "Argillic horizon" entry directly confirms clay-illuviation evidence (~13 500 entries in the 2021 NASIS snapshot). Strongest evidence.

2. pedon$horizons$clay_films_amount – per-horizon clay-film abundance derived from NASIS phpvsf. Values: "few", "common", "many", "continuous". Direct measurement.

3. pedon$horizons$designation containing a 't' master suffix (e.g. Bt, Btk, Btx, Bt1, 2Bt). v0.9.28: the pedologist who wrote that designation explicitly identified the horizon as clay-illuvial – per KST 13ed Ch 18, the 't' suffix means "accumulation of silicate clay" – so it counts as positive evidence even when NASIS records are absent. This unlocks the KST 13ed argillic thresholds for the ~47 pediagfeatures and phpvsf records.

Any of the three sources counts as positive evidence (logical OR). passed = NA when none is populated AND no horizon designation field is present at all (lab-only loaders without horizon descriptions). passed = FALSE when designations exist but none has a 't' suffix and NASIS slots are empty.

Value

A DiagnosticResult.

References

Soil Survey Staff (2022), Keys to Soil Taxonomy 13th ed., Ch. 3, argillic horizon (clay-illuviation criteria, p. 4); Ch. 18, master horizon symbols (t: silicate-clay accumulation, p. 332).

Artefacts (WRB 2022 Ch 3.3.2)

Description

Per the canonical definition: human-made / human-altered / human- excavated material. v0.3.3 returns the layers where artefacts_pct >= 1.

Usage

artefacts(pedon, min_pct = 1)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Convert one or more PedonRecord objects to an aqp SoilProfileCollection

Description

Builds a aqp::SoilProfileCollection from one PedonRecord or a list of them. Standard soilKey columns (top_cm, bottom_cm, designation, clay_pct, sand_pct, silt_pct) are renamed to aqp's canonical convention (top, bottom, name, clay, sand, silt). All other columns are passed through unchanged. Site-level slots (lat, lon, country, parent_material, reference_*, nasis_diagnostic_features, etc.) are attached to the SPC's site table.

Usage

as_aqp(x)

Arguments

Details

Requires the aqp package, listed in Suggests; the function raises a clear error if aqp is not installed.

Value

A aqp::SoilProfileCollection.

See Also

from_aqp, the inverse conversion.

Examples

## Not run: 
library(soilKey)
library(aqp)

pedons <- list(make_ferralsol_canonical(), make_luvisol_canonical())
spc <- as_aqp(pedons)
length(spc)         # 2 profiles
aqp::horizons(spc)  # one row per horizon, aqp-named columns

## End(Not run)

Attach LUCAS 2018 Vis-NIR spectra to a list of PedonRecord objects

Description

Joins the LUCAS Soil 2018 Spectral Library (separate ESDAC release, ~83 GB) onto the pedons returned by load_lucas_soil_2018, by matching the LUCAS POINT_ID of the spectra against pedon$site$id. Each matched pedon gets $spectra$vnir populated as a numeric matrix (rows = horizons, cols = wavelengths).

Usage

attach_lucas_spectra(
  pedons,
  spectra,
  point_id_col = "POINT_ID",
  verbose = TRUE
)

Arguments

Details

Two input shapes are accepted:

• A wide data.frame keyed by an integer POINT_ID column with one column per wavelength (column names parseable as numeric nm). One row per LUCAS point.

• A long data.frame with columns POINT_ID, wavelength_nm, reflectance.

Spectra are attached only to the topsoil horizon (row 1); the subsoil horizon (if any) is left without spectra. After this call, benchmark_lucas_2018(..., fill_topsoil_from = "spectra", ossl_models = ...) feeds the spectra through predict_from_spectra (v0.9.46) to fill any chemistry / texture gap not already populated by SoilGrids.

Value

The list of pedons (mutated in place; returned invisibly).

See Also

predict_from_spectra, predict_munsell_from_spectra, load_lucas_soil_2018.

Audit the strong-clay-films exclusion across a list of pedons

Description

Applies argic_with_strong_clay_films() to every pedon in pedons and returns a per-pedon table summarising how the v0.9.61 B_latossolico() latossolic-vs-argic rule resolves on the benchmark sample.

Usage

audit_argic_strong_films(pedons, reference_filter = NULL)

Arguments

Details

Useful for empirical validation of the SiBCS Cap 18 precedence rule on field-described datasets such as BDsolos and Redape, where clay-film qualifiers are recorded in mixed Portuguese / English tokenisation. The audit is read-only and never invokes classify_sibcs().

Value

A data.frame with columns id, reference_sibcs, argic_passed, has_films_at_argic, strong_films_at_argic, and would_exclude_from_latossolo.

Examples

## Not run: 
peds <- load_bdsolos_csv("RJ.csv")
a <- audit_argic_strong_films(peds, reference_filter = "LATOSSOLO")
table(a$would_exclude_from_latossolo)

## End(Not run)

Auto-detect PROJ_LIB and GDAL_DATA directories

Description

Probes the common system locations for PROJ proj.db and GDAL data directories, on macOS Homebrew (Apple silicon and Intel), Linuxbrew, conda / mamba environments, and Debian / Ubuntu / Fedora apt or dnf installs. Sets the corresponding environment variables only when they are not already set, so a user-provided value always wins. Idempotent: safe to call repeatedly.

Usage

auto_set_proj_env(verbose = FALSE)

Arguments

Details

Called automatically from .onLoad; call manually after installing PROJ / GDAL via Homebrew if you want to refresh the env without restarting R.

Value

Invisibly, a named list with PROJ_LIB and GDAL_DATA (the values that were set, or NA_character_ if a value was already present or no candidate was found).

List ESDB Raster Library attributes available at a given root

Description

Walks 'raster_root' and returns the folder names that contain a valid '<NAME>.tif' raster. Useful for discovery before calling lookup_esdb.

Usage

available_esdb_attributes(raster_root)

Arguments

Value

A character vector of attribute names (sorted).

Examples

## Not run: 
available_esdb_attributes("~/data/ESDB-Raster-Library-1k-GeoTIFF-20240507")
#> [1] "AGLI1NNI" "AGLI2NNI" "AGLIM1" "AGLIM2" "ALT" "ATC" "AWC_SUB" ...
#>     [continued: 71 attributes]

## End(Not run)

Batch robustness across many pedons

Description

Runs classification_robustness on each pedon in a list and returns a tidy data.frame with one row per pedon. Useful for paper-grade claims like "85 to a 5

Usage

batch_robustness(pedons, ...)

Arguments

Value

A data.frame with columns id, baseline, robustness, n_flipped.

Examples

## Not run: 
pedons <- list(make_ferralsol_canonical(),
                 make_luvisol_canonical(),
                 make_chernozem_canonical())
batch_robustness(pedons, system = "wrb2022", n = 50)
#>            id   baseline robustness n_flipped
#> 1 FR-canon-01 Ferralsols       0.96         2
#> 2 LV-canon-01   Luvisols       1.00         0
#> 3 CH-canon-01 Chernozems       0.94         3

## End(Not run)

Benchmark soilKey WRB predictions against AfSP ground truth

Description

Benchmark soilKey WRB predictions against AfSP ground truth

Usage

benchmark_afsp(pedons, verbose = TRUE)

Arguments

Value

List with accuracy, n_compared, confusion, per_class_recall.

Benchmark soilKey classifiers against BDsolos national reference labels

Description

Runs classify_wrb2022, classify_sibcs, and classify_usda on each PedonRecord loaded from a BDsolos CSV via load_bdsolos_csv, then compares each predicted classification against the corresponding BDsolos reference label (reference_sibcs, reference_wrb, reference_st) and reports per-system accuracy, per-class recall, and a confusion matrix.

Usage

benchmark_bdsolos(
  pedons,
  systems = c("wrb2022", "sibcs", "usda"),
  sibcs_level = c("order", "subordem"),
  max_n = NULL,
  verbose = TRUE
)

Arguments

Value

A list with elements:

• per_system – named list (one entry per requested system) of list(accuracy, n_compared, n_correct, n_errors, confusion, per_class) (or list(accuracy = NA_real_, message) when no reference labels were present).

• coverage – named list of list(n_with_ref, n_total, pct) per system.

• config – named list capturing n_pedons, systems, sibcs_level, soilKey_version, timestamp.

Reference label coverage

BDsolos densely populates reference_sibcs (~82 of the v0.9.59 audit) but sparsely populates reference_wrb and reference_st (UF-dependent; ~5 states). The function always reports the per-system label coverage ($coverage) so the caller can judge how representative each accuracy figure is.

Comparison level

SiBCS comparison is at level = "order" by default, which converts the BDsolos all-caps Portuguese label (e.g. "ARGISSOLO VERMELHO Tb EUTROFICO ...") to the soilKey plural Title Case form ("Argissolos") via normalise_febr_sibcs. Set sibcs_level = "subordem" to compare the first two SiBCS tokens (Ordem + Subordem).

WRB and USDA comparisons are at the Reference Soil Group / Order level: normalise_febr_wrb() strips qualifier parens and pluralises the bare RSG ("Xanthic Ferralsol" -> "Ferralsols"); normalise_febr_usda() maps the suffix of the last subgroup token to the USDA Order ("Typic Haplorthox" -> "Oxisols").

Errors and missing-label handling

Pedons without a reference label for a given system are silently excluded from THAT system's comparison (but still classified for the other two systems). If a system has zero pedons with a reference label, the corresponding $per_system entry has accuracy = NA_real_ and message = "no_reference_labels". Classifier errors are caught per-pedon and recorded in n_errors; they do not abort the run.

See Also

load_bdsolos_csv, benchmark_lucas_2018, classify_all, normalise_febr_sibcs, normalise_febr_wrb, normalise_febr_usda.

Examples

## Not run: 
# Single UF -- typical SiBCS-dense slice
peds <- load_bdsolos_csv("RJ.csv")
bench <- benchmark_bdsolos(peds, systems = c("sibcs", "wrb2022", "usda"))
bench$coverage      # how many pedons had each reference label
bench$per_system$sibcs$accuracy
bench$per_system$sibcs$confusion

# Subordem level
bench2 <- benchmark_bdsolos(peds, systems = "sibcs",
                               sibcs_level = "subordem")

## End(Not run)

Run the LUCAS Soil 2018 / ESDB WRB benchmark

Description

For each pedon in pedons, attaches the canonical Reference Soil Group at its coordinate via lookup_esdb, runs classify_wrb2022 (or classify_sibcs), and tabulates predicted vs reference. Optionally fills missing texture from ISRIC SoilGrids 250m before classifying so that WRB diagnostic horizons that depend on clay (argic, ferralic, nitic) are reachable.

Usage

benchmark_lucas_2018(
  pedons,
  esdb_root,
  attribute = "WRBLV1",
  fill_texture_from = NULL,
  fill_topsoil_from = c("none", "soilgrids", "spectra"),
  fill_subsoil_from = c("none", "soilgrids"),
  fill_properties = c("clay", "sand", "silt", "phh2o", "soc", "cec", "bdod", "nitrogen",
    "cfvo"),
  ossl_models = NULL,
  classify_with = c("wrb2022", "sibcs"),
  max_n = NULL,
  soilgrids_lookup_fn = lookup_soilgrids,
  verbose = TRUE
)

Arguments

Details

This closes Route B of the v0.9.27 EU-LUCAS roadmap end-to-end: v0.9.44 lookup_esdb provides the reference label; v0.9.49 (this) provides the loader and the comparison loop; v0.9.48 lookup_soilgrids fills texture; v0.9.46 predict_from_spectra and v0.9.47 predict_munsell_from_spectra can fill the chemistry / Munsell gaps when Vis-NIR is available.

Value

A list with elements:

predictions

data.frame with one row per pedon: point_id, lon, lat, country, predicted, reference_code, reference_name, agree.

confusion

Confusion table (predicted vs reference) over in-scope rows.

accuracy

Overall fraction of correct classifications among in-scope rows.

per_rsg

Per-RSG recall data.frame.

n_in_scope

Number of pedons with both predicted and reference set.

n_total

Total pedons benchmarked.

n_errors

Number of pedons where the classifier errored out.

errors

List of (i, id, error) tuples for classifier errors.

config

Recap of arguments used.

See Also

load_lucas_soil_2018, lookup_esdb, lookup_soilgrids.

Examples

## Not run: 
pedons <- load_lucas_soil_2018(
  "soil_data/eu_lucas/LUCAS-SOIL-2018-data-report-readme-v2/LUCAS-SOIL-2018-v2",
  countries = c("ES"), max_n = 50)
bench <- benchmark_lucas_2018(
  pedons,
  esdb_root = "soil_data/eu_lucas/ESDB-Raster-Library-1k-GeoTIFF-20240507",
  fill_texture_from = "soilgrids")
bench$accuracy
bench$per_rsg

## End(Not run)

Run the soilKey performance benchmark

Description

Generates n synthetic pedons (5 horizons each, with the chemistry / morphology populated for typical Argissolo / Latossolo / Cambissolo cases), calls each classifier on each pedon, and reports per-call latency + total throughput.

Usage

benchmark_performance(
  n = 100L,
  systems = c("wrb2022", "sibcs", "usda"),
  include_familia = FALSE,
  seed = 42L,
  verbose = TRUE
)

Arguments

Details

Designed to be a one-shot reproducible benchmark: the synthetic pedons use a fixed RNG seed so timings on the same machine are comparable across releases.

Value

A list with elements:

summary

data.frame: system, n_pedons, total_seconds, mean_seconds, median_seconds, pedons_per_minute.

per_pedon

data.frame with one row per (pedon, system) call: i, system, seconds, status.

config

list with n, seed, soilKey_version, R_version, platform.

Examples

## Not run: 
bench <- benchmark_performance(n = 100)
bench$summary
#>     system n_pedons total_seconds mean_seconds median_seconds pedons_per_minute
#> 1 wrb2022      100        ~ 5-12      0.05-0.12      ~          ~
#> 2   sibcs      100        ~ 5-15      0.05-0.15      ~          ~
#> 3    usda      100        ~ 4-10      0.04-0.10      ~          ~

## End(Not run)

Benchmark soilKey SiBCS predictions against the Redape gold standard

Description

Runs classify_sibcs on each pedon and compares against the curator-validated reference label (Order / Suborder / Great Group / Subgroup). Returns per-level accuracy and the confusion matrix at the requested granularity.

Usage

benchmark_redape(
  pedons,
  level = c("order", "subordem", "gde_grupo", "subgrupo"),
  verbose = TRUE
)

Arguments

Value

A list with accuracy, n_compared, confusion, per_class_recall, and the per-pedon predictions table. predictions now also includes columns ref_norm and pred_norm – the canonical comparison keys – for downstream auditing.

v0.9.81 level-aware comparison

Earlier versions accepted the level argument but always used rsg_or_order for the prediction and the order field for the reference, so all four levels reported identical accuracy. v0.9.81 reads the level-specific slots from res$trace (subordem, grande_grupo, subgrupo) and concatenates the matching reference fields, applying SiBCS-aware Portuguese pluralisation so the comparison key matches the predictor's plural Title Case form.

Run a benchmark across one of the loaded pedon lists

Description

Classifies each pedon in pedons against the named system, compares against the published reference (e.g. site$reference_wrb), and returns a confusion matrix + top-1 / top-3 accuracy + bootstrap CI on top-1.

Usage

benchmark_run_classification(
  pedons,
  system = c("wrb2022", "sibcs", "usda"),
  level = c("order", "subgroup", "subordem", "great_group", "suborder"),
  boot_n = 1000L
)

Arguments

Value

A list with elements accuracy_top1, accuracy_ci, confusion, and per_pedon (one row per pedon with predicted vs reference).

Benchmark the accuracy lift of spectral gap-fill (ON vs OFF), k-fold

Description

The honest measurement that has been data-blocked until a spectra-bearing, labelled dataset exists. For each cross-validation fold it calibrates a spectral library on the training profiles, then classifies the held-out profiles twice – OFF (spectra-only pedon, no lab attributes) and ON (fill_from_spectra predicts the lab attributes from the scan first) – and scores both against the reference label. Non-circular: the calibration library never includes a test profile.

Usage

benchmark_spectral_fill(
  reflectance,
  metadata,
  id_col = "id",
  system = c("sibcs", "wrb2022", "usda"),
  profile_col = NULL,
  folds = 5L,
  properties = NULL,
  method = c("mbl", "plsr_local", "pretrained"),
  wavelengths = NULL,
  resample_to = NULL,
  property_map = NULL,
  label_map = NULL,
  normalize = c("auto", "none", "percent"),
  fold_id = NULL,
  verbose = TRUE
)

Arguments

Value

A list with accuracy_off, accuracy_on, delta, n, per-fold rows, and the per-profile predictions frame.

See Also

read_spectral_library, fill_from_spectra

Unified cross-dataset benchmark across SiBCS / WRB / USDA

Description

Runs a system's soilKey classifier on every dataset that has reference labels for that system, then pools the results into a single nation-/world-wide accuracy estimate.

Usage

benchmark_unified(
  systems = c("all", "wrb2022", "sibcs", "usda"),
  datasets = c("all", "bdsolos", "febr", "kssl", "lucas_esdb"),
  paths = NULL,
  max_n_per_dataset = NULL,
  engine = c("soilkey", "aqp", "both"),
  harmonize = FALSE,
  gapfill = FALSE,
  verbose = TRUE
)

Arguments

Value

A list with elements:

• per_system – per-system pooled list(accuracy, n_compared, n_correct, confusion, per_class).

• per_system_per_dataset – per-(system, dataset) same shape, for breakdown.

• coverage – per-(system, dataset) sample sizes and label coverage.

• config – captures systems, datasets, engine, soilKey_version, timestamp.

Datasets and their reference labels

For each (system, dataset) pair, this function:

1. Loads pedons via the appropriate load_* helper.

2. Filters to pedons with a populated reference label for the requested system.

3. Normalises both reference and predicted labels via normalise_febr_*() / KSSL canonicalisation helpers.

4. Calls the system's classifier and records pred-vs-ref.

Then pools per-system results across datasets.

Engine selection (Phase 1 wiring)

For datasets with morphological data (BDsolos / FEBR), the diagnostics that pivot Argissolos / Latossolos / Cambissolos classification can be run with two engines:

• engine = "soilkey" (default) – the hand-coded WRB 6/1.4/20 thresholds.

• engine = "aqp" – aqp::getArgillicBounds / getCambicBounds (KST 13ed 3/1.2/8 thresholds).

On the v0.9.62 RJ benchmark (722 perfis), aqp was 14.8 pp stricter on argic and 40.6 pp more permissive on cambic; the SiBCS Argissolos / Latossolos / Cambissolos boundary is sensitive to both. engine is currently forwarded to a future v0.9.63 wired argic() / cambic(); for now, benchmark_unified() reports separately per engine when engine = "both".

See Also

benchmark_bdsolos, benchmark_lucas_2018, benchmark_run_classification, harmonize_to_gsm.

Benchmark soilKey WRB predictions against a USDA-derived ground truth

Description

Convenience wrapper: applies annotate_wrb_from_usda to attach derived WRB labels, runs classify_wrb2022 on each pedon, and returns top-1 accuracy + per-RSG recall.

Usage

benchmark_wrb_vs_usda(pedons, verbose = TRUE)

Arguments

Value

A list with accuracy, n_compared, confusion, per_class_recall.

Build per-taxon mean depth profiles for predicted-taxon gap-fill

Description

For each taxon (the first word of the reference label at the requested level), averages each attribute across the calibration pedons into the six standard depth slices (0-5 ... 100-200 cm). The result feeds gapfill_by_predicted_taxon. Calibrate on a set DISJOINT from the pedons you will fill (e.g. a train split) to keep the fill non-circular.

Usage

build_taxon_profiles(pedons, ref_field = "reference_sibcs", attrs = NULL)

Arguments

Value

A named list taxon -> attr -> numeric(6) (NA where a taxon has no measured value in a slice).

See Also

gapfill_by_predicted_taxon

Calcaric material (WRB 2022 Ch 3.3.3): \>= 2% CaCO3 throughout the fine earth, primary carbonates from the parent material.

Description

Calcaric material (WRB 2022 Ch 3.3.3): \>= 2% CaCO3 throughout the fine earth, primary carbonates from the parent material.

Usage

calcaric_material(pedon, min_caco3_pct = 2)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Calcic horizon (WRB 2022)

Description

Tests whether any horizon meets the calcic horizon criteria. The calcic horizon is a horizon of secondary carbonate accumulation, diagnostic for Calcisols and qualifying many other RSGs.

Usage

calcic(pedon, min_thickness = 15, min_caco3_pct = 15)

Arguments

Details

Sub-tests called:

• test_caco3_concentration – CaCO3 >= 15%.

• test_minimum_thickness – thickness >= 15 cm.

v0.2 limitations: the WRB criterion of "5% absolute or relative more CaCO3 than the underlying horizon" is not enforced; this captures true calcic horizons but may also mark uniformly carbonate-rich substrates that are not pedologically calcic. Cementation (petrocalcic) is not yet detected. Both refinements are scheduled for v0.3.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022). World Reference Base for Soil Resources, 4th edition. International Union of Soil Sciences, Vienna. Chapter 3 – Calcic horizon.

Cambic horizon (WRB 2022)

Description

Tests whether any horizon meets the cambic horizon criteria. The cambic horizon is a subsurface horizon with evidence of pedological alteration that does not meet the criteria for any stronger diagnostic horizon. It is the diagnostic of Cambisols.

Usage

cambic(pedon, min_thickness = 15, min_top_cm = 5, engine = NULL)

Arguments

Details

v0.2 implementation tests three conditions:

• thickness >= 15 cm (test_minimum_thickness)

• texture sandy loam or finer (test_texture_argic)

• NOT argic AND NOT ferralic

v0.2 limitations: WRB 2022 also excludes profiles with spodic, calcic, gypsic, plinthic, vertic, and several other diagnostic horizons. Those exclusions, plus the WRB criteria of "evidence of alteration" (color/structure differences from parent material, carbonate removal), are scheduled for v0.3.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 3, Cambic horizon.

Cambic horizon via aqp::getCambicBounds()

Description

Wraps aqp::getCambicBounds() in soilKey's DiagnosticResult contract. The aqp test enforces the KST 13ed cambic criteria:

• Texture finer than loamy fine sand (i.e. NOT in the sandy-texture pattern).

• Soil structure or absence of rock structure.

• Evidence of pedogenic alteration (chroma / value / clay).

• NOT meeting argic / oxic / spodic / mollic criteria.

soilKey's cambic (and the SiBCS proxy B_incipiente) implements similar logic but with SiBCS / WRB-flavoured exclusions; the aqp engine here is an independent canonical reference.

Usage

cambic_aqp(pedon, argi_bounds = NULL, ...)

Arguments

Value

A DiagnosticResult with name = "cambic_aqp".

See Also

cambic (soilKey hand-coded), aqp::getCambicBounds.

Load a canonical reference dataset from soilKey or SoilTaxonomy

Description

Resolution order:

1. If the SoilTaxonomy package is installed AND the prefer_pkg argument is TRUE (default), load the dataset from the installed package (always fresh).

2. Otherwise, load from the vendored copy at inst/extdata/canonical/<name>.rda.

Usage

canonical_reference(
  name = c("WRB_4th_2022", "ST_criteria_13th", "ST_features"),
  prefer_pkg = TRUE
)

Arguments

Value

The dataset as the original R object (list or data.frame).

See Also

wrb2022_canonical, kst13_canonical, st_features_canonical.

Canonicalise a USDA Great Group label to a KST 13ed-compatible key

Description

Maps both obsolete (pre-KST 13ed) and modern Great Group names to a single canonical key, so that direct equality between predicted and reference Great Group names ignores edition-driven renaming. Names that have no known mapping pass through unchanged.

Usage

canonicalise_kst13ed_gg(gg)

Arguments

Details

Examples of the canonicalisation (each pair is rendered equivalent):

• "haplaquolls" (KST 8) === "endoaquolls" (KST 13ed)

• "pellusterts" (KST 8) === "hapluderts" (KST 13ed)

• "camborthids" (KST 8) === "haplocambids" (KST 13ed)

• "vitrandepts" (KST 8) === "vitrudands" (KST 13ed)

Value

Character vector of canonical keys. Unmapped names pass through. NA stays NA. Empty input returns empty vector.

References

Soil Survey Staff (2022), Keys to Soil Taxonomy 13ed, Ch 4 (Order keys); previous editions for the obsolete names.

Cerosidade quantitativa (SiBCS Cap 13, p 207; Cap 1)

Description

Diagnostico parametrizado quantidade x intensidade de cerosidade (clay films / cutans). Consume as colunas v0.7.2 clay_films_amount (ordinal: few/pouca, common/comum, many/abundante, continuous/continua) e clay_films_strength (ordinal: weak/fraca, moderate/moderada, strong/forte; "shiny" mapeado a "strong"), introduzidas em substituicao ao legado clay_films.

Usage

cerosidade(pedon, min_amount = "common", min_strength = "moderate")

Arguments

Details

Discriminante critico Nitossolos vs Argissolos no Cap 13: Nitossolos exigem cerosidade \ge comum + \ge moderada (defaults).

Value

DiagnosticResult; passed = TRUE se ao menos um horizonte B atende ambos os limiares.

References

Embrapa (2018), SiBCS 5a ed., Cap 13 (Nitossolos), p 207; Cap 1 (atributos diagnosticos).

Chernic horizon (WRB 2022): the cherozemic-style mollic with very high biological activity (worm holes, casts, coprolites). v0.3.3: delegates to mollic + worm_holes_pct >= 50 (proxy for "biological homogenization").

Description

Chernic horizon (WRB 2022): the cherozemic-style mollic with very high biological activity (worm holes, casts, coprolites). v0.3.3: delegates to mollic + worm_holes_pct >= 50 (proxy for "biological homogenization").

Usage

chernic(pedon, min_worm_pct = 50)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Chernozem RSG diagnostic (WRB 2022)

Description

Tests whether a profile satisfies the Chernozem RSG criteria: a mollic horizon plus secondary carbonates somewhere in the profile, plus chroma (moist) <= 2 in at least one layer of the upper 20 cm.

Usage

chernozem(pedon, max_chroma_upper = 2)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Chernozems.

Chernozem RSG gate (strengthened, WRB 2022 Ch 4, p 111)

Description

WRB-canonical: chernic horizon AND, starting \<= 50 cm below the lower limit of the mollic horizon and (if a petrocalcic horizon is present) above it, a layer with protocalcic properties \>= 5 cm thick OR a calcic horizon AND base saturation \>= 50% from the surface to the protocalcic / calcic layer throughout.

Usage

chernozem_strict(pedon, min_bs = 50, max_top_cm = 50, strict = NULL)

Arguments

Details

v0.3.4 strengthens the previous v0.2 chernozem (which only required mollic + chernic_color) by adding the protocalcic / calcic gate and the BS \>= 50% requirement.

Note: the v0.2 chernozem() diagnostic remains available as a less-strict variant; chernozem_strict() is what the v0.3.4 key.yaml uses for the CH RSG.

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Tier-3 strict mode (v0.9.98)

With strict = TRUE the base-saturation floor above the carbonate-bearing layer is raised from 50% to 80%, in line with the very high base status expected of a textbook Chernozem.

Claric material (WRB 2022 Ch 3.3.4): light-coloured fine earth with Munsell criteria.

Description

Claric material (WRB 2022 Ch 3.3.4): light-coloured fine earth with Munsell criteria.

Usage

claric_material(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Robustness of classification under input perturbation

Description

For a given PedonRecord, perturb a chosen list of horizon attributes by a configured fractional amount, re-classify under the requested system, and report how often the classification $rsg_or_order (or full $name) matches the unperturbed baseline.

Usage

classification_robustness(
  pedon,
  system = c("wrb2022", "sibcs", "usda"),
  level = c("order", "name"),
  n = 50L,
  perturbations = NULL,
  provenance_aware = FALSE,
  seed = 42L
)

Arguments

Details

Default perturbation panel:

• clay_pct: ±5

• sand_pct: ±5

• silt_pct: ±5

• ph_h2o: ±0.2 absolute

• oc_pct: ±10

Value

A list with elements baseline (the unperturbed classification name), n (number of MC runs), robustness (fraction of perturbed runs matching baseline), flipped_to (table of alternative classifications when the perturbation flipped the result).

Examples

## Not run: 
p <- make_ferralsol_canonical()
classification_robustness(p, system = "wrb2022", n = 50)
#> $baseline    : "Ferralsols"
#> $robustness  : 0.96  (48 / 50 perturbed runs landed on Ferralsols)
#> $flipped_to  : table(c("Cambisols" = 1, "Acrisols" = 1))

## End(Not run)

Classify a pedon across all three taxonomic systems

Description

Convenience wrapper that runs classify_wrb2022, classify_sibcs, and classify_usda on the same PedonRecord and returns a single named list with one entry per system (plus a summary table that's handy for reports).

Usage

classify_all(
  pedon,
  systems = "all",
  on_missing = c("warn", "silent", "error"),
  include_familia = TRUE,
  include_family = FALSE,
  specifiers = FALSE,
  gapfill = FALSE,
  ...
)

Arguments

Details

Each classifier still produces its own ClassificationResult with the full key trace and evidence grade – nothing is collapsed or homogenised. The wrapper exists for ergonomics, not abstraction.

Value

A named list with elements:

• wrb – ClassificationResult from classify_wrb2022() (or NULL if the system was skipped or errored).

• sibcs – as above, from classify_sibcs().

• usda – as above, from classify_usda().

• summary – a 1-row data.frame with one column per system, holding the resulting $name (or NA when the system was skipped / errored). Useful for tabulating many pedons in one shot.

Selecting a subset of systems

Pass systems = c("wrb2022", "sibcs") (or any other subset) to skip systems you don't need. Default systems = "all" runs all three.

Errors and partial results

If a single classifier raises an error, the corresponding slot of the returned list is set to NULL and a one-line warning is emitted (so you can rerun the offender on its own to see the full traceback). The other classifiers still run and their results are returned. This matches the spirit of on_missing = "warn" on the individual classifiers.

Side effects

None. The classifiers do not mutate pedon; the wrapper does not attach any side-channel state.

See Also

classify_wrb2022, classify_sibcs, classify_usda.

Examples

pr <- make_ferralsol_canonical()
all_three <- classify_all(pr)
all_three$summary

# WRB + USDA only (skip SiBCS):
classify_all(pr, systems = c("wrb2022", "usda"))$summary

Classify a soil by spectral similarity to OSSL reference profiles

Description

Given a Vis-NIR (or MIR) spectrum and an OSSL reference library enriched with WRB / SiBCS / USDA labels, returns the K most spectrally similar profiles plus a probabilistic class prediction aggregated from their labels.

Usage

classify_by_spectral_neighbours(
  spectrum,
  ossl_library,
  system = c("wrb2022", "sibcs", "usda"),
  k = 25L,
  preprocess = "snv+sg1",
  region = NULL,
  verbose = TRUE
)

Arguments

Details

This is the **spectral analogy** classifier. It does not replace the deterministic key in classify_wrb2022 / classify_sibcs / classify_usda; instead it provides a high-prior "expected class" before the user has lab data, reducing the search space when collecting confirming attributes.

Value

A list with three elements:

distribution

A data.table with columns class, n_neighbours, probability (= n_neighbours / k), sorted by probability.

neighbours

A data.table with one row per neighbour (top K), columns rank, distance, class, plus any other columns present in ossl_library$Yr.

query

The query metadata (system, k, region filter, n_library_rows, n_filtered).

Distance metric

By default we compute distances on PLS scores (matching the resemble / OSSL recipe), with PLS components fit on the OSSL reference Yr matrix. When resemble is unavailable, we fall back to PCA scores from stats::prcomp on the preprocessed Xr – a defensible-but-simpler heuristic.

Region filter

Optional lat / lon / radius_km arguments filter the OSSL library to profiles within radius_km (great-circle) of the query location before computing distances. This implements the "biome-aware" use case the architecture document calls for: a Cerrado profile shouldn't have its class inferred from spectral neighbours in the Boreal taiga.

See Also

predict_ossl_mbl (predicts attributes), classify_wrb2022 (the deterministic key).

Examples

## Not run: 
# Toy run against the bundled demo library (synthetic):
data(ossl_demo_sa)
# Inject a fake label column for the demo (real OSSL has it):
ossl_demo_sa$Yr$wrb_rsg <- sample(c("FR", "AC", "LX", "AL"),
                                    nrow(ossl_demo_sa$Yr),
                                    replace = TRUE)
query <- ossl_demo_sa$Xr[1, ]
res <- classify_by_spectral_neighbours(query, ossl_demo_sa,
                                        k = 10)
res$distribution    # ranked classes
res$neighbours      # the 10 most similar profiles

## End(Not run)

Build a fully-classified 'PedonRecord' from documents in one call

Description

Highest-level entry point of the soilKey VLM pipeline. Given a soil-description PDF and / or a profile-wall photograph, this function:

Usage

classify_from_documents(
  pdf = NULL,
  image = NULL,
  fieldsheet = NULL,
  pedon = NULL,
  provider = "auto",
  model = NULL,
  systems = c("wrb", "sibcs", "usda"),
  report = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Details

1. Constructs a vision-language provider chat object via vlm_provider (defaults to local Ollama with Gemma 4 edge for institutional independence and data sovereignty).

2. Extracts horizons from pdf via extract_horizons_from_pdf, Munsell colours from image via extract_munsell_from_photo, and site metadata from fieldsheet via extract_site_from_fieldsheet. Every extracted attribute is stamped source = "extracted_vlm" in the PedonRecord's provenance log.

3. Runs the three deterministic keys (classify_wrb2022, classify_sibcs, classify_usda). The VLM never classifies – the package's architectural invariant is preserved.

4. Optionally renders a one-pager HTML / PDF report via report.

At least one of pdf, image or fieldsheet must be supplied; you can also pass an existing partially-filled PedonRecord via pedon and let this function fill the gaps.

Value

A list with elements:

pedon

The (mutated) PedonRecord.

classifications

Named list with up to three ClassificationResult objects keyed by wrb, sibcs, usda.

report

Path to the rendered report file (if report = ... was supplied), else NULL.

provider

The chat-provider object actually used (useful for downstream debugging or cost accounting).

Why local-first by default

The default provider = "ollama" runs the entire VLM pipeline on the user's machine via Gemma 4 (edge variant, ~3 GB, multimodal text+image). No part of the soil description, photograph or field sheet ever leaves the local network. This is the recommended configuration for governmental surveys, indigenous land studies, and unpublished research data; it also makes the pipeline reproducible without an internet connection. Cloud providers ("anthropic", "openai", "google") remain one argument away when they are the right call.

Architectural invariants preserved

• The VLM never classifies. Every extracted value carries source = "extracted_vlm"; the deterministic keys consume the resulting PedonRecord unaware of how each value was obtained.

• Provenance is preserved end-to-end. The evidence_grade on each ClassificationResult reflects whether decisive attributes came from measured, predicted_spectra, extracted_vlm, inferred_prior, or user_assumed – so a caller always knows how robust the classification is.

• Authority order is enforced. A pre-existing measured value is never silently overwritten by a later extracted_vlm value (unless overwrite = TRUE).

See Also

vlm_provider, extract_horizons_from_pdf, classify_wrb2022, report.

Examples

## Not run: 
# The simplest possible end-to-end call -- local Gemma 4 edge.
res <- classify_from_documents(
  pdf      = "perfil_042_descricao.pdf",
  image    = "perfil_042_parede.jpg",
  report   = "perfil_042.html"
)
res$classifications$wrb$name
#> "Geric Ferric Rhodic Chromic Ferralsol (Clayic, Humic, Dystric, Ochric, Rubic)"

# Cloud provider for a one-shot, production run
res <- classify_from_documents(
  pdf      = "perfil_042_descricao.pdf",
  provider = "anthropic"
)

# Different Gemma 4 size on Ollama
res <- classify_from_documents(
  pdf      = "perfil_042_descricao.pdf",
  provider = "ollama",
  model    = "gemma4:31b"
)

## End(Not run)

Classify a soil profile from field photographs alone

Description

A no-lab-data pipeline: profile photographs are sent to a vision-language model for Munsell-colour and (optionally) site-metadata extraction; the missing horizon attributes are back-filled from a SoilGrids depth prior; and the WRB 2022, SiBCS 5 and USDA Soil Taxonomy keys are run on the assembled PedonRecord.

Usage

classify_from_photos(
  images,
  lat = NULL,
  lon = NULL,
  country = NULL,
  provider = NULL,
  systems = c("wrb", "sibcs", "usda"),
  soilgrids = TRUE,
  depth_profiles = NULL,
  on_missing = "silent"
)

Arguments

Details

Because every value originates from a photograph or a spatial prior, the classification's evidence grade is low by construction (D for VLM-extracted attributes, C where a SoilGrids prior contributed). The result is a screening estimate, not a substitute for a described and sampled profile.

Value

A named list with one ClassificationResult per requested system ($wrb, $sibcs, $usda), the constructed $pedon, its $provenance ledger, and a one-row $summary data frame. If extraction yields no horizons the list instead carries $error and a NULL pedon.

See Also

extract_munsell_from_photo, apply_soilgrids_depth_prior, compute_per_attribute_evidence_grade.

Examples

## Not run: 
# Live use with an ellmer chat:
res <- classify_from_photos(
  images   = list(profile = "profile.jpg", fieldsheet = "sheet.jpg"),
  lat = -22.7, lon = -43.6, country = "BR",
  provider = ellmer::chat_anthropic())
res$wrb$name
res$wrb$evidence_grade   # "D" or "C"

## End(Not run)

Classifica um pedon segundo o SiBCS 5a edicao (1o + 2o + 3o + 4o niveis)

Description

v0.7 ligou as 13 ordens; v0.7.1 desce ao 2o nivel (subordens) via run_sibcs_subordem; v0.7.3 desce ao 3o nivel (Grandes Grupos) via run_sibcs_grande_grupo para as ordens progressivamente wiradas em inst/rules/sibcs5/grandes-grupos/<ordem>.yaml (Cap 14 Organossolos primeiro). Quando a subordem ainda nao tem bloco de Grandes Grupos, ou quando nenhum Grande Grupo passa (e nao ha catch-all default), a classificacao para no 2o nivel.

Usage

classify_sibcs(
  pedon,
  rules = NULL,
  on_missing = c("warn", "silent", "error"),
  include_familia = FALSE,
  gapfill = FALSE
)

Arguments

Value

Um ClassificationResult cujo name eh o nome completo da classe atribuida no nivel mais profundo (Grande Grupo > Subordem > Ordem) e rsg_or_order eh o nome da ordem (e.g. "Organossolos"). Os codigos de cada nivel e o trace ficam em $trace.

Examples

pedon <- make_latossolo_canonical()
res <- classify_sibcs(pedon)
res$name

Classifica um perfil no 5o nivel categorico do SiBCS (Familia)

Description

Aplica as dimensoes pertinentes a ordem do solo e devolve uma lista nomeada de FamilyAttribute. O label textual da Familia eh formado adicionando-se cada value nao-nulo apos a designacao do 4o nivel, separados por virgulas (Cap 18, p 281).

Usage

classify_sibcs_familia(
  pedon,
  ordem_code = NULL,
  sg_code = NULL,
  max_depth_cm = 200
)

Arguments

Details

Esta funcao NAO eh uma chave determinista: cada perfil recebe SIMULTANEAMENTE todos os adjetivos pertinentes (multi-rotulo).

Value

Lista nomeada de FamilyAttribute.

Status v0.7.14.A

Implementadas 5 dimensoes – grupamento textural, subgrupamento textural, distribuicao de cascalhos, constituicao esqueletica, tipo de horizonte superficial. Outras dimensoes (prefixos epi/ meso/endo, saturacao de bases, alico, mineralogia, atividade da argila, oxidos de ferro, andico, especificos de Organossolos) adicionadas em sub-commits subsequentes.

References

Embrapa (2018), SiBCS 5a ed., Cap 18, pp 281-288.

Classify a pedon under USDA Soil Taxonomy (13th edition)

Description

Walks the canonical USDA key (Order -> Suborder -> Great Group -> Subgroup) using YAML rule files at:

• inst/rules/usda/key.yaml: Order key (12 entries)

• inst/rules/usda/suborders/<order>.yaml

• inst/rules/usda/great-groups/<order>.yaml

• inst/rules/usda/subgroups/<order>.yaml

Usage

classify_usda(
  pedon,
  rules = NULL,
  on_missing = c("warn", "silent", "error"),
  include_family = FALSE,
  infer_temperature = TRUE,
  gapfill = FALSE
)

Arguments

Details

With include_family = TRUE it additionally derives the 5th category, the family – a set of class modifiers (particle-size, mineralogy, CEC-activity, reaction, temperature regime, depth) PREPENDED to the subgroup name, e.g. "fine, kaolinitic, isohyperthermic Rhodic Hapludox". See classify_usda_family.

Value

A ClassificationResult with deepest-level taxon name. Each level's trace is in $trace; the family attributes are in $trace$family.

References

Soil Survey Staff (2022). Keys to Soil Taxonomy, 13th edition. USDA Natural Resources Conservation Service.

Examples

pedon <- make_ferralsol_canonical()
res <- classify_usda(pedon)
res$name
# include the 5th (family) level:
classify_usda(pedon, include_family = TRUE)$name

Classify the USDA family (5th level) of a pedon

Description

Runs the applicable family-modifier dimensions and returns them as a named list of FamilyAttribute objects (multi-label; each dimension is orthogonal). Mirrors classify_sibcs_familia.

Usage

classify_usda_family(
  pedon,
  order_code = NULL,
  subgroup_code = NULL,
  infer_temperature = TRUE
)

Arguments

Value

Named list of FamilyAttribute objects.

References

Soil Survey Staff (2022), KST 13th ed., Ch. 16–17.

See Also

family_label_usda, classify_usda.

Classify a PedonRecord via Embrapa's SmartSolosExpert REST API

Description

Sends a soilKey PedonRecord to the SmartSolosExpert REST endpoint maintained by Embrapa (Glauber Vaz's PROLOG-based implementation of the SiBCS classifier) and returns the resulting four-level classification (Ordem / Subordem / Grande Grupo / Subgrupo) wrapped in a soilKey ClassificationResult.

Usage

classify_via_smartsolos_api(
  pedon,
  api_key = Sys.getenv("AGROAPI_TOKEN"),
  endpoint = c("classification", "verification"),
  drenagem = NULL,
  reference_sibcs = NULL,
  base_url = "https://api.cnptia.embrapa.br/smartsolos/expert/v1",
  timeout_seconds = 30,
  post_fn = NULL,
  verbose = TRUE
)

Arguments

Details

This is an **external classifier** – the package does not host or replicate the PROLOG rules. The function exists so soilKey users can cross-validate the local classifier against an authoritative Embrapa-hosted reference. Use the "verification" endpoint to compare against your own user-supplied reference classification (the API returns a per-level match summary with counters L0..L4).

Authentication: register a free AgroAPI account at https://www.agroapi.cnptia.embrapa.br/portal/, subscribe to the SmartSolosExpert API and generate an access token. Pass it via the AGROAPI_TOKEN environment variable or the api_key argument.

Value

A ClassificationResult with system = "SiBCS 5a edicao (SmartSolosExpert API)" and the four taxonomic levels in rsg_or_order (Ordem) and qualifiers (Subordem / GdeGrupo / Subgrupo). Verification-mode responses additionally carry trace$smartsolos_summary (the per-level match counters L0..L4).

References

Vaz, G. J., Silva Neto, L. de F. da, & Barbedo, J. G. A. (2025). SmartSolos Expert: an expert system for Brazilian soil classification. Smart Agricultural Technology, 10, 100735. doi:10.1016/j.atech.2024.100735.

Vaz, G. J., Silva Neto, L. de F. da, Lima, R. N., & Oliveira, S. R. de M. (2019). Uma API para a classificacao de solos do Brasil. In Anais do 12 Congresso Brasileiro de Agroinformatica (SBIAGRO 2019), pp. 63-72. Ponta Grossa.

Vaz, G. J., Silva Jr, A. F., & Silva Neto, L. de F. da (2023). Brazilian soil data for taxonomic classification. Redape, V1. doi:10.48432/PYKKA7.

See Also

classify_sibcs for the local PROLOG-free classifier; compare_smartsolos for a side-by-side comparison helper; benchmark_redape for the gold-standard curated dataset published by the same authors.

Examples

## Not run: 
Sys.setenv(AGROAPI_TOKEN = "<your token>")
res <- classify_via_smartsolos_api(make_argissolo_canonical())
res$rsg_or_order      # "ARGISSOLO"
res$qualifiers
#> $subordem  "VERMELHO"
#> $gde_grupo "Distrofico"
#> $subgrupo  "tipico"

## End(Not run)

Classify a pedon with the engine chosen by 'pick_engine()'

Description

Convenience wrapper that routes classify_wrb2022 / classify_sibcs / classify_usda through whichever engine the heuristic recommends for the specific pedon.

Usage

classify_with_engine_heuristic(
  pedon,
  system = c("wrb2022", "sibcs", "usda"),
  min_score = 3L,
  ...
)

Arguments

Value

The result of the chosen classifier (a ClassificationResult). The chosen engine is captured in $trace$engine_used.

Posterior distribution over classification outcomes

Description

Runs n Monte-Carlo perturbations of a pedon and tallies the resulting classes into an empirical posterior. Unlike classification_robustness, the perturbation magnitude of every (horizon, attribute) cell is scaled by its provenance evidence grade (see get_perturbation_scale): an A-grade measurement is nudged by a few percent, an E-grade assumption by a third of its value. The posterior therefore reflects not just how close the profile sits to a key boundary, but how trustworthy the inputs that placed it there actually are.

Usage

classify_with_uncertainty(
  pedon,
  n = 200L,
  system = c("wrb2022", "sibcs", "usda"),
  level = c("rsg", "name"),
  scales = NULL,
  sensitivity = TRUE,
  seed = 42L
)

Arguments

Value

A list of class "soilkey_uncertainty" with elements: posterior (named numeric vector summing to 1, sorted descending), top1 (the modal class), entropy (Shannon entropy of the posterior, natural log), sensitivity (a data.table of attribute / importance, or NULL), n_runs, n_success, baseline, system and level.

See Also

classification_robustness, get_perturbation_scale, compute_per_attribute_evidence_grade.

Examples

p <- make_ferralsol_canonical()
u <- classify_with_uncertainty(p, n = 50, system = "wrb2022")
u$posterior   # P(RSG = x)
u$entropy     # near 0 for a robust profile

Classify a pedon under WRB 2022

Description

High-level classification entry point. Pre-computes the implemented diagnostic horizons (argic, ferralic, mollic) for transparent reporting, runs the key, and assembles a ClassificationResult with the trace, ambiguities, missing-data hints, evidence grade, and (in future) prior sanity check.

Usage

classify_wrb2022(
  pedon,
  prior = NULL,
  prior_threshold = 0.01,
  on_missing = c("warn", "silent", "error"),
  rules = NULL,
  strict = NULL,
  specifiers = FALSE,
  gapfill = FALSE
)

Arguments

Value

A ClassificationResult.

Examples

pedon <- make_ferralsol_canonical()
res <- classify_wrb2022(pedon)
res$name

Clear the in-memory KST13 cache

Description

Useful when the vendored JSON files are updated mid-session. Frees ~3.1 MB.

Usage

clear_kst13_cache()

Value

NULL, invisibly. Called for its side effect of emptying the KST 13th-edition lookup cache.

Clear the soilKey OSSL cache

Description

Removes the per-region cache files written by download_ossl_subset. Useful when a stale cache is suspected or when disk space is tight.

Usage

clear_ossl_cache(region = NULL, cache_dir = NULL, verbose = TRUE)

Arguments

Value

Invisibly, the character vector of files that were removed.

Combine multiple spatial priors via weighted geometric mean

Description

Given a list of priors (each a data.table with rsg_code, probability), pools them into a single distribution using a weighted geometric mean and renormalises to sum to 1.

Usage

combine_priors(priors, weights = NULL, epsilon = 1e-06)

Arguments

Details

Geometric pooling has two desirable properties for soil-class priors:

1. externally Bayesian (the pooled posterior under any common likelihood matches what one would get by individual updates), and

2. zero-preserving: a class assigned probability 0 by any prior is suppressed in the pooled distribution. To avoid that, classes absent from a given prior are imputed with the smoothing constant epsilon.

Value

A data.table with columns rsg_code, probability, sorted by descending probability.

Side-by-side comparison of soilKey vs aqp diagnostic engines

Description

Runs the soilKey hand-coded diagnostic and the aqp wrapper on the same pedon, returns both results plus an agreement flag. Useful for A/B benchmarks and for choosing which engine to use per dataset.

Usage

compare_engines(pedon, diagnostic = c("argic", "cambic"))

Arguments

Value

A list with soilkey, aqp, agree.

Cross-validate the local SiBCS classifier against the SmartSolosExpert API

Description

Runs both classify_sibcs (local) and classify_via_smartsolos_api (remote PROLOG via Embrapa AgroAPI) on the same PedonRecord and tabulates agreement at each of the four SiBCS categorical levels.

Usage

compare_smartsolos(pedon, ...)

Arguments

Value

A list with local and remote ClassificationResults plus a one-row agreement data.frame with columns ordem, subordem, gde_grupo, subgrupo, n_match.

Examples

## Not run: 
Sys.setenv(AGROAPI_TOKEN = "<your token>")
cmp <- compare_smartsolos(make_argissolo_canonical())
cmp$agreement

## End(Not run)

Ki (silica:alumina molar) – SiBCS Cap 1, p 32

Description

Calcula o indice molar Ki = SiO2 / Al2O3 a partir de teores percentuais por ataque sulfurico-NaOH (Embrapa Manual de Metodos). Massas molares: 60.08 (SiO2), 101.96 (Al2O3):

Usage

compute_ki(sio2_pct, al2o3_pct)

Arguments

Details

Ki (molar) = (% SiO2 / 60.08) / (% Al2O3 / 101.96) \approx 1.6973 \times (% SiO2 / % Al2O3)

Value

Ki molar (numeric); NA se algum input for NA ou Al2O3 \le 0.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, p 32; Embrapa Manual de Metodos de Analise de Solo (3a ed., 2017).

Examples

compute_ki(sio2_pct = 18, al2o3_pct = 20)  # ~1.53, abaixo do limite latossolico

Kr (silica:sesquioxidos molar) – SiBCS Cap 1, p 32

Description

Calcula o indice molar Kr = SiO2 / (Al2O3 + Fe2O3) usando massas molares 60.08 (SiO2), 101.96 (Al2O3) e 159.69 (Fe2O3):

Usage

compute_kr(sio2_pct, al2o3_pct, fe2o3_pct)

Arguments

Details

Kr (molar) = (% SiO2 / 60.08) / (% Al2O3 / 101.96 + % Fe2O3 / 159.69)

Value

Kr molar (numeric); NA se algum input for NA ou denominador \le 0.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, p 32.

Examples

compute_kr(sio2_pct = 18, al2o3_pct = 20, fe2o3_pct = 12)

Per-attribute provenance-aware evidence grade

Description

Resolves the evidence grade of every (horizon, attribute) cell that carries a provenance entry. Where a cell has more than one entry (a value re-sourced over the profile's lifetime) the most authoritative source wins, mirroring PedonRecord's own authority order.

Usage

compute_per_attribute_evidence_grade(pedon)

Arguments

Details

Grades: A measured, B predicted from spectra, C inferred from a spatial prior, D extracted by a vision-language model, E user-assumed.

Value

A data.table with columns horizon_idx, attribute and grade, sorted by horizon then attribute. A pedon with no provenance entries yields a zero-row table.

See Also

classify_from_photos, the global evidence grade reported on every ClassificationResult.

Examples

p <- make_ferralsol_canonical()
compute_per_attribute_evidence_grade(p)   # all-measured -> all grade A

Continuous rock (WRB 2022 Ch 3.2.5)

Description

Consolidated material below the soil. v0.3.3: detects via designation R or Cr on the lowermost (or any) layer.

Usage

continuous_rock(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Honest taxonomic-completeness report

Description

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",
    "sibcs"),
  write = FALSE,
  report_dir = NULL
)

Arguments

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

cov <- coverage_report("usda_subgroup")
cov$overall
head(cov$missing)

Cryic conditions (WRB 2022)

Description

Tests whether continuous frozen / permafrost material occurs within the upper max_top_cm. Two alternative paths qualify per WRB 2022:

1. Permafrost temperature: a layer at top_cm <= max_top_cm (default 100) with permafrost_temp_C <= max_temp_C (default 0 C).

2. Designation pattern: a layer at top_cm <= max_top_cm with designation containing suffix "f" (frozen) or matching "^Cf" / "perma". Used as a fallback when the temperature field is not in the pedon (typical of legacy survey data).

Either path qualifies. Diagnostic of Cryosols.

Usage

cryic_conditions(pedon, max_top_cm = 100, max_temp_C = 0)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Cryosols.

Solo distrofico (SiBCS Cap 1, p 30)

Description

Negacao operacional de eutrofico: V < 50% no horizonte diagnostico subsuperficial.

Usage

distrofico(pedon, max_v = 50)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Dolomitic material (WRB 2022 Ch 3.3.5): \>= 2% Mg-rich carbonate, CaCO3/MgCO3 < 1.5. v0.3.3: detects via designation pattern kdo|do|magn as proxy when ratio data missing.

Description

Dolomitic material (WRB 2022 Ch 3.3.5): \>= 2% Mg-rich carbonate, CaCO3/MgCO3 < 1.5. v0.3.3: detects via designation pattern kdo|do|magn as proxy when ratio data missing.

Usage

dolomitic_material(pedon)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Download the BDsolos consulta-publica CSV (experimental, requires chromote)

Description

Drives the Embrapa BDsolos web form via headless Chrome (chromote) to produce a CSV of all profiles + all attributes. Marked **experimental**: heavy queries (no UF filter) frequently overload the Embrapa server. Prefer filter_uf = batches of one or two states at a time and stitch the resulting CSVs.

Usage

download_bdsolos(
  out_path,
  accept_terms = FALSE,
  filter_uf = NULL,
  attributes = "default",
  timeout_seconds = 600,
  chromote_session = NULL,
  verbose = TRUE
)

Arguments

Details

Per the Embrapa terms-of-use, the data is licensed for personal / academic use and publications must cite the source per ABNT. Set accept_terms = TRUE to acknowledge this and let the function click "Concordo" on your behalf.

Value

File path to the downloaded CSV (invisible).

See Also

load_bdsolos_csv, inspect_bdsolos_csv.

Examples

## Not run: 
# Single UF (fast, recommended)
download_bdsolos("soil_data/bdsolos/RJ.csv",
                  accept_terms = TRUE,
                  filter_uf    = "RJ")

# Stitch multiple UFs
for (uf in c("RJ", "SP", "MG", "ES")) {
  download_bdsolos(file.path("soil_data/bdsolos",
                               paste0(uf, ".csv")),
                    accept_terms = TRUE, filter_uf = uf)
}

# Then load all of them
csvs <- list.files("soil_data/bdsolos", "\\.csv$", full.names = TRUE)
all_pedons <- unlist(lapply(csvs, load_bdsolos_csv), recursive = FALSE)
length(all_pedons)

## End(Not run)

Download one or more soilKey lazy-fetch caches from GitHub Release

Description

soilKey ships four large benchmark caches (KSSL, KSSL+NASIS, AfSP, WoSIS stratified) that are too large to embed in the CRAN source tarball. Since v0.9.94 they are pinned to a versioned GitHub Release and downloaded on demand into the user cache directory at tools::R_user_dir("soilKey", "data").

Usage

download_extdata_cache(
  which = "all",
  release = .SOILKEY_LAZY_FETCH_RELEASE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Details

On first call to any of load_kssl_sample(), load_kssl_nasis_sample(), load_afsp_sample(), or load_wosis_stratified_sample(), soilKey checks for the file in the user cache. If missing, the loader prompts (interactive sessions only) to download. Use download_extdata_cache() to eagerly populate the cache without prompting.

Value

Invisibly, a named character vector of local paths to the downloaded files.

Examples

## Not run: 
# Download every lazy-fetch cache once, ahead of any benchmark run:
download_extdata_cache()

# Or just the WRB AfSP sample:
download_extdata_cache("afsp_sample")

## End(Not run)

Download an OSSL subset and return an 'ossl_library' artefact

Description

Fetches a region-filtered subset of the Open Soil Spectral Library (Sanderman et al. 2024) and assembles it into the 'list(Xr, Yr, metadata)' shape consumed by predict_ossl_mbl and predict_ossl_plsr_local. The result is cached under 'tools::R_user_dir("soilKey", "cache")' so subsequent calls in the same session (or future R sessions) skip the network.

Usage

download_ossl_subset(
  region = c("global", "south_america", "north_america", "europe", "africa", "asia",
    "oceania"),
  properties = c("clay_pct", "sand_pct", "silt_pct", "cec_cmol", "bs_pct", "ph_h2o",
    "oc_pct", "fe_dcb_pct", "caco3_pct"),
  wavelengths = 350:2500,
  endpoint = NULL,
  cache_dir = NULL,
  force = FALSE,
  verbose = TRUE
)

Arguments

Details

This function intentionally does not fall back to the synthetic predictor on network failure – a missing OSSL artefact is a real condition that the caller must handle, and silent fallback would make benchmarks meaningless.

Value

A list with elements Xr (numeric matrix, rows = training profiles, columns = wavelengths in nm), Yr (data.frame with the requested property columns, rows aligned to Xr), and metadata (snapshot date, region, n profiles, source URL, and the SHA-256 of the cache file). Pass it as the ossl_library argument to fill_from_spectra or predict_ossl_mbl.

References

Sanderman, J., Savage, K., Dangal, S.R.S., Duran, G., Rivard, C., Cardona, M.T., Sandzhieva, A., Aramian, A. & Safanelli, J.L. (2024). Soil Spectroscopy for Global Good – the Open Soil Spectral Library (OSSL). https://soilspectroscopy.org/.

Download an OSSL subset and attach WRB / SiBCS / USDA labels

Description

Fetches a region-filtered slice of the Open Soil Spectral Library via download_ossl_subset and post-joins WRB Reference Soil Group labels from WoSIS GraphQL by spatial nearest-neighbour. The resulting artefact has the canonical list(Xr, Yr, metadata) shape – with extra columns in Yr: wrb_rsg, wrb_label_source, wrb_label_distance_km, plus optionally sibcs_ordem and usda_order when translate_systems = TRUE.

Usage

download_ossl_subset_with_labels(
  region = c("global", "south_america", "north_america", "europe", "africa", "asia",
    "oceania"),
  max_distance_km = 5,
  wosis_endpoint = NULL,
  translate_systems = TRUE,
  max_to_label = Inf,
  verbose = TRUE,
  query_fn = NULL,
  ...
)

Arguments

Value

A list with Xr (numeric matrix), Yr (data frame with the labels attached), and metadata (list with the OSSL fetch metadata + the join statistics: number of profiles labeled, average / max distance, WoSIS endpoint, snapshot date).

Why this function exists

OSSL stores Vis-NIR / MIR spectra and lab data but typically lacks WRB Reference Soil Group labels on most profiles (KSSL data is USDA-flavoured; non-US contributions are inconsistent). WoSIS, by contrast, archives ~228 000 profiles with WRB labels but no spectra. This function bridges the two so the user can run classify_by_spectral_neighbours on a real-data OSSL library without having to do the spatial join themselves.

Caveats and provenance

WRB labels obtained via spatial join are weak labels. The same physical location may have been classified differently across surveys (different WRB editions, different interpretations). Each row carries:

• wrb_label_source = "wosis_spatial_join": label inherited from a WoSIS neighbour within max_distance_km.

• wrb_label_distance_km: the distance to that neighbour (NA when no neighbour was found within tolerance).

• wrb_label_source = "ossl_native": label was already present in OSSL Yr (rare; preserved verbatim).

• wrb_label_source = "missing": no neighbour within tolerance; the row stays unlabeled and will be skipped downstream.

Treat the labels as priors, not ground truth.

See Also

download_ossl_subset, classify_by_spectral_neighbours.

Examples

## Not run: 
# Real OSSL South-America subset with WRB labels:
lib <- download_ossl_subset_with_labels(
  region          = "south_america",
  max_distance_km = 10
)
table(lib$Yr$wrb_rsg, useNA = "always")
table(lib$Yr$wrb_label_source)

# Drop into the spectral analogy classifier:
res <- classify_by_spectral_neighbours(
  spectrum     = my_query_spectrum,
  ossl_library = lib,
  k            = 25,
  region       = list(lat = -22.7, lon = -43.7,
                      radius_km = 500)
)

## End(Not run)

Download the curated Redape GeoTab dataset (Vaz et al 2023)

Description

Enumerates the dataset via the Dataverse API and downloads all JSON profile files (the structured / interoperable format used by the curators) into dest_dir. Skips files already present unless overwrite = TRUE.

Usage

download_redape_dataset(
  dest_dir,
  dataset_doi = .REDAPE_GEOTAB_DOI,
  include_rtf = FALSE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character vector of paths to the downloaded files.

References

Vaz, G. J., Silva Jr, A. F., & Silva Neto, L. de F. da (2023). Brazilian soil data for taxonomic classification. Redape, V1. doi:10.48432/PYKKA7.

Duric horizon (WRB 2022)

Description

Tests for >= 10% volume of duripan nodules (Si-cemented) within a horizon at least 10 cm thick. Diagnostic of Durisols.

Usage

duric_horizon(pedon, min_thickness = 10, min_duripan_pct = 10)

Arguments

Value

A DiagnosticResult.

v0.3.1: thresholds aligned with WRB 2022 Ch 3.1.7 (10%, 10 cm) – previous v0.3 used 15%/15 cm. Petroduric (cemented continuous duripan) detection still deferred and will be added in v0.4.

References

IUSS Working Group WRB (2022), Chapter 3.1.7 – Duric horizon (p. 41).

Duripa (SiBCS Cap 2, p 74; v0.7)

Description

Reuso de duric_horizon (WRB Ch 3.1): subsuperficial cimentado por silica, continuo ou em \>= 50% volume.

Usage

duripa(pedon, ...)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Coerce a horizons-like data.frame to the canonical schema

Description

Adds any missing canonical columns as NAs of the right type and reorders canonical columns first. Extra user-supplied columns are preserved at the end. Coerces character values to numeric where the schema requires it.

Usage

ensure_horizon_schema(h)

Arguments

Value

A data.table with the canonical horizon columns present, in canonical order, with extra columns preserved at the end.

Examples

h <- ensure_horizon_schema(data.frame(top_cm = 0, bottom_cm = 20))
"designation" %in% names(h)

Solo eutrofico (SiBCS Cap 1, p 30)

Description

Returns TRUE se a saturacao por bases (V%) >= 50% no horizonte diagnostico subsuperficial (B ou C). 65% para A chernozemico.

Usage

eutrofico(pedon, min_v = 50)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Evaluate the test block of a single RSG

Description

Given a parsed tests block from a YAML key entry, evaluates the appropriate combinator and returns a list with passed, evidence, missing, and (optionally) notes.

Usage

evaluate_rsg_tests(pedon, tests)

Arguments

Value

A list summarising the test outcome.

Extract horizons from a soil description PDF

Description

Reads a PDF (typically a soil survey chapter, field-sheet scan, or thesis appendix), prompts the configured VLM to extract horizon attributes against inst/schemas/horizon.json, and merges the result into pedon. Every extracted attribute is recorded with source = "extracted_vlm" and the model's reported confidence and verbatim source quote.

Usage

extract_horizons_from_pdf(
  pedon,
  pdf_path = NULL,
  provider,
  max_retries = 3L,
  overwrite = FALSE,
  prompt_name = "extract_horizons",
  schema_name = "horizon",
  pdf_text = NULL
)

Arguments

Details

The PedonRecord's authority order guarantees that values already tagged "measured" are never silently overwritten by VLM extraction unless overwrite = TRUE.

If the PDF is long (more than ~30,000 characters), it is chunked page-by-page and each page is sent independently. This is a conservative-but-simple strategy; for very long surveys callers should pre-chunk and call this function once per profile.

Value

Invisibly, the (mutated) pedon. Carries a "vlm_extraction" attribute with the parsed response, number of attempts, and number of provenance entries added.

Failure modes

• If pdftools is not installed -> error.

• If the PDF cannot be read -> error.

• If the VLM response fails JSON parse / schema validation after max_retries + 1 attempts -> error from validate_or_retry.

Extract Munsell color from a profile photo

Description

Sends the photo to a multimodal VLM with a prompt that asks the model to estimate Munsell hue / value / chroma per visible horizon (when a Munsell reference card is in frame). Recorded as extracted_vlm with the model's self-reported confidence; photos without a reference card should yield confidence below 0.5 per the prompt specification.

Usage

extract_munsell_from_photo(
  pedon,
  image_path,
  provider,
  max_retries = 3L,
  overwrite = FALSE,
  prompt_name = "extract_munsell_from_photo",
  schema_name = "horizon"
)

Arguments

Details

Quantitative non-color attributes (clay %, CEC, pH, etc.) are never extracted from photos, by prompt-level instruction. If the model returns one anyway, it is silently dropped.

Value

Invisibly, the mutated pedon, with the photo added to pedon$images.

Extract site metadata from a field-sheet image

Description

Sends a photographed / scanned field sheet to a multimodal VLM and merges the extracted site-level metadata (lat, lon, elevation, parent material, land use, etc.) into pedon$site. Existing fields are preserved unless overwrite = TRUE; only NULL fields are filled.

Usage

extract_site_from_fieldsheet(
  pedon,
  image_path,
  provider,
  max_retries = 3L,
  overwrite = FALSE,
  prompt_name = "extract_site_metadata",
  schema_name = "site"
)

Arguments

Value

Invisibly, the mutated pedon.

Familia: mineralogia da fracao argila (geral, nao-Latossolos)

Description

Classifica a mineralogia da argila para Argissolos, Cambissolos, Plintossolos, Luvissolos, Nitossolos, Vertissolos, Chernossolos, Planossolos, Gleissolos quando ha informacao quantitativa de atividade da argila e/ou Ki/Kr. Cobre as classes nao endereçadas por familia_mineralogia_argila_latossolo:

• esmectitica: T_argila >= ta_threshold (default 27 cmolc/kg argila), indicando dominancia de argilas 2:1 expansivas (esmectita / vermiculita / micas hidratadas).

• caulinitica: Ki >= ki_caulinitico_min (default 0.75) e Kr >= kr_caulinitico_min (default 0.75), alem de T_argila < ta_threshold.

• oxidica: Kr < kr_caulinitico_min, indicando predominancia de oxihidrooxidos de Fe e Al.

• mista: nenhum dos outros gates fechou conclusivamente – evidencia heterogenea ou incompleta.

Quando os tres atributos (T_argila, Ki, Kr) estiverem ausentes, o resultado fica NULL e os atributos faltantes sao reportados.

Usage

familia_mineralogia_argila_geral(
  pedon,
  max_depth_cm = 200,
  ta_threshold = 27,
  ki_caulinitico_min = 0.75,
  kr_caulinitico_min = 0.75
)

Arguments

Value

FamilyAttribute.

References

Embrapa (2018), SiBCS 5a ed., Cap 18, p 286-287.

Curated index of FEBR datasets that carry Munsell colors

Description

Returns a data.frame listing FEBR dataset IDs that have at least one Munsell-related column populated in their camada table, with metadata: n_horizons, n_finite_munsell, coverage, column_pattern.

Usage

febr_index_munsell(min_coverage = 0.1, refresh = FALSE, verbose = TRUE)

Arguments

Details

Backed by a precomputed cache shipped in R/sysdata.rda (.FEBR_MUNSELL_INDEX; results of the May 2026 scan over 249 datasets). On first call after install, returns the cache instantly. Pass refresh = TRUE to re-scan FEBR live (slow, network-dependent; updates the in-memory copy but does not modify the bundled cache).

Value

A data.frame sorted by n_finite_munsell descending.

See Also

read_febr_pedons.

Ferralic horizon (WRB 2022)

Description

Tests whether any horizon meets the ferralic horizon criteria. The ferralic horizon is a subsurface horizon resulting from long and intense weathering, characterized by very low cation exchange capacity per unit clay – the canonical "low-activity clay" signal that defines the Ferralsol RSG.

Usage

ferralic(pedon, min_thickness = 30, max_cec = NULL, engine = NULL)

Arguments

Details

Sub-tests called:

• test_ferralic_texture – texture sandy loam or finer.

• test_cec_per_clay – CEC / clay <= 16 (or 20 under engine = "aqp") cmol_c/kg clay.

• test_ferralic_thickness – thickness >= 30 cm.

v0.3.1 alignment with WRB 2022 Ch 3.1.10 (p. 44): the older "ECEC <= 12 cmol_c/kg clay" gate was removed because it is not in the canonical text – only CEC (1M NH4OAc, pH 7) <= 16 is required.

v0.9.67 regional tolerance: BDsolos RJ benchmark (n=722 perfis) showed 88/115 Latossolos failing the strict 16-cmol gate because Embrapa lab methodology often reads CEC at 17-20 on profiles that are unambiguously Latossolos by every other criterion. The engine = "aqp" threshold of 20 closes that gap without redefining the WRB threshold itself; users targeting strict WRB 2022 fidelity should keep engine = "soilkey".

The weatherable-mineral test (<= 10% by volume), water-dispersible-clay test, and stratification / rock-structure exclusions remain deferred (they need mineralogical data outside the canonical horizon schema) and are refinements rather than gates.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022). World Reference Base for Soil Resources, 4th edition. International Union of Soil Sciences, Vienna. Chapter 3.1.10 – Ferralic horizon (p. 44).

Ferralsol RSG gate (WRB 2022 Ch 4, p 110)

Description

WRB-canonical: ferralic horizon \<= 150 cm AND no argic horizon starting above (or at the upper limit of) the ferralic, UNLESS the argic in its upper 30 cm or throughout has one or more of:

• < 10% water-dispersible clay; OR

• DeltapH (pH_KCl - pH_water) \>= 0; OR

• \>= 1.4% soil organic carbon.

v0.3.4 enforces all three exception paths. The DeltapH check uses ph_kcl and ph_h2o; the WDC check uses water_dispersible_clay_pct (introduced in v0.3.3 schema).

Usage

ferralsol(pedon, strict = NULL)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Tier-3 strict mode (v0.9.98)

When an argic horizon sits above the ferralic, the default gate keeps the profile as a Ferralsol if any one of the three exception paths (WDC \< 10%, DeltapH \>= 0, SOC \>= 1.4%) holds. With strict = TRUE the gate requires at least two of the three – a single weak indicator no longer rescues a profile with a translocated-clay argic from being keyed out of Ferralsols.

Ferric horizon (WRB 2022)

Description

A horizon of iron accumulation that does not reach the cementation / redness levels of plinthic. Diagnostic for the Ferric qualifier.

Usage

ferric(pedon, min_thickness = 15, min_fe_dith_pct = 5)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 3.1, Ferric horizon.

Material organico fibrico (SiBCS Cap 14)

Description

Material organico pouco decomposto: >= 40% de fibras esfregadas OU indice de von Post H1-H4. Discrimina Organossolos Fibricos no 3o nivel.

Usage

fibrico(pedon)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 14 (Organossolos), pp 224-226.

Fill missing soil attributes from spectra via OSSL

Description

Given a PedonRecord carrying a spectra$vnir matrix (rows = horizons, columns = wavelengths in nm), pre-processes the spectra, predicts the requested soil properties using the chosen OSSL-backed method, and writes the predictions into the pedon's horizons table via pedon$add_measurement(..., source = "predicted_spectra"). Each call updates the pedon's provenance log so that downstream classification can derive an evidence grade.

Usage

fill_from_spectra(
  pedon,
  library = "ossl",
  region = c("global", "south_america", "north_america", "europe", "africa"),
  properties = c("clay_pct", "sand_pct", "silt_pct", "cec_cmol", "bs_pct", "ph_h2o",
    "oc_pct", "fe_dcb_pct", "caco3_pct"),
  method = c("mbl", "plsr_local", "pretrained"),
  preprocess = "snv+sg1",
  k_neighbors = 100L,
  overwrite = FALSE,
  ossl_library = NULL,
  ossl_models = NULL,
  verbose = TRUE
)

Arguments

Details

By default, predicted values do not overwrite measured values (the add_measurement() authority logic protects them). Setting overwrite = TRUE forces overwrite of any non-measured value.

Value

The mutated pedon, invisibly. Provenance entries with source = "predicted_spectra" are added per (horizon, property).

See Also

preprocess_spectra, predict_ossl_mbl, predict_ossl_plsr_local, predict_ossl_pretrained, pi_to_confidence.

Fill missing Munsell colors on a PedonRecord from Vis-NIR spectra

Description

High-level helper that runs predict_munsell_from_spectra per horizon over the Vis-NIR spectra in pedon$spectra$vnir and writes the resulting hue / value / chroma back to the matching horizon rows via pedon$add_measurement(..., source = "predicted_spectra").

Usage

fill_munsell_from_spectra(pedon, overwrite = FALSE, verbose = TRUE)

Arguments

Details

This is the operational answer to the v0.9.35 Argissolo color confusion: when surveyor Munsell colors are missing and the user has Vis-NIR (e.g. from OSSL), call this helper, then re-run classify_sibcs – the v0.9.45 "color-undetermined" fallback will lift, and the classification will descend to subordem / grande grupo / subgrupo with proper evidence_grade.

Value

The pedon, invisibly. Provenance entries with source = "predicted_spectra" are appended.

Fluvic material (WRB 2022)

Description

Tests whether the profile shows fluvic material features: alternating textures across consecutive horizons within the upper 100 cm AND an irregular (non-monotone) organic carbon pattern with depth. Diagnostic of Fluvisols.

Usage

fluvic_material(pedon, max_top_cm = 100, min_clay_swing = 8)

Arguments

Details

Sub-test: test_fluvic_stratification.

v0.3 limitations: WRB 2022 fluvic material also requires age (typically <100 years for sediment freshness), which v0.3 does not check (no temporal fields in the schema). The stratification proxy is conservative – truly heterogeneous floodplain profiles with dramatic texture swings will pass; subtle alluvial sequences may miss. v0.4 will refine.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 3, Fluvic material.

Format a WRB 2022 soil name with qualifiers

Description

Format a WRB 2022 soil name with qualifiers

Usage

format_wrb_name(
  rsg_name,
  principal = character(0),
  supplementary = character(0)
)

Arguments

Value

Formatted string per Ch 6 p 154 ("Rhodic Ferralsol (Clayic, Humic, Dystric)").

Fragic horizon (WRB 2022): a high-bulk-density horizon with restricted rooting. v0.3.3: detects via bulk_density_g_cm3 >= 1.65 AND structure grade massive/very firm OR designation pattern x/Bx.

Description

Fragic horizon (WRB 2022): a high-bulk-density horizon with restricted rooting. v0.3.3: detects via bulk_density_g_cm3 >= 1.65 AND structure grade massive/very firm OR designation pattern x/Bx.

Usage

fragic(pedon, min_thickness = 15, min_bd = 1.65)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Fragipa (SiBCS Cap 2, p 73-74; v0.7)

Description

Reuso de fragic (WRB v0.3.3): horizonte subsuperficial endurecido quando seco, baixa MO, BD elevada, quebradicidade.

Usage

fragipa(pedon, ...)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Convert an aqp SoilProfileCollection back to a list of PedonRecord

Description

Inverse of as_aqp. Walks each profile in the SPC, renames aqp's canonical horizon column names back to soilKey's (top -> top_cm, name -> designation, clay -> clay_pct, ...), assembles a PedonRecord per profile, and returns the list.

Usage

from_aqp(spc)

Arguments

Details

Round-trip property: from_aqp(as_aqp(pedon)) reproduces pedon modulo column ordering.

Value

A list of PedonRecord objects (length = length(spc)).

See Also

as_aqp, the forward conversion.

Examples

## Not run: 
pedons <- list(make_ferralsol_canonical(), make_luvisol_canonical())
spc <- as_aqp(pedons)
pedons2 <- from_aqp(spc)
identical(pedons[[1]]$horizons$clay_pct, pedons2[[1]]$horizons$clay_pct)
#> [1] TRUE

## End(Not run)

Fill missing horizon attributes from the predicted taxon's mean profile

Description

Classifies pedon with NO fill to get a provisional taxon, then fills its missing cells from taxon_profiles[[<that taxon>]] (built by build_taxon_profiles). Non-circular: the fill is keyed on the model's own prediction, not the reference. Each fill is written with source = "inferred_prior" (grade C). Reachable via gapfill = list(method = "taxon", taxon_profiles = <...>).

Usage

gapfill_by_predicted_taxon(
  pedon,
  taxon_profiles,
  system = c("sibcs", "wrb2022", "usda"),
  attrs = NULL,
  confidence = 0.55
)

Arguments

Value

Invisibly, the mutated pedon; attribute "gapfill_by_predicted_taxon" records the taxon + cells filled.

See Also

build_taxon_profiles, apply_soilgrids_depth_prior

Fill horizon attributes derivable BY DEFINITION from the same horizon

Description

Recovers cells that are exact closures of other measured columns in the same horizon (not statistical estimates): the texture third (clay/silt/sand) when the other two are present and sum to \< 100; effective CEC as sum(bases) + al; aluminium saturation as 100 * al / ecec; and base saturation as 100 * sum(bases) / cec. Every fill is written with source = "inferred_prior" so the PedonRecord authority order keeps it from displacing a measured value and the evidence grade drops to "C". Companion to gapfill_within_pedon (depth interpolation) and apply_soilgrids_depth_prior (external prior); reachable via the gapfill = list(method = "derive") argument of the classifiers.

Usage

gapfill_derive_horizon(pedon, overwrite = FALSE)

Arguments

Value

Invisibly, the mutated pedon; attribute "gapfill_derive_horizon" records the count filled.

See Also

gapfill_within_pedon, apply_soilgrids_depth_prior

Fill interior missing horizon attributes by within-pedon depth interpolation

Description

For each requested attribute, builds a depth profile from the horizons in which that attribute is measured (non-NA) and linearly interpolates the value at the mid-depth of every horizon where it is missing – but only for horizons whose mid-depth falls strictly between the shallowest and deepest measured layer. Cells above the top or below the bottom measured layer are left NA: the function interpolates, it never extrapolates. Each fill is written with source = "inferred_prior", so the PedonRecord authority order keeps it from displacing a measured, spectra-predicted or VLM-extracted value, and any downstream compute_evidence_grade call reports grade "C".

Usage

gapfill_within_pedon(pedon, attrs = NULL, confidence = 0.6, overwrite = FALSE)

Arguments

Details

This is the within-pedon companion to apply_soilgrids_depth_prior (which fills from an external SoilGrids profile rather than from the profile's own measured layers). It is the mechanism behind the opt-in gapfill argument of classify_wrb2022, classify_sibcs, classify_usda and classify_all.

Note that this mutates pedon in place (as apply_soilgrids_depth_prior does). The gapfill argument of the classifiers operates on a deep copy instead, so a classification call never alters the caller's pedon.

Value

Invisibly, the mutated pedon. An attribute "gapfill_within_pedon" on the return value records how many cells were filled and for which attributes.

See Also

apply_soilgrids_depth_prior, classify_all

Examples

h <- data.frame(
  top_cm    = c(0, 20, 40, 60),
  bottom_cm = c(20, 40, 60, 90),
  clay_pct  = c(15, NA, 35, 40)
)
p <- PedonRecord$new(horizons = h)
gapfill_within_pedon(p, attrs = "clay_pct")
p$horizons$clay_pct   # second horizon filled to ~25 by interpolation

Monte-Carlo perturbation scale for an evidence grade

Description

Returns the noise magnitudes used by classify_with_uncertainty for a cell of the given evidence grade. A measurement (grade A) is perturbed only slightly; a user-assumed value (grade E) is perturbed heavily, reflecting how little is actually known about it.

Usage

get_perturbation_scale(grade = c("A", "B", "C", "D", "E"))

Arguments

Value

A list with three elements: pct (the half-width of the multiplicative perturbation, applied to most numeric attributes), ph_abs (the half-width of the additive perturbation applied to pH columns) and munsell_abs (the additive half-width for Munsell value / chroma columns).

Examples

get_perturbation_scale("A")$pct   # 0.03 -- measured values barely move
get_perturbation_scale("E")$pct   # 0.30 -- assumptions move a lot

Gleyic properties (WRB 2022)

Description

Tests whether the profile shows gleyic properties – evidence of prolonged saturation by groundwater – within the upper 50 cm. Gleyic properties are diagnostic for Gleysols and qualify many other RSGs (Endogleyic, Epigleyic qualifiers).

Usage

gleyic_properties(
  pedon,
  max_top_cm = 50,
  min_redox_pct = 5,
  stagnic_decay_factor = 3
)

Arguments

Details

Sub-test: test_gleyic_features – requires explicit redoximorphic_features_pct >= 5% within the upper 50 cm.

v0.2 deliberately does NOT use the Munsell-based shortcut (chroma <= 2 + value >= 4) as a primary criterion: that pattern fits albic / bleached horizons of Podzols just as well as truly reduced gleyic horizons. v0.3 will add reductimorphic / oxidimorphic feature discrimination once we model field-described mottle properties. v0.9.72 adds the designation-suffix path (opt-in).

Value

A DiagnosticResult.

v0.9.72 designation morphological inference (opt-in)

Field-described Brazilian Gleissolos profiles (e.g.\ the Embrapa Redape curated dataset) routinely encode gleyic properties via the designation suffix g (e.g.\ Cg, Cg1, Cgn, Apg) plus low-chroma Munsell colours (chroma \<= 2), without recording redoximorphic_features_pct as a numeric percent. The strict canonical test then returns NA on every horizon and Gleissolos cascade to other Orders.

With options(soilKey.gleyic_designation_inference = TRUE) the function accepts a layer as gleyic when:

1. the canonical redoximorphic_features_pct test is NA for that layer, AND

2. the designation matches [A-Z]+g[0-9a-z]? (a horizon name with a g suffix in the master letter sequence, e.g.\ Cg, Bg2, Apg, Cgn), AND

3. the layer has munsell_chroma_moist <= 2 (low-chroma reduced colour) when Munsell is recorded; if Munsell is missing on the layer the suffix alone is sufficient (designation suffix is the most direct signal of pedologist field judgment).

This is conservative: the suffix g is a master-letter modifier in the FAO/Embrapa horizon nomenclature that explicitly means "gleyic-affected" – the curator already made the call. Default is FALSE (canonical behaviour preserved).

References

IUSS Working Group WRB (2022), Chapter 3, Gleyic properties.

Gleysol RSG gate (WRB 2022 Ch 4, p 103)

Description

WRB-canonical (multi-path):

1. Layer \>= 25 cm starting \<= 40 cm with gleyic properties throughout AND reducing conditions in some parts of every sublayer; OR

2. Mollic/umbric > 40 cm thick with reducing conditions some parts of every sublayer 40 cm below mineral surface to lower limit, AND directly underneath a layer \>= 10 cm with lower limit \>= 65 cm having gleyic properties + reducing conditions; OR

3. Permanent saturation by water \<= 40 cm.

v0.3.4 enforces path 1 (the dominant path) and path 3 via designation (W / saturated marker). Path 2 is deferred (requires a depth-of- saturation column that's not standard).

Usage

gleysol(pedon, strict = NULL)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Tier-3 strict mode (v0.9.98)

With strict = TRUE the path-1 gleyic+reducing layer must start within the upper 25 cm (instead of 40 cm), and the path-3 designation-only fallback (a “W” / aquic marker) is disabled: strict mode requires measured gleyic and reducing evidence.

Default-value-for-NULL operator

Description

Returns the left-hand side if it is non-NULL, otherwise the right-hand side. Re-exported so that downstream code can use the same idiom soilKey itself uses internally.

Usage

a %||% b

Arguments

Value

Either a or b.

Gypsic horizon (WRB 2022)

Description

Tests whether any horizon meets the gypsic horizon criteria. The gypsic horizon is a horizon of secondary gypsum accumulation, diagnostic for Gypsisols.

Usage

gypsic(pedon, min_thickness = 15, min_gypsum_pct = 5)

Arguments

Details

Sub-tests called:

• test_caso4_concentration – gypsum >= 5%.

• test_minimum_thickness – thickness >= 15 cm.

v0.2 limitations: the WRB rule that gypsum content must exceed the underlying horizon by 1% (absolute) is not enforced. Petrogypsic (cemented) horizons are not yet detected. Both deferred to v0.3.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022). World Reference Base for Soil Resources, 4th edition. International Union of Soil Sciences, Vienna. Chapter 3 – Gypsic horizon.

Gypsiric material (WRB 2022 Ch 3.3.7): \>= 5% gypsum that is primary (not secondary). Without a "secondary fraction" schema column, v0.3.3 treats any layer with caso4_pct >= 5 as gypsiric unless it explicitly carries gypsic-horizon designation.

Description

Gypsiric material (WRB 2022 Ch 3.3.7): \>= 5% gypsum that is primary (not secondary). Without a "secondary fraction" schema column, v0.3.3 treats any layer with caso4_pct >= 5 as gypsiric unless it explicitly carries gypsic-horizon designation.

Usage

gypsiric_material(pedon, min_caso4_pct = 5)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Harmonise pedons to GlobalSoilMap depth intervals

Description

Runs mpspline2::mpspline_tidy() on each requested numeric horizon attribute, producing a new PedonRecord per input pedon whose horizons table covers the canonical GSM intervals (GSM_DEPTHS). Categorical attributes (designation, Munsell hue) are propagated by mode-over-depth-overlap.

Usage

harmonize_to_gsm(
  pedons,
  attributes = c("clay_pct", "silt_pct", "sand_pct", "ph_h2o", "oc_pct", "cec_cmol",
    "base_saturation_pct", "munsell_value_moist", "munsell_chroma_moist",
    "redoximorphic_features_pct"),
  depths = GSM_DEPTHS,
  lam = 0.1,
  verbose = TRUE
)

Arguments

Value

A list of new PedonRecord objects with harmonised horizons.

Why mass-preserving

The Bishop et al. (1999) spline conserves the integral of the attribute over depth: if the original pedon has 30 g/kg OC over 0-15 cm, the harmonised pedon will report 30 g/kg integrated over 0-15 cm (split between 0-5 and 5-15 in proportion to the spline-implied gradient). This is a critical property for benchmark integrity: simple linear interpolation does not preserve mass and biases means upward / downward systematically.

Categorical handling

designation and munsell_hue_moist (and other character columns in the horizon schema) cannot be splined. Instead, for each target GSM interval, we pick the modal value weighted by the depth-overlap fraction with the input horizons. Ties broken by uppermost-input-horizon precedence.

References

Bishop, T.F.A., McBratney, A.B., Laslett, G.M. (1999). "Modelling soil attribute depth functions with equal-area quadratic smoothing splines." Geoderma 91: 27-45.

Arrouays, D. et al. (2014). "GlobalSoilMap: Toward a fine-resolution global grid of soil properties." Advances in Agronomy 125: 93-134.

See Also

mpspline2::mpspline_tidy, GSM_DEPTHS.

Material organico hemico (SiBCS Cap 14)

Description

Material organico em decomposicao intermediaria: 17-40% de fibras esfregadas OU indice de von Post H5-H6. Discrimina Organossolos Hemicos no 3o nivel.

Usage

hemico(pedon)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 14 (Organossolos), pp 224-226.

Histic horizon (WRB 2022)

Description

A surface (or near-surface, after drainage) horizon of organic material; diagnostic of Histosols. Two alternative qualifying paths per WRB 2022:

• Contiguous: a single layer of organic material (OC % >= min_oc) reaching the surface and at least min_thickness cm thick (default 10 cm).

• Cumulative: organic material totalling cumulative_min_cm cm (default 40) within the upper cumulative_max_depth_cm (default 80). Relevant for folic / mossy Histosols on slopes.

Either path qualifies. The "after drainage" qualifier (recently drained organic soils) is treated as implicit since the same OC and thickness criteria apply.

Usage

histic_horizon(
  pedon,
  min_thickness = 10,
  min_oc = 12,
  surface_top_cm = 0,
  cumulative_min_cm = 40,
  cumulative_max_depth_cm = 80
)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 3, Histic horizon and organic material.

Canonical horizon column specification

Description

Returns the schema for the horizons data.table carried by a PedonRecord: an ordered named list mapping column names to their R type ("numeric" or "character"). Adding a new attribute means editing this single function.

Usage

horizon_column_spec()

Value

Named list of column types in canonical order.

Examples

spec <- horizon_column_spec()
head(names(spec))

Hortic horizon (WRB 2022): garden / kitchen-midden topsoil. Diagnostic criteria: thickness \>= 20 cm, dark colour (mollic-like), high P (Mehlich-3 P >= 100 mg/kg or P2O5_1pct_citric >= 175 mg/kg), high SOC.

Description

Hortic horizon (WRB 2022): garden / kitchen-midden topsoil. Diagnostic criteria: thickness \>= 20 cm, dark colour (mollic-like), high P (Mehlich-3 P >= 100 mg/kg or P2O5_1pct_citric >= 175 mg/kg), high SOC.

Usage

hortic(pedon, min_thickness = 20, min_oc = 1, min_p_mehlich3 = 100)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Hydragric horizon (WRB 2022): subsoil hydric horizon under anthraquic. v0.3.3 detects via designation pattern Bg|Brg immediately below an anthraquic-like topsoil.

Description

Hydragric horizon (WRB 2022): subsoil hydric horizon under anthraquic. v0.3.3 detects via designation pattern Bg|Brg immediately below an anthraquic-like topsoil.

Usage

hydragric(pedon, min_thickness = 20)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Hypersulfidic material (WRB 2022 Ch 3.3.8): \>= 0.01% inorganic sulfidic S, pH \>= 4, capable of severe acidification on aerobic incubation.

Description

Hypersulfidic material (WRB 2022 Ch 3.3.8): \>= 0.01% inorganic sulfidic S, pH \>= 4, capable of severe acidification on aerobic incubation.

Usage

hypersulfidic_material(pedon, min_s_pct = 0.01, min_pH = 4)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Hyposulfidic material (WRB 2022 Ch 3.3.9): same inorganic sulfidic S and field pH as hypersulfidic but does NOT consist of hypersulfidic (criterion 3 – does not acidify to pH < 4 on aerobic incubation, usually self-neutralised by carbonate). Reachable from v0.9.128: when incubation_ph is measured, a sulfidic + pH>=4 layer that stays >= 4 on incubation is the set-complement of hypersulfidic_material and is reported here. Without an incubation pH the two cannot be told apart, so this returns empty (the layer is reported as potential hypersulfidic instead).

Description

Hyposulfidic material (WRB 2022 Ch 3.3.9): same inorganic sulfidic S and field pH as hypersulfidic but does NOT consist of hypersulfidic (criterion 3 – does not acidify to pH < 4 on aerobic incubation, usually self-neutralised by carbonate). Reachable from v0.9.128: when incubation_ph is measured, a sulfidic + pH>=4 layer that stays >= 4 on incubation is the set-complement of hypersulfidic_material and is reported here. Without an incubation pH the two cannot be told apart, so this returns empty (the layer is reported as potential hypersulfidic instead).

Usage

hyposulfidic_material(pedon, min_s_pct = 0.01, min_pH = 4)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Diagnostic inspection of a BDsolos CSV before loading

Description

Reads the CSV header, attempts to map each column to the soilKey horizon schema via .bdsolos_match_column, and prints three sections:

Usage

inspect_bdsolos_csv(path, sep = NULL)

Arguments

Details

• Mapped columns – BDsolos name -> soilKey name

• Unmapped columns – columns the loader will ignore (review these before running load_bdsolos_csv to make sure no critical attribute is silently dropped)

• Munsell coverage – whether matiz / valor / croma are present in either umido or seco variants

Run this before load_bdsolos_csv on any new CSV from BDsolos, especially if the export schema looks unfamiliar (BDsolos has shipped multiple schema versions over the years).

Value

Invisibly, a list with mapped, unmapped, munsell_present, taxon_column.

Irragric horizon (WRB 2022): topsoil thickened by irrigation deposits. v0.3.3: thickness >= 20 cm + sediment-derived structure proxied via designation Apk|Apg|Au.

Description

Irragric horizon (WRB 2022): topsoil thickened by irrigation deposits. v0.3.3: thickness >= 20 cm + sediment-derived structure proxied via designation Apk|Apg|Au.

Usage

irragric(pedon, min_thickness = 20)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Kastanozem RSG diagnostic (WRB 2022)

Description

Tests whether a profile satisfies the Kastanozem RSG criteria: a mollic horizon plus secondary carbonates plus NOT-Chernozem colour (chroma (moist) > 2 in the upper 20 cm).

Usage

kastanozem(pedon, max_chroma_upper = 2)

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 5, Kastanozems.

Kastanozem RSG gate (strengthened, WRB 2022 Ch 4, p 112)

Description

Same structure as chernozem_strict but using the mollic horizon (no chernic gate) and starting \<= 70 cm of mineral soil surface.

Usage

kastanozem_strict(pedon, min_bs = 50, max_top_cm = 70, strict = NULL)

Arguments

Value

A DiagnosticResult recording whether the diagnostic is present, the qualifying layers, and the supporting evidence.

Tier-3 strict mode (v0.9.98)

With strict = TRUE the base-saturation floor above the carbonate-bearing layer is raised from 50% to 75%. The 70 cm carbonate-depth window is left unchanged.

Keys to Soil Taxonomy 13th edition canonical reference

Description

Convenience wrapper for canonical_reference("ST_criteria_13th"). Returns a nested list of 3,153 parsed Keys-to-Soil-Taxonomy clauses per chapter / page / key / taxon / code / clause / logic.

Usage

kst13_canonical(prefer_pkg = TRUE)

Arguments

Details

Source: NCSS-tech SoilTaxonomy R package. Original: USDA-NRCS (2022). Keys to Soil Taxonomy, 13th edition.

Value

The canonical Keys to Soil Taxonomy (13th ed.) criteria reference (a list / data.frame).

Load the canonical KST 13ed code -> taxon-name lookup table

Description

Returns the 3,153-row data.frame from inst/rules/usda/canonical/2022_KST_codes.json, vendored from NCSS-tech/SoilKnowledgeBase. Each row is a (code, name) pair.

Usage

kst13_codes()

Details

Code structure:

• Single letter ("A"-"L"): Soil Order (Gelisols, Histosols, ..., Entisols)

• Two letters ("AB", "AC", ...): Suborder

• Three letters: Great Group

• Four letters: Subgroup