Package {soilKey}

Type:	Package
Title:	Automated Soil Profile Classification per 'WRB' 2022, 'SiBCS' 5 and 'USDA' Soil Taxonomy 13
Version:	0.9.97
Date:	2026-05-13
Description:	Implements deterministic classification keys for the World Reference Base for Soil Resources ('WRB') 2022, 4th edition (IUSS Working Group WRB, 2022, ISBN:979-8-9862451-1-9), the Brazilian System of Soil Classification ('SiBCS') 5th edition (Santos et al., 2018, ISBN:978-85-7035-800-4) and the United States Department of Agriculture ('USDA') Soil Taxonomy 13th edition (Soil Survey Staff, 2022, https://www.nrcs.usda.gov/resources/guides-and-instructions/keys-to-soil-taxonomy). Provides a unified profile representation with explicit per-attribute provenance, multimodal extraction from field reports and photos via vision-language models (VLM), spatial priors from 'SoilGrids' (Poggio et al., 2021, <doi:10.5194/soil-7-217-2021>) and national soil maps, and gap-filling of soil attributes from visible-near-infrared (Vis-NIR) or mid-infrared (MIR) spectra via the Open Soil Spectral Library ('OSSL'; Safanelli et al., 2025, <doi:10.7717/peerj.18908>). The taxonomic key itself is never delegated to a large language model (LLM); 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
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1)
Imports:	R6, data.table, yaml, cli, rlang, withr
Suggests:	aqp, SoilTaxonomy, mpspline2, terra, foreign, sf, chromote, munsellinterpol, pls, prospectr, resemble, ellmer, httr, jsonlite, jsonvalidate, pdftools, magick, shiny, DT, DBI, RSQLite, testthat (≥ 3.0.0), knitr, rmarkdown
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-05-13 22:09:52 UTC; rodrigues.h
Author:	Hugo Rodrigues [aut, cre]
Maintainer:	Hugo Rodrigues <rodrigues.machado.hugo@gmail.com>
Repository:	CRAN
Date/Publication:	2026-05-19 09:20:21 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.

Parse AfSP Munsell colour string (e.g. "10YR 4/3") into hue/value/chroma

Description

Parse AfSP Munsell colour string (e.g. "10YR 4/3") into hue/value/chroma

Usage

.afsp_parse_munsell(s)

Build a soilKey PedonRecord from AfSP Profiles + Layers rows

Description

Build a soilKey PedonRecord from AfSP Profiles + Layers rows

Usage

.afsp_to_pedon(profile_row, layer_rows)

Convert AfSP NoData sentinel (-9999) to NA

Description

Convert AfSP NoData sentinel (-9999) to NA

Usage

.afsp_unna(x)

Apply the NASIS surveyor tie-breaker to a DiagnosticResult

Description

When result$passed is NA (insufficient data) AND the surveyor identified the matching diagnostic in NASIS, flips the result to TRUE with a provenance note. TRUE or FALSE canonical results are NOT overridden – the function returns the input unchanged in those cases.

Usage

.apply_nasis_tiebreaker(result, pedon, pattern, feature_label)

Arguments

Value

The (possibly modified) DiagnosticResult.

Internal helper: .argic_derived_aggregate

Description

Internal helper: .argic_derived_aggregate

Usage

.argic_derived_aggregate(tests, layer_keys)

Internal helper: .argic_derived_negative

Description

Internal helper: .argic_derived_negative

Usage

.argic_derived_negative(name, arg_res, note)

Detect strong clay-film qualifier strings (Portuguese / English)

Description

Internal helper used by argic_with_strong_clay_films() and the v0.9.61 B_latossolico() latossolic-vs-argic precedence rule. Strips Portuguese accents and matches the standard SiBCS Cap 18 "strong" terminology: comum, abundante, common, abundant.

Usage

.argic_strong_films_match(films_chr)

Arguments

Details

"Pouca", "fraca", "few", "weak" do NOT count as strong (they are the weak end of the SiBCS clay-film scale that allows latossolic features to dominate).

Value

Logical scalar: TRUE if any element matches a strong qualifier; FALSE for empty input or weak-only qualifiers.

Auto-detect the BDsolos field separator (',', ';', or tab)

Description

Auto-detect the BDsolos field separator (',', ';', or tab)

Usage

.bdsolos_detect_sep(path, header_line = 1L)

Convert BDsolos coords (graus / minutos / segundos / hemisferio) to decimal

Description

Convert BDsolos coords (graus / minutos / segundos / hemisferio) to decimal

Usage

.bdsolos_dms_to_decimal(graus, minutos, segundos, hemisferio)

Evaluate JS in a chromote session, returning a string result

Description

Evaluate JS in a chromote session, returning a string result

Usage

.bdsolos_eval(chromote_session, js)

Detect the line where the BDsolos CSV header starts

Description

BDsolos exports prepend a 1-line preamble plus an empty line before the actual schema header (a long quoted-string row with hundreds of fields). This walks the first N lines and returns the 1-based index of the header row.

Usage

.bdsolos_find_header_line(path, n_probe = 10L)

Guess the soilKey horizon column for a BDsolos column name

Description

Returns the canonical soilKey column name, or NA_character_ if no pattern matches.

Usage

.bdsolos_match_column(raw_name)

Discover taxonomic column (the surveyor's SiBCS classification)

Description

Discover taxonomic column (the surveyor's SiBCS classification)

Usage

.bdsolos_match_taxon_column(raw_name)

Convert BDsolos mottle-quantity ordinal class to percent

Description

BDsolos exports the "Mosqueado - Quantidade" field as an ordinal Portuguese class (pouco/comum/abundante in singular OR plural, with various accent / casing variants). The soilKey schema uses redoximorphic_features_pct (numeric volume maps the ordinal to a representative midpoint percent so that the gleyic_properties diagnostic can fire on field-described mottles.

Usage

.bdsolos_mosqueado_to_pct(x)

Arguments

Details

Mapping (per Embrapa / SiBCS field-description manual):

Value

Numeric vector of representative percent values (NA for empty / unknown labels).

Strip Latin-1 diacritics + lowercase for fuzzy matching

Description

iconv ASCII//TRANSLIT renders Portuguese diacritics as bigraphs (e.g. a-tilde -> ~a, c-cedilla -> c') which then get collapsed into spurious underscores. Pre-replace the common Portuguese diacritics by hand for deterministic output.

Usage

.bdsolos_norm(x)

Convert a subset of BDsolos rows (one perfil) to a soilKey horizons table

Description

Convert a subset of BDsolos rows (one perfil) to a soilKey horizons table

Usage

.bdsolos_rows_to_horizons(rows, sk_map)

Single (dataset, system) benchmark call dispatched by name

Description

Single (dataset, system) benchmark call dispatched by name

Usage

.benchmark_one_dataset_one_system(
  ds,
  sys,
  paths,
  max_n,
  harmonize = FALSE,
  verbose = TRUE
)

Build a single PedonRecord from one LUCAS chemistry row + optional BD row

Description

Build a single PedonRecord from one LUCAS chemistry row + optional BD row

Usage

.build_lucas_pedon_2018(chem_row, bd_row = NULL)

Build a single-row tibble describing the profile + classifications for the GPKG 'pedon_point' layer.

Description

Build a single-row tibble describing the profile + classifications for the GPKG 'pedon_point' layer.

Usage

.build_pedon_point_row(pedon, classifications, report_html)

Internal helper: .build_report_rmd

Description

Internal helper: .build_report_rmd

Usage

.build_report_rmd(results, pedon, title)

Internal helper: .candidate_layers

Description

Internal helper: .candidate_layers

Usage

.candidate_layers(h, candidate_layers = NULL)

Validate inputs to a prediction backend

Description

Validate inputs to a prediction backend

Usage

.check_predict_inputs(X, properties)

Classifica grau de decomposicao por camada: saprico / hemico / fibrico

Description

SiBCS Cap 14 adota o criterio USDA Soil Taxonomy:

Usage

.classify_decomposition(fiber_pct, von_post)

Details

Saprico: < 17% fibras esfregadas ou von Post H7-H10 Hemico: 17-40% fibras ou von Post H5-H6 Fibrico: >= 40% fibras ou von Post H1-H4

Robust per-layer column accessor.

Description

'h[[col]][i]' returns 'NULL' (length 0) when the column is absent from the horizon schema entirely (e.g. older fixtures pre-dating a schema extension). Downstream code then reaches 'is.na(NULL)', which is 'logical(0)', and crashes inside 'if (...)'. This helper converts an absent column to 'NA' of the requested mode so the "missing" branch in every sub-test is exercised cleanly.

Usage

.col_at(h, column, i, default = NA)

Details

Added 2026-04-30 after the canonical-fixture benchmark surfaced five errors of the form "argument is of length zero" coming from 'test_numeric_above', 'test_pattern_match', 'test_shrink_swell_cracks' on fixtures whose schema predates v0.3.3 column extensions.

Detecta fallback "cor a determinar" no nivel de subordem SiBCS

Description

Quando a subordem atribuida e uma catch-all de cor (PVA, LVA, NX, TX) E pelo menos um predicado anterior na trace falhou exatamente por ausencia de munsell_hue_moist, considera-se que o fallback foi forçado pela ausencia de matiz, nao pelo conteudo do perfil. Retorna NULL se a situacao nao se aplica.

Usage

.detect_color_undetermined_fallback(sub_result, subordem)

Discover Munsell-related columns in a FEBR layer table

Description

Returns a list with elements moist_string (single column with the Munsell string), moist_hue, moist_value, moist_chroma (separate columns), dry_string, dry_hue, dry_value, dry_chroma. Each is either a column name (character) or NA_character_. The loader uses the parsed columns when available, falls back to parsing the string column.

Usage

.detect_febr_munsell_columns(cols)

Details

Recognised conventions (from the May 2026 scan of 249 FEBR datasets):

• cor_munsell_umida (ctb0039, ctb0572)

• cor_cod_munsell_umida (ctb0032)

• cor_cod_munsell_umida_1 + cor_nome_munsell_umida_1 (ctb0005)

• cor_cod_munsell_umida_i (ctb0019)

• cor_munsell_umida_matiz + cor_munsell_umida_valor + cor_munsell_umida_croma (ctb0562-ctb0700+)

• cor_munsell_umida_nome (ctb0562+)

• cor_matriz_umido_munsell (canonical, morphology())

Same patterns apply for "seca" (dry).

Internal helper: .escape_latex

Description

Internal helper: .escape_latex

Usage

.escape_latex(x)

Map FEBR layer-table columns to soilKey horizon column names

Description

Map FEBR layer-table columns to soilKey horizon column names

Usage

.febr_match_layer_columns(cols)

Build a single PedonRecord from FEBR rows

Description

Build a single PedonRecord from FEBR rows

Usage

.febr_pedon_from_rows(oid, camada_rows, ob_row, ident, hz, ds)

Build a soilKey horizons table from a subset of FEBR camada rows

Description

Build a soilKey horizons table from a subset of FEBR camada rows

Usage

.febr_rows_to_horizons(rows, sk_map, mcols)

Fill a horizon (or synthesise a new one) from SoilGrids 250m

Description

Internal helper used by benchmark_lucas_2018. For each requested property, calls lookup_fn (default lookup_soilgrids) at soilgrids_depth, converts to the soilKey unit and writes onto the pedon's horizon horizon_idx via add_measurement(..., source = "inferred_prior"). Synthesises the horizon if it does not exist yet (geometry from horizon_top_cm / horizon_bottom_cm).

Usage

.fill_horizon_from_soilgrids(
  pedon,
  horizon_idx,
  properties,
  soilgrids_depth = "0-5cm",
  horizon_top_cm = 0,
  horizon_bottom_cm = 20,
  horizon_designation = "Ap",
  lookup_fn = lookup_soilgrids
)

Details

Test injection: pass lookup_fn = function(...) value to bypass the network when unit-testing.

Grade -> CSS class

Description

Grade -> CSS class

Usage

.grade_class(g)

Numeric attributes via mass-preserving spline

Description

Numeric attributes via mass-preserving spline

Usage

.harmonize_numeric_attrs(hz, attributes, depths, lam)

Single-horizon fallback: replicate values across overlapping GSM intervals

Description

Single-horizon fallback: replicate values across overlapping GSM intervals

Usage

.harmonize_single_horizon(p, hz, depths)

Has the field surveyor identified this diagnostic in NASIS?

Description

Looks at pedon$site$nasis_diagnostic_features for a featkind value matching pattern (case-insensitive regex). Returns FALSE when the slot is missing entirely (e.g. lab-only loaders, non-KSSL pedons).

Usage

.has_nasis_feature(pedon, pattern)

Arguments

Value

Logical scalar.

Great-circle distance (km) between (lat1, lon1) and the elementwise (lat2, lon2) vectors.

Description

Great-circle distance (km) between (lat1, lon1) and the elementwise (lat2, lon2) vectors.

Usage

.haversine_km(lat1, lon1, lat2, lon2)

Render the per-result card (one per classification system).

Description

Render the per-result card (one per classification system).

Usage

.html_classification_card(res)

Internal helper: .html_escape

Description

Internal helper: .html_escape

Usage

.html_escape(x)

Render the head section with embedded CSS.

Description

Render the head section with embedded CSS.

Usage

.html_head(title)

Render the horizons table from a PedonRecord.

Description

Render the horizons table from a PedonRecord.

Usage

.html_horizons_table(pedon)

Arguments

Render a provenance summary from a PedonRecord.

Description

Render a provenance summary from a PedonRecord.

Usage

.html_provenance_table(pedon)

Arguments

Render site metadata header.

Description

Render site metadata header.

Usage

.html_site_header(pedon)

Arguments

Render the cross-system summary table when multiple results are provided.

Description

Render the cross-system summary table when multiple results are provided.

Usage

.html_summary_table(results)

Alias 'reference_wrb_from_usda' -> 'reference_wrb' on KSSL pedons

Description

Internal helper used by both load_kssl_sample() and load_kssl_nasis_sample() since v0.9.91 to populate the canonical reference_wrb field from the KSSL-specific reference_wrb_from_usda cross-walk slot. Only sets the field when it is currently NULL, so explicit annotations are preserved.

Usage

.kssl_alias_reference_wrb(pedons)

Read + cache a KST13 JSON file

Description

Read + cache a KST13 JSON file

Usage

.kst13_load_cached(filename)

Resolve the path to a vendored canonical KST 13th JSON file

Description

Resolve the path to a vendored canonical KST 13th JSON file

Usage

.kst13_path(filename)

Resolve the local path of a v0.9.94 lazy-fetch cache file

Description

Internal helper used by every lazy-fetch loader (load_kssl_sample, load_kssl_nasis_sample, load_afsp_sample, load_wosis_stratified_sample). Looks in three places:

1. Bundled inst/extdata/<name>.rds (back-compat for developer checkouts and pre-v0.9.94 install paths).

2. User cache at tools::R_user_dir("soilKey", "data").

3. Returns NULL if neither exists – the caller then decides whether to prompt the user for an on-demand download.

Usage

.lazy_fetch_local_path(name)

Arguments

Value

Character path to a readable .rds file, or NULL if the cache is not yet present locally.

Read a lazy-fetch cache, downloading on first call if needed

Description

Internal entry point used by every lazy-fetch loader. Encapsulates the three-step resolution (bundled / user-cache / on-demand download with interactive prompt).

Usage

.lazy_fetch_readRDS(name)

Build the GitHub Release download URL for a lazy-fetch cache

Description

Build the GitHub Release download URL for a lazy-fetch cache

Usage

.lazy_fetch_url(name, release = .SOILKEY_LAZY_FETCH_RELEASE)

Coerce a LUCAS character cell to numeric, treating "< LOD" / "" as NA

Description

Coerce a LUCAS character cell to numeric, treating "< LOD" / "" as NA

Usage

.lucas_numeric(x)

Synthesise a small but realistic 5-horizon pedon for benchmarking

Description

Synthesise a small but realistic 5-horizon pedon for benchmarking

Usage

.make_synth_perf_pedon(i)

Merge two confusion matrices (table objects), padding union of labels

Description

Merge two confusion matrices (table objects), padding union of labels

Usage

.merge_confusion(a, b)

Modal categorical value by depth-overlap fraction

Description

Modal categorical value by depth-overlap fraction

Usage

.modal_by_overlap(values, top, bottom, depths)

Internal helper: .mollic_derived_aggregate

Description

Internal helper: .mollic_derived_aggregate

Usage

.mollic_derived_aggregate(tests, require_pass)

Internal helper: .mollic_derived_negative

Description

Internal helper: .mollic_derived_negative

Usage

.mollic_derived_negative(name, mol_res, note)

Internal helper: .normalise_results

Description

Internal helper: .normalise_results

Usage

.normalise_results(x, pedon = NULL)

Plausibility ranges for OSSL-backed soil property predictions

Description

Used by predict_ossl_mbl, predict_ossl_plsr_local and predict_ossl_pretrained to clip implausible values and to seed the synthetic-prediction fallback. Ranges follow the Open Soil Spectral Library (OSSL) global summary statistics.

Usage

.ossl_property_ranges()

Value

Named list of c(min, max) numeric pairs.

Parse a single Brazilian-style Munsell color string into hue/value/chroma

Description

Handles the FEBR / SiBCS-canonical "<matiz> <valor>/<croma>" format with PT-BR comma-decimal in any numeric component (e.g. "2,5YR 3/6" -> hue "2.5YR", value 3, chroma 6; "10YR 5,5/3,5" -> hue "10YR", value 5.5, chroma 3.5).

Usage

.parse_febr_munsell(s)

Details

Returns c(hue = NA_character_, value = NA_real_, chroma = NA_real_) when the input is empty / unparseable.

Vectorised Munsell-string parser

Description

Returns a data.frame with columns hue / value / chroma, one row per input string.

Usage

.parse_febr_munsell_vec(x)

Per-class recall data.frame from a confusion matrix

Description

Per-class recall data.frame from a confusion matrix

Usage

.per_class_from_confusion(cm)

MBL via resemble::mbl

Description

Wraps resemble::mbl so that the public predict_ossl_* wrappers stay short. Returns a data.table with the canonical schema. Only invoked when both resemble and a populated ossl_library are present.

Usage

.predict_ossl_mbl_resemble(X, properties, k, ossl_library, ...)

Deterministic synthetic prediction (fallback)

Description

Generates predictions from a stable seed derived from the input spectra. Each (horizon, property) draw is a shifted, lightly noised centre within the property's plausibility range. Prediction intervals scale inversely with the row's spectral information content (here: 1 - clipped_variance). This is *not* a soil-physical model – it exists so that the v0.4 plumbing can be tested end-to-end without OSSL installed.

Usage

.predict_synthetic(X, properties, region, k, method_label)

Stub-NA qualifier that exists in NAMESPACE but reports missing data

Description

For Tier-3 qualifiers requiring schema fields not yet on the horizon_column_spec() or site-level lists. The audit picks the function up as "implemented", and downstream code that calls it gets a NA-passed result with a clear 'missing' listing.

Usage

.q_stub_na(name, missing_fields, reference)

Volume-weighted mean of a horizon attribute over a depth window

Description

Volume-weighted mean of a horizon attribute over a depth window

Usage

.q_weighted_mean(values, top, bottom, window_top = 0, window_bottom = 100)

Test "X within depth d cm" given an existing diagnostic

Description

Many WRB sub-qualifiers (Endo-, Bathy-, Hyper-, Pano-, Ortho-, Ano-, etc.) are depth-bounded modifiers of an existing principal qualifier or diagnostic horizon. This helper tests whether the base diagnostic fires AND has any of its passing layers in the given depth window.

Usage

.q_within_depth(name, base_diag, pedon, top_cm, bottom_cm)

Query WoSIS GraphQL for the nearest WRB-labeled profile.

Description

Returns NULL on transport failure; NA fields when the bbox has no labeled WoSIS profile.

Usage

.query_nearest_wosis_wrb(
  lat,
  lon,
  max_distance_km,
  endpoint = "https://graphql.isric.org/wosis/graphql",
  verbose = FALSE
)

Normalise a Portuguese SiBCS label to a plural-canonical comparison key

Description

Normalise a Portuguese SiBCS label to a plural-canonical comparison key

Usage

.redape_canonical_label(s, pluralise = TRUE)

Compose the canonical reference label for a given SiBCS level

Description

Concatenates the relevant Redape reference fields (singular Portuguese nominal phrase) and applies plural-canonical normalisation so the result is comparable to the soilKey predicted label (e.g.\ "Argissolos Amarelos Distroficos abrupticos").

Usage

.redape_compose_ref(pedon, level)

Extract the predicted label at a given SiBCS level from a classify_sibcs() result

Description

Extract the predicted label at a given SiBCS level from a classify_sibcs() result

Usage

.redape_extract_pred(res, level)

Details

The returned label is a ClassificationResult field for the requested level (Order / Subordem / Grande Grupo / Subgrupo).

Convert one Redape GeoTab horizon record to a soilKey horizon row

Description

Convert one Redape GeoTab horizon record to a soilKey horizon row

Usage

.redape_horizon_to_soilkey(h)

Convert one Redape GeoTab item to a soilKey PedonRecord

Description

Convert one Redape GeoTab item to a soilKey PedonRecord

Usage

.redape_item_to_pedon(item)

Pluralise a single Portuguese token using SiBCS conventions

Description

Rules:

• Tokens of <= 2 chars are kept as-is (abbreviations like "tb"/"ta" used in SiBCS Cambissolo activity modifiers).

• Tokens already ending in "s" are kept as-is.

• Otherwise: append "s" (covers all -o, -ico, -oso, -eo, -io endings present in SiBCS Order, Subordem, GG, and Subgrupo modifiers; -al / -el / -ol words don't appear in the SiBCS taxonomy at these levels).

Usage

.redape_pluralise_pt(w)

Read a single Redape GeoTab JSON file

Description

The Redape JSON format wraps profiles in {"items": [{...}]}. Some files in the published dataset have a stray trailing brace that breaks strict JSON parsers; this helper tolerates it.

Usage

.redape_read_json(path)

Arguments

Value

List of items (typically length 1).

Strip Portuguese accents and lowercase / collapse whitespace

Description

Internal helper used by the Redape benchmark to canonicalise SiBCS labels before string comparison. Maps accented Latin letters to their ASCII equivalents (A-acute, O-tilde, C-cedilla, etc., for all five Portuguese vowel classes).

Usage

.redape_strip_accents(s)

Reduce X (library + query) to a small score space.

Description

Reduce X (library + query) to a small score space.

Usage

.reduce_for_neighbours(X_lib, X_query, y_label)

Resolve the regional subset code for an OSSL query

Description

Currently a thin pass-through; reserved for future remapping (e.g. "south_america" -> ISRIC region tag). Validates the spelling.

Usage

.resolve_region(region)

Internal helper: .rmd_classification_block

Description

Internal helper: .rmd_classification_block

Usage

.rmd_classification_block(res)

Internal helper: .rmd_header

Description

Internal helper: .rmd_header

Usage

.rmd_header(title)

Internal helper: .rmd_horizons_block

Description

Internal helper: .rmd_horizons_block

Usage

.rmd_horizons_block(pedon)

Arguments

Internal helper: .rmd_site_block

Description

Internal helper: .rmd_site_block

Usage

.rmd_site_block(pedon)

Arguments

Internal helper: .rmd_summary_block

Description

Internal helper: .rmd_summary_block

Usage

.rmd_summary_block(results)

Map an RSG code to a human-readable class name in the requested classification system.

Description

Map an RSG code to a human-readable class name in the requested classification system.

Usage

.rsg_name_for_system(code, system)

Hash-derived seed from a numeric matrix

Description

Produces a deterministic 32-bit integer seed from the contents of a numeric matrix so that synthetic predictions are reproducible per input spectrum without relying on global RNG state.

Usage

.seed_from_matrix(X)

Savitzky-Golay 1st derivative

Description

Delegates to prospectr::savitzkyGolay when available (m = 1, polynomial p, window w). The native fallback uses the closed-form 5-point coefficients (-2, -1, 0, 1, 2) / 10, which is the SG solution for w = 5, p = 2, m = 1, and trims two columns from each edge. For w != 5 the native path falls back to a generic SG coefficient computation via least squares.

Usage

.sg1(X, w = 5L, p = 2L)

Compute Savitzky-Golay coefficients for a derivative

Description

Solves the standard SG least-squares system to derive the kernel coefficients for a given window w, polynomial p, and derivative order m. Used only when prospectr is unavailable.

Usage

.sg_coefficients(w, p, m)

Map clay_films_amount (few/common/many) to SmartSolos CEROSIDADE_QUANTIDADE (1..3).

Description

Map clay_films_amount (few/common/many) to SmartSolos CEROSIDADE_QUANTIDADE (1..3).

Usage

.smartsolos_clay_films_amt(x)

Map clay_films_strength to SmartSolos CEROSIDADE_GRAU (1..3).

Description

Map clay_films_strength to SmartSolos CEROSIDADE_GRAU (1..3).

Usage

.smartsolos_clay_films_strength(x)

Convert one PedonRecord to the SmartSolosExpert request payload

Description

Builds the JSON-serialisable list expected by the POST /classification (or /verification) endpoint. Missing soilKey horizon attributes are sent as NA (the API tolerates partial data and replies with NULL for taxonomic levels that cannot be resolved).

Usage

.smartsolos_pedon_to_payload(pedon, drenagem = NULL, reference_sibcs = NULL)

Arguments

Convert a SmartSolosExpert response to a soilKey ClassificationResult

Description

Convert a SmartSolosExpert response to a soilKey ClassificationResult

Usage

.smartsolos_response_to_result(resp, pedon, endpoint)

Map a soilKey structure_grade string to the SmartSolos integer (ESTRUTURA_GRAU: 1=fraca, 2=moderada, 3=forte).

Description

Map a soilKey structure_grade string to the SmartSolos integer (ESTRUTURA_GRAU: 1=fraca, 2=moderada, 3=forte).

Usage

.smartsolos_struct_grade(x)

Map structure_size (very fine .. very coarse) to SmartSolos ESTRUTURA_TAMANHO (1..5).

Description

Map structure_size (very fine .. very coarse) to SmartSolos ESTRUTURA_TAMANHO (1..5).

Usage

.smartsolos_struct_size(x)

Map structure_type to SmartSolos ESTRUTURA_TIPO (1..6).

Description

Map structure_type to SmartSolos ESTRUTURA_TIPO (1..6).

Usage

.smartsolos_struct_type(x)

Standard Normal Variate transform

Description

Per-row centring and scaling: (x - rowMeans) / rowSds. Uses prospectr::standardNormalVariate when available, otherwise a native vectorised implementation. Returns a matrix of the same shape as the input.

Usage

.snv(X)

Canonical SoilGrids 250m unit-conversion factor per property

Description

SoilGrids stores integer rasters; the published conversion factors are documented in Hengl et al. (2017) and the SoilGrids README. This internal lookup table applies the right factor so lookup_soilgrids returns conventional units.

Usage

.soilgrids_scale(property)

Arguments

Value

Numeric scalar. The native integer value times this scale yields the conventional unit:

• clay/sand/silt – 0.1 (g/kg integer -> percent)

• phh2o – 0.1 (pH * 10 integer -> pH)

• soc – 0.1 (dg/kg integer -> g/kg)

• bdod – 0.01 (cg/cm^3 integer -> g/cm^3)

• cec – 0.1 (mmol(c)/kg integer -> cmol(c)/kg)

• nitrogen – 0.01 (cg/kg integer -> g/kg)

• ocd – 0.1 (hg/m^3 integer -> kg/m^3)

• ocs – 0.1 (hg/m^2 integer -> kg/m^2)

• cfvo – 0.1 (cm^3/dm^3 integer -> percent vol)

Look up the package version, falling back gracefully when soilKey is not installed (e.g. during interactive development with 'sys.source()').

Description

Look up the package version, falling back gracefully when soilKey is not installed (e.g. during interactive development with 'sys.source()').

Usage

.soilkey_version()

Internal helper: .subtest_result

Description

Internal helper: .subtest_result

Usage

.subtest_result(
  passed,
  layers = integer(0),
  missing = character(0),
  details = NULL,
  notes = NA_character_
)

Three-valued ALL across a logical vector, NA-aware

Description

Returns FALSE if any element is exactly FALSE; TRUE if every element is exactly TRUE; NA if no FALSE but at least one NA. Used inside SiBCS pendente diagnostics that combine per-layer tests with proper propagation.

Usage

.three_valued_all(x)

Canonical attribute ranges per class, used as the "what-to-confirm" appendix.

Description

Canonical attribute ranges per class, used as the "what-to-confirm" appendix.

Usage

.typical_attribute_table(system, codes)

Normalize a WRB RSG name to its plural canonical form so lookups work whether the source supplied "Ferralsol" or "Ferralsols".

Description

Normalize a WRB RSG name to its plural canonical form so lookups work whether the source supplied "Ferralsol" or "Ferralsols".

Usage

.wrb_canonical_plural(rsg)

Translate a WRB-RSG probability distribution to SiBCS-Ordem probabilities via Schad (2023) Annex Table 1 / SiBCS 5ª ed. Annex A. Many-to-many: a single WRB RSG may map to multiple SiBCS ordens (we split the probability evenly).

Description

Translate a WRB-RSG probability distribution to SiBCS-Ordem probabilities via Schad (2023) Annex Table 1 / SiBCS 5ª ed. Annex A. Many-to-many: a single WRB RSG may map to multiple SiBCS ordens (we split the probability evenly).

Usage

.wrb_to_sibcs_distribution(dist)

Modal SiBCS Ordem for a WRB RSG (1:1 picked by Schad 2023). Accepts either the singular ("Ferralsol") or plural ("Ferralsols") form – WoSIS, the WRB book, and OSSL all use slightly different conventions.

Description

Modal SiBCS Ordem for a WRB RSG (1:1 picked by Schad 2023). Accepts either the singular ("Ferralsol") or plural ("Ferralsols") form – WoSIS, the WRB book, and OSSL all use slightly different conventions.

Usage

.wrb_to_sibcs_modal_ordem(rsg)

Modal USDA Order for a WRB RSG (Schad 2023 Annex Table 1). Accepts either the singular ("Ferralsol") or plural ("Ferralsols") form.

Description

Modal USDA Order for a WRB RSG (Schad 2023 Annex Table 1). Accepts either the singular ("Ferralsol") or plural ("Ferralsols") form.

Usage

.wrb_to_usda_modal_order(rsg)

Internal helper: serialise the schema and write it to disk.

Description

Called by data-raw / build scripts only – not exported. The caller must pass an explicit destination path so we never write into the user's working directory or home filespace by default.

Usage

.write_pedon_schema_to_disk(path)

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

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

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

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

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

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

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.

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

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

Acric Subgroup helper (Andisols Acrudoxic / Acraquoxic / Acrustoxic / etc.)

Description

Pass when the sum of extractable bases (NH4OAc) plus 1N KCl-Al is < 2.0 cmol(+)/kg in fine earth, in a 30+ cm layer between 25 and 100 cm. v0.8 proxy: ECEC <= 2.0 in B horizons.

Usage

acric_andisol_usda(pedon)

Arguments

Acric Oxisol Suborder helper (Acroperox/Acrudox/Acrustox/Acraquox) Pass when oxic or kandic horizon has ECEC < 1.5 cmol/kg clay AND pH (KCl) >= 5.0.

Description

Acric Oxisol Suborder helper (Acroperox/Acrudox/Acrustox/Acraquox) Pass when oxic or kandic horizon has ECEC < 1.5 cmol/kg clay AND pH (KCl) >= 5.0.

Usage

acric_oxisol_usda(pedon)

Arguments

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

Aeric Subgroup (for Oxisols Aquox) – chroma-3 below epipedon Already defined for Aquods; here we add Oxisol-specific variant (any 10+ cm horizon below A with chroma >= 3 in 50%+ peds).

Description

Aeric Subgroup (for Oxisols Aquox) – chroma-3 below epipedon Already defined for Aquods; here we add Oxisol-specific variant (any 10+ cm horizon below A with chroma >= 3 in 50%+ peds).

Usage

aeric_oxisol_usda(pedon)

Arguments

Aeric Subgroup helper (Aquods) Pass when ochric epipedon is present (vs. histic/umbric/etc).

Description

Aeric Subgroup helper (Aquods) Pass when ochric epipedon is present (vs. histic/umbric/etc).

Usage

aeric_subgroup_usda(pedon)

Arguments

Aggregate alternative-path subtests with OR semantics

Description

Each "path" is a named list of subtests that combine with AND (intersect their layers). Paths combine with OR: the diagnostic passes if any path passes; passing layers are the union across passing paths; missing attributes are unioned across all paths that did not pass and reported NA. Used by diagnostics where WRB specifies several alternative qualifying conditions.

Usage

aggregate_alternatives(paths)

Arguments

Value

A list with elements passed, layers, missing, and passing_path (the name of the first path that passed, or NA_character_).

Aggregate sub-test results into a passed/missing summary

Description

Used by every diagnostic-level function. layers_passing is the intersection of layers across the listed sub-tests; passed is TRUE if that intersection is non-empty, NA if no test could be evaluated and missing attributes were reported, and FALSE otherwise.

Usage

aggregate_subtests(tests, layer_tests = NULL, exclusions = character(0))

Aluminum-rich spodic helper (Alaquods, Alorthods, KST Ch 14)

Description

Pass when the spodic horizon has < 0.10% Fe (oxalate) in 75%+ of layers, OR Al >= 3 * Fe in 75%+ of layers (Alaquods only).

Usage

al_rich_spodic_usda(pedon)

Arguments

Value

A DiagnosticResult.

Albic-over-argillic qualifying (Albaquults) Pass when albic horizon overlies an argillic horizon directly.

Description

Albic-over-argillic qualifying (Albaquults) Pass when albic horizon overlies an argillic horizon directly.

Usage

albaquult_qualifying_usda(pedon)

Arguments

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

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.

Albic horizon (USDA, KST 13ed Ch 3)

Description

Pass when an albic horizon (light-colored, eluvial; chroma <= 2, value >= 4) >= 1 cm thick is present. Delegates to WRB albic diagnostic.

Usage

albic_horizon_usda(pedon)

Arguments

Value

A DiagnosticResult.

Albic Subgroup helper (Albaquultic / Albaquic)

Description

Albic Subgroup helper (Albaquultic / Albaquic)

Usage

albic_subgroup_usda(pedon)

Arguments

Albolls qualifier: mollic + albic + argillic.

Description

Albolls qualifier: mollic + albic + argillic.

Usage

alboll_qualifying_usda(pedon)

Arguments

Alfic Subgroup helper (Spodosols): argillic or kandic with BS >= 35%

Description

Alfic Subgroup helper (Spodosols): argillic or kandic with BS >= 35%

Usage

alfic_subgroup_usda(pedon)

Arguments

Alfisol Order qualifier Pass when argillic OR kandic horizon present + BS >= 35% in some part.

Description

Alfisol Order qualifier Pass when argillic OR kandic horizon present + BS >= 35% in some part.

Usage

alfisol_qualifying_usda(pedon)

Arguments

Alfisols (USDA Cap 5): argillic/kandic/natric horizon + base saturation >= 35% at the implicit reference depth.

Description

Alfisols (USDA Cap 5): argillic/kandic/natric horizon + base saturation >= 35% at the implicit reference depth.

Usage

alfisol_usda(pedon)

Arguments

Alic Subgroup helper (Andisols) Pass when al_kcl_cmol > 2.0 in a 10+ cm layer between 25 and 50 cm.

Description

Alic Subgroup helper (Andisols) Pass when al_kcl_cmol > 2.0 in a 10+ cm layer between 25 and 50 cm.

Usage

alic_andisol_usda(pedon)

Arguments

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.

Andic soil properties (USDA, KST 13ed Ch 3, p 32)

Description

Soil materials with one or both of the following:

• bulk_density <= 0.90 g/cm3 AND Al + 0.5*Fe (oxalate) >= 2.0% AND phosphate_retention >= 85%; OR

• Al + 0.5*Fe (oxalate) >= 0.4% AND phosphate_retention >= 25% AND volcanic_glass_pct varying with the texture-class proxy (deferred – requires fine-earth fraction analysis).

Usage

andic_soil_properties_usda(pedon)

Arguments

Details

Implementation (v0.8.6): primary "humic-andic" branch (bd <= 0.9 + Al+0.5Fe >= 2 + Pret >= 85). The vitric-andic branch (lower Al+Fe but high glass content) is partially captured.

Value

A DiagnosticResult.

References

Soil Survey Staff (2022), KST 13ed, Ch. 3, p 32.

Andic Subgroup helper (USDA, KST 13ed)

Description

Pass when, throughout one or more horizons with total thickness >= 18 cm within 75 cm of the surface:

• bulk_density_g_cm3 <= 1.0 (at 33 kPa); AND

• Al + 0.5 * Fe (oxalate-extractable) > 1.0 percent.

KST 13ed, p 117 (Andisols core, applies to subgroup criteria too).

Usage

andic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

Andisol Order qualifier (USDA, KST 13ed Ch 3, p 7)

Description

Andisols have andic soil properties in 60%+ of the thickness between the surface and either:

• a depth of 60 cm; or

• a densic, lithic, or paralithic contact, a duripan, or a petrocalcic horizon (whichever is shallower).

v0.8.6 implementation: pass when total thickness of layers with andic_soil_properties is >= 0.6 * (depth from surface to 60 cm).

Usage

andisol_qualifying_usda(pedon)

Arguments

Value

A DiagnosticResult.

References

Soil Survey Staff (2022), KST 13ed, Ch. 6, p 117.

Andisols (USDA Cap 6): andic soil properties >= 60% of thickness.

Description

Andisols (USDA Cap 6): andic soil properties >= 60% of thickness.

Usage

andisol_usda(pedon)

Arguments

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)

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.

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.

Anhydrous conditions (USDA Soil Taxonomy, 13th edition)

Description

"Anhydrous conditions refer to the moisture condition of soils in very cold deserts and other areas with permafrost (often dry permafrost). These soils typically have low precipitation (usually less than 50 mm water equivalent per year) and a moisture content of less than 3 percent by weight." – KST 13ed, Ch 3, p 33.

Usage

anhydrous_conditions_usda(pedon)

Arguments

Details

Required characteristics:

• Mean annual soil temperature <= 0 C; AND

• Layer 10-70 cm with soil temperature < 5 C throughout the year; AND

• No ice-impregnated permafrost in that layer; AND

• One of:

  • Dry (>= 1500 kPa) in 1/2+ of soil for 1/2+ of time above 0 C; OR

  • Rupture-resistance class loose to slightly hard throughout when temp <= 0 C (except where pedogenically cemented).

Implementation (v0.8.x): Uses permafrost_temp_C from schema to flag layers below freezing; checks rupture_resistance for "loose" / "soft" / "slightly hard" in the 10-70 cm layer. Precipitation criterion is deferred to v0.9 (climatic data).

Value

A DiagnosticResult.

References

Soil Survey Staff (2022), KST 13ed, Ch. 3, p 33.

Anionic Subgroup helper (Oxisols)

Description

Pass when delta pH (KCl - water) is 0 or net positive in a 18+ cm layer within 125 cm. Indicates exchange complex dominated by positive-charge minerals (Fe/Al oxides).

Usage

anionic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

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

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.

Apply a parsed horizons-extraction result to a pedon

Description

Walks the horizons array of a parsed extraction response, creating / matching horizon rows and recording each non-null attribute via pedon$add_measurement(... source = "extracted_vlm").

Usage

apply_horizons_extraction(
  pedon,
  parsed,
  overwrite = FALSE,
  source_label = "extracted_vlm"
)

Arguments

Details

Returns the count of provenance entries added.

Apply a parsed site-extraction result to a pedon

Description

Site metadata is not under provenance control (PedonRecord$site is a free-form list, not a column with an authority-ranked log). We therefore set the missing fields directly and emit a provenance entry against horizon_idx 0 (sentinel for "site-level") only when there is at least one horizon to anchor it.

Usage

apply_site_extraction(pedon, parsed, overwrite = FALSE)

Arguments

Details

For attributes that already exist in pedon$site, we leave them alone unless overwrite = TRUE. The VLM contract (extracted_vlm < measured) is preserved by attribute origin: a user-built site list is treated as authoritative; an empty / NULL field can be filled by the VLM.

Aqualf Suborder qualifier (aquic conditions in argillic Alfisol).

Description

Aqualf Suborder qualifier (aquic conditions in argillic Alfisol).

Usage

aqualf_qualifying_usda(pedon)

Arguments

Aquands Suborder qualifier (Cap 6, p 117) Pass when histic OR aquic conditions in 40-50 cm with redox features. Simplified: histic OR aquic_conditions(max_top=50).

Description

Aquands Suborder qualifier (Cap 6, p 117) Pass when histic OR aquic conditions in 40-50 cm with redox features. Simplified: histic OR aquic_conditions(max_top=50).

Usage

aquand_qualifying_usda(pedon)

Arguments

Aquandic Subgroup helper (Spodosols / others) Aquic + Andic.

Description

Aquandic Subgroup helper (Spodosols / others) Aquic + Andic.

Usage

aquandic_subgroup_usda(pedon)

Arguments

Aquent Suborder qualifier (Entisol with aquic conditions <50 cm).

Description

Aquent Suborder qualifier (Entisol with aquic conditions <50 cm).

Usage

aquent_qualifying_usda(pedon)

Arguments

Aquept Suborder qualifier

Description

Aquept Suborder qualifier

Usage

aquept_qualifying_usda(pedon)

Arguments

Aquerts qualifier (Vertisols with aquic conditions) Pass when aquic_conditions within 50 cm.

Description

Aquerts qualifier (Vertisols with aquic conditions) Pass when aquic_conditions within 50 cm.

Usage

aquert_qualifying_usda(pedon)

Arguments

Aquic conditions (USDA Soil Taxonomy, 13th edition)

Description

"Soils with aquic conditions are those that currently undergo continuous or periodic saturation and reduction. The presence of these conditions is indicated by redoximorphic features, except in Histosols and Histels." – KST 13ed, Ch 3, p 41.

Usage

aquic_conditions_usda(
  pedon,
  max_top_cm = 100,
  min_redox_pct = 5,
  max_chroma = 2
)

Arguments

Details

Three types of saturation are defined:

• Endosaturation: saturated in all layers from the upper boundary of saturation to >=200 cm.

• Episaturation: saturated in one or more layers within 200 cm with unsaturated layer(s) below.

• Anthric saturation: cultivated/flood-irrigated.

Implementation (v0.8.x):

• Saturation is inferred from the presence of redoximorphic features (redoximorphic_features_pct >= 5) and/or a glei horizon (designation containing 'g').

• Reduction is inferred when chroma <= 2 in the matrix.

• Artificial drainage is treated as positive aquic when site$artificially_drained == TRUE (deferred – not in current schema).

Value

A DiagnosticResult with evidence$saturation_type = "endo" / "epi" / NA.

References

Soil Survey Staff (2022), KST 13ed, Ch. 3, pp 41-44.

Aquic Subgroup helper (within 100 cm of mineral soil surface)

Description

Aquic Subgroup helper (within 100 cm of mineral soil surface)

Usage

aquic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

Aquolls qualifier (aquic conditions in mollic).

Description

Aquolls qualifier (aquic conditions in mollic).

Usage

aquoll_qualifying_usda(pedon)

Arguments

Aquult Suborder qualifier Pass when aquic_conditions within 50 cm.

Description

Aquult Suborder qualifier Pass when aquic_conditions within 50 cm.

Usage

aquult_qualifying_usda(pedon)

Arguments

Arenic / Grossarenic Subgroup helper (Spodosols)

Description

Pass when texture class (fine-earth fraction) is sandy throughout from the surface to the top of the spodic horizon AND the spodic top depth falls in [min_spodic_top, max_spodic_top].

Usage

arenic_subgroup_usda(pedon, min_spodic_top = 75, max_spodic_top = 125)

Arguments

Details

Standard cuts: - "Arenic": 75-125 cm - "Grossarenic": 125+ cm (use min_spodic_top=125, max=Inf)

Value

A DiagnosticResult.

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.

Argic Aridisol helper – argillic-or-kandic in Argids/Cryids/etc.

Description

Argic Aridisol helper – argillic-or-kandic in Argids/Cryids/etc.

Usage

argic_aridisol_usda(pedon)

Arguments

Argic Mollisol Suborder helper – delegates argillic_within_usda.

Description

Argic Mollisol Suborder helper – delegates argillic_within_usda.

Usage

argic_mollisol_usda(pedon)

Arguments

Argic Subgroup helper (Endoaquods/Fragiaquods): argillic or kandic. Synonym of ultic at this level. Re-exported for naming clarity.

Description

Argic Subgroup helper (Endoaquods/Fragiaquods): argillic or kandic. Synonym of ultic at this level. Re-exported for naming clarity.

Usage

argic_subgroup_usda(pedon)

Arguments

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).

Argillic-or-Kandic helper (USDA, used in Spodosols Subgroups)

Description

Pass when EITHER an argillic OR a kandic horizon is present within max_top_cm.

Usage

argillic_or_kandic_usda(pedon, max_top_cm = 200, min_bs = NULL)

Arguments

Value

A DiagnosticResult.

Argillic horizon (USDA Soil Taxonomy)

Description

v0.2 scaffold delegating to WRB argic. The two diagnostics' clay-increase rules are essentially the same; USDA argillic additionally requires evidence of clay illuviation (clay films / clay bridges) on at least 1% of the surface area, which v0.8 will enforce against the clay_films_amount column.

Usage

argillic_usda(pedon, ...)

Arguments

Value

A DiagnosticResult.

References

Soil Survey Staff (2014), Keys to Soil Taxonomy, Ch. 3 – argillic horizon.

Argillic horizon helper (USDA, KST 13ed Ch 3)

Description

Wrapper around argillic_usda that simply re-exports the DiagnosticResult with a max-depth check (default 100 cm for Argiorthels Subgroup keys).

Usage

argillic_within_usda(pedon, max_top_cm = 100)

Arguments

Value

A DiagnosticResult.

Argissolos (SiBCS Cap 4, p 114; conceito Cap 3, p 86-88)

Description

Horizonte B textural – catch-all final na chave SiBCS apos Luvissolos / Nitossolos terem sido excluidos. v0.7 enforce: B textural + (argila ativ baixa OR ativ alta + V baixa OR carater alumínico).

Usage

argissolo(pedon)

Arguments

Argissolos Acinzentados (SiBCS Cap 5)

Description

Matiz \>= 7.5YR, valor \>= 5, croma \< 4 (cores mais cinzentas / palidas), na maior parte do B (inclusive BA).

Usage

argissolo_acinzentado(pedon)

Arguments

Argissolos Amarelos (SiBCS Cap 5)

Description

Matiz \>= 7.5YR (mais amarelo) na maior parte do B, sem ser Acinzentado (croma \>= 4).

Usage

argissolo_amarelo(pedon)

Arguments

Argissolos Bruno-Acinzentados (SiBCS Cap 5)

Description

Argissolos com horizonte B textural, com matiz \>= 5YR e cor escura (valor \<= 4 + croma \<= 4 umidos) na maior parte do B (inclusive BA).

Usage

argissolo_bruno_acinzentado(pedon)

Arguments

Argissolos Vermelhos (SiBCS Cap 5)

Description

Matiz \<= 2.5YR (mais vermelho) na maior parte do B.

Usage

argissolo_vermelho(pedon)

Arguments

Argissolos Vermelho-Amarelos (catch-all dos Argissolos)

Description

Argissolos Vermelho-Amarelos (catch-all dos Argissolos)

Usage

argissolo_vermelho_amarelo(pedon)

Arguments

Aridisol Order qualifier (USDA, KST 13ed, Ch 2) Pass when the soil has aridic SMR AND any one of: argillic, natric, kandic, calcic, petrocalcic, gypsic, petrogypsic, salic, duripan, cambic, sulfuric horizon. Also requires no other prior order match.

Description

Aridisol Order qualifier (USDA, KST 13ed, Ch 2) Pass when the soil has aridic SMR AND any one of: argillic, natric, kandic, calcic, petrocalcic, gypsic, petrogypsic, salic, duripan, cambic, sulfuric horizon. Also requires no other prior order match.

Usage

aridisol_qualifying_usda(pedon)

Arguments

Aridisols (USDA Cap 7): aridic moisture regime + ochric/anthropic + subsurface diagnostic. v0.8 simplification: detected via aridity proxies (low EC OR salic OR caracter combinations) + non-mollic surface + low OC (no organic accumulation).

Description

Aridisols (USDA Cap 7): aridic moisture regime + ochric/anthropic + subsurface diagnostic. v0.8 simplification: detected via aridity proxies (low EC OR salic OR caracter combinations) + non-mollic surface + low OC (no organic accumulation).

Usage

aridisol_usda(pedon)

Arguments

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

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

if (requireNamespace("aqp", quietly = TRUE)) {
  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
}

Coerce a chat response to a single character scalar

Description

ellmer chat objects' $chat() method returns a character vector (possibly with class attributes for ANSI). The MockVLMProvider returns a plain string. This helper normalises both shapes.

Usage

as_chat_text(x)

Atividade da fracao argila (SiBCS Cap 1, p 30)

Description

Calcula a atividade da fracao argila Ta = CEC * 1000 / argila (em cmolc/kg de argila, sem correcao para carbono) por horizonte e classifica como **alta (Ta)** se >= 27 cmolc/kg argila ou **baixa (Tb)** se < 27. Nao se aplica a texturas areia / areia franca.

Usage

atividade_argila_alta(pedon, min_ta = 27)

Arguments

Details

Para distincao de classes pelo SiBCS, considera-se a atividade no horizonte B (incl. BA, exc. BC) ou no horizonte C (incl. CA), quando nao existe B.

Value

Um DiagnosticResult; passed = TRUE sse pelo menos um horizonte B ou C tem Ta. layers = horizontes com atividade alta (Ta).

References

Embrapa (2018), SiBCS 5a ed., Cap 1, "Atividade da fracao argila", p. 30.

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

csv_path <- "RJ.csv"
if (file.exists(csv_path)) {
  peds <- load_bdsolos_csv(csv_path)
  a <- audit_argic_strong_films(peds, reference_filter = "LATOSSOLO")
  table(a$would_exclude_from_latossolo)
}

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

root <- file.path(tempdir(), "ESDB-Raster-Library-1k-GeoTIFF-20240507")
if (dir.exists(root)) {
  available_esdb_attributes(root)
}

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

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

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

# Requires a user-provided BDsolos CSV; guarded so the example
# no-ops on CRAN when the file is absent.
csv_path <- "RJ.csv"
if (file.exists(csv_path)) {
  peds <- load_bdsolos_csv(csv_path)
  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")
}

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

lucas_dir <- file.path(tempdir(), "LUCAS-SOIL-2018-v2")
esdb_dir  <- file.path(tempdir(), "ESDB-Raster-Library-1k-GeoTIFF-20240507")
if (dir.exists(lucas_dir) && dir.exists(esdb_dir)) {
  pedons <- load_lucas_soil_2018(lucas_dir, countries = "ES", max_n = 50)
  bench <- benchmark_lucas_2018(
    pedons,
    esdb_root = esdb_dir,
    fill_texture_from = "soilgrids")
  bench$accuracy
  bench$per_rsg
}

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

bench <- benchmark_performance(n = 5)
bench$summary

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,
  seed = NULL
)

Arguments

Value

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

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,
  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.

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

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.

Calcic horizon (USDA, delegates to WRB calcic).

Description

Calcic horizon (USDA, delegates to WRB calcic).

Usage

calcic_horizon_usda(pedon, max_top_cm = 100)

Arguments

Calcic Subgroup helper – delegates to calcic_horizon_usda within max_top_cm.

Description

Calcic Subgroup helper – delegates to calcic_horizon_usda within max_top_cm.

Usage

calcic_subgroup_usda(pedon, max_top_cm = 100)

Arguments

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.

Cambissolos (SiBCS Cap 4, p 113; conceito Cap 3, p 88-89)

Description

Horizonte B incipiente imediatamente abaixo de A ou histico < 40 cm, com plintita/petroplintita (se presente) que NAO satisfaca aos requisitos para Plintossolos.

Usage

cambissolo(pedon)

Arguments

Cambissolos Fluvicos (Cap 6): carater fluvico.

Description

Cambissolos Fluvicos (Cap 6): carater fluvico.

Usage

cambissolo_fluvico(pedon)

Arguments

Cambissolos Haplicos (catch-all).

Description

Cambissolos Haplicos (catch-all).

Usage

cambissolo_haplico(pedon)

Arguments

Cambissolos Histicos (Cap 6): horizonte histico sem espessura para Organossolo.

Description

Cambissolos Histicos (Cap 6): horizonte histico sem espessura para Organossolo.

Usage

cambissolo_histico(pedon)

Arguments

Cambissolos Humicos (Cap 6): horizonte A humico.

Description

Cambissolos Humicos (Cap 6): horizonte A humico.

Usage

cambissolo_humico(pedon)

Arguments

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.

Carater acrico (SiBCS Cap 1, p 31)

Description

Indica solos com balanca de cargas predominante eletropositiva ou eletricamente neutra. Discrimina Latossolos Acricos / Acriferricos no 3o nivel (Cap 10).

Usage

carater_acrico(pedon, max_ecec_clay = 1.5, min_delta_ph = 0)

Arguments

Details

Criterios canonicos (todos verificados em horizontes B):

1. \Delta pH = pH(KCl) - pH(H_2O) \ge 0 2. CECef por kg de argila \le 1.5 cmolc/kg argila

Value

DiagnosticResult; passed = TRUE se pelo menos um horizonte B satisfaz ambos os criterios.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, p 31; Cap 10 (Latossolos), pp 173-176.

Carater alitico (SiBCS Cap 1, p 32)

Description

Critérios canônicos: Al(extr) >= 4 cmolc/kg solo, saturacao por aluminio [100 * Al / (S + Al)] >= 50%, e saturacao por bases V < 50%. Avaliado no horizonte B (ou C, na ausencia de B).

Usage

carater_alitico(pedon, min_al = 4, min_al_sat = 50, max_v = 50)

Arguments

Carater arenico (SiBCS Cap 5)

Description

Solos com textura arenosa (clay% < max_clay_pct, default 15%) desde a superficie ate uma profundidade entre min_depth_cm e max_depth_cm (default 50-100 cm). Discrimina os Subgrupos arenicos de Argissolos (Cap 5: PAC, PA, PV, PVA) e Neossolos (Cap 12).

Usage

carater_arenico(
  pedon,
  max_clay_pct = 15,
  min_depth_cm = 50,
  max_depth_cm = 100
)

Arguments

Details

Implementacao: ordena horizontes por top_cm, identifica o PRIMEIRO horizonte com clay_pct >= max_clay_pct, e verifica que (a) todos os horizontes acima desse boundary sao arenosos (sem camada argilosa intercalada acima) e (b) o boundary (top_cm) cai no intervalo [min_depth_cm, max_depth_cm].

Para "espessarenicos" (boundary 100-200 cm), use carater_espessarenico (planejado v0.7.4.B.3).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5 (Argissolos), pp 120-138.

Carater argiluvico (SiBCS Cap 1; Cap 6)

Description

Solos com B textural (B_textural) em posicao NAO diagnostica para Argissolos, dentro de max_depth_cm. Discrimina os Subgrupos argissolicos de Cambissolos (Cap 6 CX 4.7.8, 4.10.5).

Usage

carater_argiluvico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao v0.7.5: requer B_textural passa em alguma camada com top_cm < max_depth_cm. Distingue-se de Argissolo pleno por contexto: chamado dentro de Cambissolos onde B incipiente (B_incipiente) ja definiu a ordem como Cambissolo.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 6, p 153.

Carater cambissolico (SiBCS Cap 14)

Description

Solos com B incipiente (B_incipiente) abaixo do horizonte hístico (H/O) ou A. Discrimina os Subgrupos cambissolicos de Organossolos Folicos (Cap 14, pp 247-248): Folicos Fibricos / Hemicos / Sapricos cambissolicos.

Usage

carater_cambissolico(pedon)

Arguments

Details

Implementado como uma interseccao de duas condicoes:

1. B_incipiente passa em ao menos um horizonte

2. Esse horizonte B incipiente esta abaixo de um horizonte H/O (hístico) ou A

Em pedons sem H/O ou A acima do B incipiente, o teste falha (B incipiente isolado nao caracteriza Organossolo Cambissolico).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 14, pp 247-248.

Carater cambissolico (Argissolos – Cap 5)

Description

Solos com 4% ou mais de minerais alteraveis visiveis E/OU 5% ou mais de fragmentos de rocha (coarse_fragments_pct) no horizonte B (exclusive BC ou B/C), dentro de max_depth_cm. Discrimina os Subgrupos cambissolicos de Argissolos PA (Cap 5, p 126) – DISTINTO do carater_cambissolico (Cap 14 Organossolos Folicos: B incipiente abaixo de histico/A).

Usage

carater_cambissolico_arg(pedon, min_coarse_pct = 5, max_depth_cm = 150)

Arguments

Details

Implementacao v0.7.4 (aproximacao): apenas coarse_fragments_pct \ge min_coarse_pct (default 5) eh testado. O criterio "minerais alteraveis visiveis" exigiria campo adicional no schema (e.g. weatherable_minerals_pct) que sera adicionado em release futura. Documentado como limitacao conhecida.

Value

DiagnosticResult.

References

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

Carater carbonatico (SiBCS Cap 1, p 33)

Description

>= 150 g/kg (15%) de CaCO3 equivalente em qualquer forma de segregacao (incl. nodulos, concrecoes). Excludente: nao satisfaz aos requisitos de horizonte calcico.

Usage

carater_carbonatico(pedon, min_caco3_pct = 15, max_depth_cm = NULL)

Arguments

Carater chernossolico (SiBCS Cap 5; A chernozemico + Ta alta)

Description

Solos com horizonte A chernozemico (horizonte_A_chernozemico) E atividade da argila \ge min_ta (default 20 cmolc/kg argila) na maior parte dos primeiros 100 cm do B (inclusive BA). Discrimina os Subgrupos chernossolicos de Argissolos (Cap 5: PV, PVA).

Usage

carater_chernossolico(pedon, min_ta = 20)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, p 134; Cap 7 (Chernossolos).

Carater coeso (SiBCS Cap 1, pp 32-33)

Description

Solos com horizontes coesos: muito duros a extremamente duros quando secos, friaveis a firmes quando umidos, decorrentes do empacotamento das particulas e/ou cimentacao. Discrimina os Grandes Grupos Distrocoesos / Eutrocoesos de Argissolos (Cap 5, pp 117-119) e Latossolos (Cap 10).

Usage

carater_coeso(pedon, max_depth_cm = 150)

Arguments

Details

Criterios canonicos:

• rupture_resistance \in{"very hard", "extremely hard"} (em estado seco)

• consistence_moist \in{"friable", "firm"} (em estado umido)

• Excluido: textura areia / areia franca (clay_pct < 15%)

Value

DiagnosticResult; passed = TRUE se ao menos uma camada (com textura suficiente) atende aos dois criterios de consistencia.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, pp 32-33; Cap 5 (Argissolos), pp 117-119.

Carater durico (SiBCS Cap 1)

Description

Solos com endurecimento por cimentacao parcial de silica (SiO2), insuficiente para qualificar como horizonte durico (duripa) completo. Detectado quando:

Usage

carater_durico(pedon, max_depth_cm = 150)

Arguments

Details

• duripan_pct > 0 (presenca de noduros / concrecoes de silica), OR

• cementation_class \in{"weakly", "moderately"} (cimentacao fraca a moderada, NAO indurada/strongly).

Discrimina os Subgrupos duricos / abrupticos duricos de Argissolos Acinzentados (Cap 5 PAC) e Latossolos com caracter durico (Cap 10).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 5 (Argissolos Acinzentados Distrocoesos abrupticos duricos), p 120.

Carater ebanico (SiBCS Cap 1; Cap 7 e Cap 17)

Description

Cor preta uniforme (value \le 3 e chroma \le 2 em umido) em TODO o horizonte B + atividade da argila alta (Ta) + saturacao por bases V% \ge 65. Discrimina Chernossolos Ebanicos (Cap 7) e Vertissolos Ebanicos (Cap 17) no 2o nivel.

Usage

carater_ebanico(pedon, max_value = 3, max_chroma = 2, min_v = 65)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 7 (Chernossolos), pp 144-148; Cap 17 (Vertissolos), pp 271-274.

Carater espessarenico (SiBCS Cap 5)

Description

Textura arenosa (clay% < max_clay_pct) da superficie ate boundary em [100, 200] cm. Variante "espessa" do carater_arenico.

Usage

carater_espessarenico(
  pedon,
  max_clay_pct = 15,
  min_depth_cm = 100,
  max_depth_cm = 200
)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, pp 130-131.

Carater espodico (SiBCS Cap 1, p 35; Cap 8)

Description

Evidencia iluvial de Al / Fe / materia organica em camada de pelo menos 2,5 cm de espessura, em quantidade insuficiente para qualificar como horizonte B espodico (B_espodico), mas suficiente para indicar espodicidade incipiente. Usado em Cambissolos / Argissolos / Plintossolos espodicos (Caps 5, 6 e 16) e em Espodossolos rasos (Cap 8).

Usage

carater_espodico(pedon, min_thickness = 2.5, min_oc_pct = 0.5)

Arguments

Details

Diferenca para B_espodico: thickness >= 2,5 cm em vez de exigir o gate completo de espessura espodica; OC >= 0,5% em vez do gate de iluviacao quantitativa; sinais de iluviacao Fe/Al (al_ox_pct ou fe_ox_pct ou fe_dcb_pct).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, p 35; Cap 8 (Espodossolos), pp 156-160.

Carater B espodico profundo (SiBCS Cap 8)

Description

Solos com horizonte B espodico cujo top_cm esta entre min_top_cm (default 200) e max_top_cm (default 400). Discrimina os Grandes Grupos Hiperespessos / Hidro-hiperespessos de Espodossolos (Cap 8 1.1, 1.3, 2.1, 2.3, 3.1, 3.3).

Usage

carater_espodico_profundo(pedon, min_top_cm = 200, max_top_cm = 400)

Arguments

Details

Implementacao: chama carater_espodico e filtra por top_cm no intervalo [min_top_cm, max_top_cm].

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 8, pp 165-168.

Carater eutrico (SiBCS Cap 1, p 35)

Description

Distinto de "eutrofico": exige pH(H2O) >= 5.7 conjugado com S (soma de bases) >= 2.0 cmolc/kg solo dentro da secao de controle.

Usage

carater_eutrico(pedon, min_pH = 5.7, min_s = 2)

Arguments

Carater ferrico (SiBCS Cap 1, p 35; Cap 5 e Cap 10)

Description

Teor de Fe2O3 (pelo ataque sulfurico-NaOH) entre 180 e 360 g/kg de solo (= 18%-36% mass) na maior parte dos primeiros 100 cm do horizonte B. Acima de 360 g/kg = "perferrico" (nao implementado aqui). Discrimina os Grandes Grupos Eutroferricos / Distroferricos / Aluminoferricos de Latossolos (Cap 10), Argissolos (Cap 5 Eutroferricos) e Cambissolos (Cap 6 Aluminoferricos).

Usage

carater_ferrico(
  pedon,
  min_fe2o3_pct = 18,
  max_fe2o3_pct = 36,
  max_depth_cm = 100
)

Arguments

Details

Implementacao v0.7.4: testa se algum horizonte B dentro de max_depth_cm atende ao intervalo. SiBCS estrito ("na maior parte de") seria uma media ponderada por espessura – refinamento planejado para v0.7.5.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1, p 35; Cap 5 (Argissolos Eutroferricos, p 118); Cap 10 (Latossolos).

Carater fluvico (SiBCS Cap 1, p 35-36): camadas estratificadas + distribuicao irregular de C organico. Reuso de fluvic_material (WRB).

Description

Carater fluvico (SiBCS Cap 1, p 35-36): camadas estratificadas + distribuicao irregular de C organico. Reuso de fluvic_material (WRB).

Usage

carater_fluvico(pedon)

Arguments

Carater gleissolico (SiBCS Cap 5; horizonte_glei em posicao nao-Gleissolo)

Description

Solos com horizonte glei (horizonte_glei) em posicao nao diagnostica para Gleissolos (i.e., dentro de max_depth_cm mas NAO satisfazendo os requisitos completos de Gleissolo). Discrimina os Subgrupos gleissolicos de Argissolos (Cap 5 PA), Cambissolos (Cap 6) e outros.

Usage

carater_gleissolico(pedon, max_depth_cm = 150)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, p 126; Cap 9 (Gleissolos).

Carater hidromorfico (SiBCS Cap 8)

Description

Solos saturados com agua em camada(s) dentro de max_depth_cm (default 100 cm), evidenciado por horizonte glei (horizonte_glei) OU caracter redoxico (carater_redoxico) OU horizonte Eg na designation OU acumulacao de Mn em horizonte E ou B espodico. Discrimina os Grandes Grupos Hidromorficos / Hidro-hiperespessos de Espodossolos (Cap 8 1.1, 1.2, 2.1, 2.2, 3.1, 3.2).

Usage

carater_hidromorfico(pedon, max_depth_cm = 100)

Arguments

Details

Implementacao v0.7.5 (aproximacao):

• horizonte_glei dentro de max_depth_cm, OR

• carater_redoxico ate max_depth_cm, OR

• designation pattern Eg dentro de max_depth_cm.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 8, pp 165-168.

Carater hipocarbonatico (SiBCS Cap 1, p 33): CaCO3 entre 50 e 150 g/kg.

Description

Carater hipocarbonatico (SiBCS Cap 1, p 33): CaCO3 entre 50 e 150 g/kg.

Usage

carater_hipocarbonatico(pedon, max_depth_cm = NULL)

Arguments

Carater espesso-humico (SiBCS Cap 5, p 119)

Description

Solos com horizonte A humico e conteudo de carbono >= min_oc_pct (default 1% = 10 g/kg) extendendo-se ate min_depth_cm (default 80 cm) ou mais de profundidade. Discrimina os Subgrupos "espesso-humicos" de Argissolos Bruno-Acinzentados Ta Aluminicos (Cap 5 PBAC 1.1.2) – camadas humosas espessas tipicas de Argissolos do RS.

Usage

carater_humico_espesso(pedon, min_oc_pct = 1, min_depth_cm = 80)

Arguments

Details

Implementacao: requer (1) horizonte_A_humico passa AND (2) ha camada com oc_pct >= min_oc_pct cuja bottom_cm >= min_depth_cm.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5 (Argissolos), p 119.

Carater latossolico (SiBCS Cap 5)

Description

Solos com horizonte B latossolico (B_latossolico) abaixo do horizonte B textural (B_textural), dentro de max_depth_cm (default 150 cm). Discrimina os Subgrupos latossolicos de Argissolos (Cap 5: PAC, PA, PV, PVA) – transicao entre Argissolo e Latossolo dentro do mesmo perfil.

Usage

carater_latossolico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao: requer (1) B_textural() passa, (2) B_latossolico() passa, e (3) ao menos uma camada com B latossolico tem top_cm maior que o top_cm maximo das camadas com B textural (i.e., latossolico ocorre abaixo).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5 (Argissolos), pp 121-138.

Carater leptico (SiBCS Cap 5; contato litico em 50-100 cm)

Description

Solos com contato litico (contato_litico) a profundidade entre 50 e 100 cm. Discrimina os Subgrupos lepticos de Argissolos (Cap 5: PA, PV, PVA).

Usage

carater_leptico(pedon, min_depth_cm = 50, max_depth_cm = 100)

Arguments

Details

Implementacao: chama contato_litico(pedon) sem bound, depois filtra layers para top em [min_depth_cm, max_depth_cm].

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, pp 127, 132.

Carater leptofragmentario (SiBCS Cap 5; Cr / fragmentary 50-100 cm)

Description

Solos com contato litico fragmentario (Cr / Crf) a profundidade entre 50 e 100 cm. Discrimina os Subgrupos leptofragmentarios de Argissolos (Cap 5: PA, PV, PVA).

Usage

carater_leptofragmentario(pedon, min_depth_cm = 50, max_depth_cm = 100)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, pp 127, 132.

Carater luvissolico (SiBCS Cap 5; Ta + S alta)

Description

Solos com atividade da argila \ge min_ta (default 20 cmolc/kg argila) E soma de bases (S) \ge min_s (default 5 cmolc/kg solo), ambos na maior parte dos primeiros 100 cm do horizonte B. Discrimina os Subgrupos luvissolicos de Argissolos (Cap 5: PV, PVA).

Usage

carater_luvissolico(pedon, min_ta = 20, min_s = 5, max_depth_cm = 100)

Arguments

Details

Note: o threshold de Ta para "luvissolico" e 20 (vs 27 para atividade_argila_alta canonico). S = Ca + Mg + K + Na trocaveis.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, p 134; Cap 11 (Luvissolos).

Carater nitossolico (SiBCS Cap 5)

Description

Solos com morfologia (estrutura e cerosidade) semelhante aos Nitossolos, mas diferindo por apresentar relacao textural B/A > 1,5 OU policromia (multiplas matizes Munsell em horizontes B) dentro de max_depth_cm cm. Discrimina os Subgrupos nitossolicos de Argissolos (Cap 5: PV, PVA).

Usage

carater_nitossolico(pedon, max_b_a_ratio = 1.5, max_depth_cm = 150)

Arguments

Details

Implementacao v0.7.4 (aproximacao):

• cerosidade \ge comum + moderada, AND

• Razao textural B/A > max_b_a_ratio (default 1.5), OR policromia (\ge 2 matizes distintos em B).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, pp 129-131; Cap 13.

Carater palico (SiBCS Cap 11)

Description

Solos com espessura do solum (A + B, inclusive E e exclusive BC) maior que min_solum_cm (default 80). Discrimina os Grandes Grupos Palicos de Luvissolos (Cap 11 TCp, TXp) – "desenvolvimento excessivo" (do latim "pale").

Usage

carater_palico(pedon, min_solum_cm = 80)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 11, p 214.

Carater perferrico (SiBCS Cap 1; Cap 6 CX Perferricos)

Description

Teor de Fe2O3 (pelo ataque sulfurico-NaOH) >= 360 g/kg de solo (= 36%) na maior parte dos primeiros 100 cm do horizonte B. Discrimina os Grandes Grupos Perferricos (acima do range "ferrico" 180-360 g/kg). Cap 6 CX 4.3 e Cap 10 (Latossolos Perferricos).

Usage

carater_perferrico(pedon, min_fe2o3_pct = 36, max_depth_cm = 100)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 6, p 142; Cap 10 (Latossolos Perferricos).

Carater petroplintico (SiBCS Cap 5)

Description

Caracteres concrecionario e/ou litoplintico ou horizontes concrecionario / litoplintico em posicao NAO diagnostica para Plintossolos Petricos, dentro de max_depth_cm (default 150). Discrimina os Subgrupos petroplinticos de Argissolos (Cap 5: PA, PVA, PV).

Usage

carater_petroplintico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao: passa se horizonte_concrecionario OU horizonte_litoplintico retornarem TRUE em ao menos uma camada com top < max_depth_cm.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5; Cap 16 (Plintossolos).

Carater placico (SiBCS Cap 5; horizonte placico cementado por Fe/Mn)

Description

Camada cimentada por Fe/Mn (geralmente fina, 1-25 mm), detectada via cementation_class %in% {"strongly", "indurated"} dentro de max_depth_cm. Discrimina os Subgrupos placicos de Argissolos PA (Cap 5).

Usage

carater_placico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao v0.7.4 (aproximacao): cementation_class forte ou indurada. SiBCS estrito requeria espessura minima e composicao Fe/Mn confirmada. Refinamento planejado para v0.8.

Value

DiagnosticResult.

References

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

Carater planossolico (SiBCS Cap 5)

Description

Caracter planico em posicao NAO diagnostica para Planossolos. Discrimina os Subgrupos planossolicos de Argissolos (Cap 5: PA, PVA, PV).

Usage

carater_planossolico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao v0.7.4: aproxima como B_planico OR (mudanca_textural_abrupta AND carater_sodico). SiBCS Cap 1 estritamente define caracter planico via mudanca textural abrupta + horizonte/caracter sodico em B + cores neutras.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5; Cap 1, p 36; Cap 15 (Planossolos).

Carater plintico (SiBCS Cap 1, p 36): plintita >= 5% em quantidade insuficiente para horizonte plintico.

Description

Carater plintico (SiBCS Cap 1, p 36): plintita >= 5% em quantidade insuficiente para horizonte plintico.

Usage

carater_plintico(pedon, min_plinthite_pct = 5, max_plinthite_pct = 15)

Arguments

Carater psamitico (SiBCS Cap 10)

Description

Solos com conteudo de argila inferior a max_clay_pct (default 20% = 200 g/kg) na maior parte dos primeiros max_depth_cm (default 150 cm) a partir da superficie do solo. Discrimina os Subgrupos psamiticos de Latossolos Amarelos Distroficos (Cap 10 LA 2.6.1).

Usage

carater_psamitico(pedon, max_clay_pct = 20, max_depth_cm = 150)

Arguments

Details

Implementacao: testa se a media ponderada por espessura de clay_pct dentro de [0, max_depth_cm] esta abaixo de max_clay_pct.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 10 LA, p 203.

Carater redoxico (SiBCS Cap 1, p 36-37): feicoes redoximorficas em quantidade pelo menos comum, dentro da secao de controle. epirredoxico se dentro de 50 cm; endorredoxico se 50-150 cm.

Description

Carater redoxico (SiBCS Cap 1, p 36-37): feicoes redoximorficas em quantidade pelo menos comum, dentro da secao de controle. epirredoxico se dentro de 50 cm; endorredoxico se 50-150 cm.

Usage

carater_redoxico(pedon, min_redox_pct = 5, max_top_cm = 150)

Arguments

Carater retratil (SiBCS Cap 1, p 33)

Description

Solos com retracao significativa quando secos: COLE \ge 0,06 sobre a secao de controle, OU presenca de slickensides + fendas (cracks) suficientemente desenvolvidas. Discrimina Cambissolos retrateis (Cap 6), Vertissolos (Cap 17) e Argissolos retrateis (Cap 5).

Usage

carater_retratil(pedon, min_cole = 0.06, min_crack_width = 1)

Arguments

Value

DiagnosticResult.

References

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

Carater rubrico (SiBCS Cap 1; Cap 10 Latossolos Brunos)

Description

Solos com matiz Munsell mais vermelho que 5YR (i.e., 2.5YR, 10R, 5R) E chroma \ge 4 em alguma parte do horizonte B (inclusive BA), dentro de max_depth_cm (default 100). Discrimina os Subgrupos rubricos de Latossolos Brunos (Cap 10 LB).

Usage

carater_rubrico(pedon, min_chroma = 4, max_depth_cm = 100)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 10 LB, p 199-200.

Carater salico (SiBCS Cap 1, p 38): CE >= 7 dS/m em alguma epoca.

Description

Carater salico (SiBCS Cap 1, p 38): CE >= 7 dS/m em alguma epoca.

Usage

carater_salico(pedon, min_ec = 7, max_depth_cm = NULL)

Arguments

Carater salino (SiBCS Cap 1, p 39): 4 <= CE < 7 dS/m.

Description

Carater salino (SiBCS Cap 1, p 39): 4 <= CE < 7 dS/m.

Usage

carater_salino(pedon, min_ec = 4, max_ec = 7, max_depth_cm = NULL)

Arguments

Carater saprolitico (SiBCS Cap 5)

Description

Solos com horizonte Cr (brando) e ausencia de contato litico ou litico fragmentario, todos dentro de max_depth_cm (default 100 cm). Discrimina os Subgrupos saproliticos de Argissolos (Cap 5: PA, PV).

Usage

carater_saprolitico(pedon, max_depth_cm = 100)

Arguments

Details

Implementacao: requer (a) designation pattern Cr/Crf (sem R continuo) em camada com top < max_depth_cm, e (b) contato_litico(pedon) retorna FALSE.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 5, pp 122, 132.

Carater sodico (SiBCS Cap 1, p 39): saturacao por sodio (PST) >= 15%.

Description

Carater sodico (SiBCS Cap 1, p 39): saturacao por sodio (PST) >= 15%.

Usage

carater_sodico(pedon, min_pst = 15, max_depth_cm = NULL)

Arguments

Carater solodico (SiBCS Cap 1, p 39): PST entre 6% e < 15%.

Description

Carater solodico (SiBCS Cap 1, p 39): PST entre 6% e < 15%.

Usage

carater_solodico(pedon, min_pst = 6, max_pst = 15, max_depth_cm = NULL)

Arguments

Carater sombrico (SiBCS Cap 1; Cap 5 PV)

Description

Camada subsuperficial com acumulacao iluvial de materia organica, caracterizada por cores escuras (munsell_value_moist \le 4, munsell_chroma_moist \le 3) e oc_pct \ge 0.5%, em B abaixo de A/E. Distinto de B espodico por nao requerer iluviacao Al/Fe. Tipico de solos altitudinais (planaltos sul-brasileiros). Discrimina o Subgrupo sombricos de Argissolos Vermelhos Aluminicos (Cap 5 PV 4.2.6).

Usage

carater_sombrico(
  pedon,
  max_value = 4,
  max_chroma = 3,
  min_oc_pct = 0.5,
  max_depth_cm = 150
)

Arguments

Details

Implementacao v0.7.4 (aproximacao):

• Camada B (designation matches ^B) com value \le max_value E chroma \le max_chroma E oc_pct \ge min_oc_pct, dentro de max_depth_cm.

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 1; Cap 5 PV 4.2.6, p 130 (Lunardi Neto, 2012, perfil PVa).

Carater terrico (SiBCS Cap 14)

Description

Solos com horizontes ou camadas constituidos por materiais minerais (horizonte A, Ag, Big e/ou Cg), com espessura cumulativa \ge min_thickness_cm dentro de within_depth_cm da superficie do solo. Discrimina os Subgrupos terricos de Organossolos (Cap 14, pp 245-250) e Cambissolos terricos (Cap 6).

Usage

carater_terrico(pedon, min_thickness_cm = 30, within_depth_cm = 100)

Arguments

Details

Padroes de designacao reconhecidos para horizonte mineral:

• A, Ap, An (mineral superficial)

• Ag (mineral hidromorfico)

• Big, Bg (B mineral hidromorfico)

• Cg (C mineral hidromorfico)

• C, Cr, Crf (mineral subsuperficial)

Excluidos do somatorio: horizontes histicos (H*, O*) e horizontes cementados puros sem material mineral.

Value

DiagnosticResult; passed = TRUE se a soma da espessura dos horizontes minerais (truncada em within_depth_cm) for \ge min_thickness_cm.

References

Embrapa (2018), SiBCS 5a ed., Cap 14, p 246 (subgrupos terricos de Organossolos).

Carater tionico (SiBCS Cap 9; Cap 1 thionic-related)

Description

Solos com horizonte sulfurico (horizonte_sulfurico) OU materiais sulfidricos a profundidades entre min_depth_cm e max_depth_cm (default 100-150 cm). Discrimina os Subgrupos tionicos de Gleissolos (Cap 9 GZsd, GMtal, GMtd, GXte) – variante "tionico subordinado" (vs Tiomorfico, que e a subordem completa).

Usage

carater_tionico(pedon, min_depth_cm = 100, max_depth_cm = 150)

Arguments

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 9, pp 180-191.

Carater vertissolico (SiBCS Cap 6)

Description

Solos com horizonte vertico OU caracter vertico em posicao nao diagnostica para Vertissolos, dentro de max_depth_cm (default 150). Discrimina os Subgrupos vertissolicos de Cambissolos Carbonaticos / Eutroficos / Tb Eutroferricos (Cap 6 CY 3.1.3, 3.6.2, CX 4.1.5, 4.7.7, 4.11.4).

Usage

carater_vertissolico(pedon, max_depth_cm = 150)

Arguments

Details

Implementacao: passa se horizonte_vertico retornar TRUE em ao menos uma camada com top_cm < max_depth_cm. SiBCS estrito requer "posicao nao diagnostica para Vertissolos" – aproximamos isso confiando no dispatcher (apenas chamamos quando ja sabemos que nao e Vertissolo).

Value

DiagnosticResult.

References

Embrapa (2018), SiBCS 5a ed., Cap 6, pp 146-153; Cap 17 (Vertissolos).

CEC per kg clay (cmol_c)

Description

cec_cmol * 100 / clay_pct. Returns NA when either input is missing or clay_pct <= 0.

Usage

cec_per_clay(cec_cmol, clay_pct)

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

Chernossolos (SiBCS Cap 4, p 113; conceito Cap 3, p 89-90)

Description

A chernozemico seguido de: (a) Bi OR Bt, ambos com argila ativ alta + V alta; OR (b) Bi com espessura < 10 cm OR C, ambos calcicos, petrocalcicos OR carbonaticos; OR (c) Calcico OR carater carbonatico no A, seguido de contato litico / fragmentario.

Usage

chernossolo(pedon)

Arguments

Chernossolos Argiluvicos (Cap 7): B textural abaixo do A chernozemico.