Package {soilKey}

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

soilKey: Automated Soil Profile Classification per WRB 2022 and SiBCS

Description

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

Design principle

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

Core types

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

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

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

Provenance and evidence grade

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

v0.1 scope

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

Author(s)

Maintainer: Hugo Rodrigues rodrigues.machado.hugo@gmail.com (ORCID) [copyright holder]

Authors:

• Hugo Rodrigues rodrigues.machado.hugo@gmail.com (ORCID) [copyright holder]

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.2.6 gleyic properties)

Description

Hues of the reductimorphic colours of WRB 2022 3.2.6 criterion 1.a (p. 75): N, 10Y, GY, G, BG, B or PB (every step of those hue families, 2.5GY to 10GY and so on; since v0.9.312, before only the 5 and 10 steps). Criterion 1.b, a hue of 2.5Y or 5Y with a chroma of 2 or less, is .GLEYIC_HUE_1B_REGEX with .reductimorphic_colour(). Used by the redox reading of gleyic_properties and by test_gleyic_features.

Usage

.GLEYIC_HUE_REGEX

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

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

Since v0.9.226 the map also holds the names of the classifications in use before SiBCS that the 5th edition (Santos et al., 2018) gives to one order, by the "Abrangencia" paragraph of each order in its chapter 3 (p. 87-106) and its Anexo I (p. 342): Latosol, Planosol, Solonetz-Solodizado, Brunizem, Rendzina, Regossolo, Litosol, Solos Litolicos, Solos Organicos, Vertisol, Cambisol, Solos Concrecionarios and Rubrozem, with the misspellings of them and of the present orders found in the national BDsolos export. Names that take two words are in .SIBCS_LEGACY_TWO_WORD_MAP.

Left out on purpose, so that their labels stay NA: names the 5th edition divides between orders by something the name does not say (Hidromorfico Cinzento: Gleissolos without an abrupt textural change, Planossolos with one; Solonchak: Gleissolos only with a glei horizon; Alissolo), and names that are not in its correlation (Lateritico Bruno Avermelhado, which is not Laterita Hidromorfica; Solos Brunos Acidos; Solos Coluviais; Mediterraneo Vermelho-Amarelo).

The key is the first word of the label, pluralised and in Title Case, as normalise_febr_sibcs() forms it ("LATOSOL" is "Latosois", "BRUNIZEM" "Brunizens", "SOLONETZ" "Solonetzs").

Old soil names that take two words to tell apart

Description

Consulted by normalise_febr_sibcs() before .SIBCS_LEGACY_ORDER_MAP when the first word of a label gives no order. The key is the first two words of the name, upper case, without accents, as written (a leading "Solo" or "Solos" is not counted, and a hyphen separates words as a space does). One word would not do: "Bruno Nao Calcico" is Luvissolos and "Solos Brunos Acidos" has no order in the correlation of the 5th edition; "Terra" and "Humic" are not names.

Usage

.SIBCS_LEGACY_TWO_WORD_MAP

Details

• Terra Roxa and Terra Bruna (Estruturada, Estruturada Similar) -> Nitossolos: "na maioria" (SiBCS 2018, p. 98). A "pequena parte", with the texture gradient of a B textural, went to Argissolos (p. 87); the name does not say which, and the label is read as the majority.

• Bruno Nao Calcico -> Luvissolos (p. 95-96, Anexo I).

• Humic Glei and Low-Humic Glei (the English names of Glei Humico and Glei Pouco Humico) -> Gleissolos (p. 93).

• Solos Indiscriminados Concrecionarios -> Plintossolos (p. 104).

The orders of SiBCS 5 (2018)

Description

As classify_sibcs()$rsg_or_order names them. A reference label that is none of these after .SIBCS_LEGACY_ORDER_MAP has no class the key can return, so normalise_febr_sibcs gives NA for it.

Usage

.SIBCS_ORDERS

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.

The order a SiBCS label states, when it is not the order of its name

Description

Applied by normalise_febr_sibcs() after the order of the name has been read. Three kinds of label state attributes that SiBCS 5 (Santos et al., 2018) places in another order than the one the name maps to:

Usage

.sibcs_stated_order(order, label)

Arguments

Details

• Podzolico Vermelho-Amarelo or Vermelho-Escuro, Eutrofico, with high-activity clay ("Ta", "argila de atividade alta") -> Luvissolos. Anexo I (p. 342) lists under Luvissolos the "Podzolicos Vermelho-Amarelos Eutroficos Ta" and the "Podzolicos Vermelho-Escuros Eutroficos Ta"; .SIBCS_LEGACY_ORDER_MAP reads every Podzolico as Argissolos. The "Podzolicos Amarelos" are Argissolos in Anexo I without condition, and stay so.

• A label that begins with "Argissolo" and states Eutrofico and high-activity clay -> Luvissolos. The label contradicts itself: an Argissolo has a B textural "de argila de atividade baixa, ou atividade alta desde que conjugada com saturacao por bases baixa ou com carater aluminico" (p. 87), and a B textural with high-activity clay and high base saturation is a Luvissolo (p. 95). Such labels (36 in the national BDsolos export, 19 of them from Acre) read as the old Podzolico names with the first word replaced; the attributes stated are taken, not the word.

• Cambissolo in the old form, Eutrofico, with high-activity clay and A chernozemico -> Chernossolos: the exception of Anexo I ("exceto os Cambissolos Eutroficos com horizonte A chernozemico e com argila de atividade alta"; p. 90). A label whose second word is a present suborder (Haplico, Humico, Fluvico, Histico) was written in SiBCS and is left as it is.

"Eutrofico" is the word itself: "Epieutrofico", "Endoeutrofico" and the like state the base saturation of part of the profile and do not count. A label that states both "Ta" and "Tb" is left with the order of its name, and so is one that states "Eutrofico" (or "Equivalente Eutrofico") without the clay activity: the book places it in Luvissolos if Ta and in Argissolos if Tb, and the label does not say.

Value

The order the label states, or order.

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

Details

In the morphological mode the horizon is also read from its designation. Since v0.9.247 that includes the "ir" of the older surveys (Bir, B2ir, B22irx), the illuvial iron that the present notation writes "s": the mode read "h" and "s" only.

Since v0.9.255 a horizon that the WRB test does not find is looked for by item (a) of the book (p. 65), in both modes. The B espodico has an "acumulacao iluvial de compostos organometalicos" and, by that item, "um horizonte E (albico ou nao) sobrejacente e cores umidas de acordo com um dos itens a seguir: 1) matiz 5YR ou mais vermelho; 2) matiz 7,5YR com valor 5 ou menor e croma 4 ou menor; 3) matiz 10YR, com valor e croma 3 ou menor; 4) cores neutras com valor 3 ou menor". A B layer of 2.5 cm or more passes when:

• an E lies above it in the profile;

• its moist colour is one of the four;

• its organic carbon is 0.5% or more and at least twice that of the nearest E above it; and

• no cerosidade is recorded in it.

The last two stand for the illuvial accumulation, which the sheets do not measure where there is no oxalate extraction. The first takes the form the book gives in item (b)(3) for aluminium and iron by oxalate, "valor 0,50 ou maior, sendo este valor pelo menos o dobro do encontrado no horizonte sobrejacente"; the second keeps out the B whose illuvial material is clay. It is a reading by analogy, decided on 2026-10-13, and not the letter of the book: the colours alone are those of the B textural of many an Argissolo below an E. Items (b) and (c), the cementation and the ortstein, are not tested.

Value

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

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

Description

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

• espessura \>= 10 cm;

• textura francoarenosa ou mais fina;

• < 50% estrutura da rocha original;

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

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

Usage

B_incipiente(pedon, min_thickness = 10)

Arguments

Value

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

Horizonte B latossolico (SiBCS Cap 2, p 57-59)

Description

The requirements of the book that the data of a profile can show (v0.9.241):

• (d) texture francoarenosa or finer;

• (g) cation exchange capacity below 17 cmolc per kg of clay, with no correction for carbon;

• (e) a molecular ratio SiO2/Al2O3 (Ki) of 2.2 or less, where the sulfuric attack is recorded (sio2_sulfuric_pct, al2o3_sulfuric_pct): a layer with a Ki above 2.20 is no B latossolico (v0.9.243);

• (h) cerosidade, if present, at most few and weak: a layer with a larger amount or a higher grade is no B latossolico (a range counts by its upper end, the requirement being a maximum);

• (b) a thickness of 50 cm or more, of the horizon: of the adjoining sub-horizons that meet the other requirements, taken together;

• it "nao apresenta caracteristicas diagnosticas de horizontes glei, B textural, B nitico e plintico": the layers of a B_textural, of a horizonte glei, of a horizonte plintico and of a B_nitico are no B latossolico. Since v0.9.249 they take out their own layers only: until then the glei and the plinthic horizon were those of WRB (gleyic properties, plinthic horizon), and one of them, or a B nitico, anywhere in the profile voided the B latossolico of the whole profile.

Where the designations are recorded, only B horizons are candidates: the B latossolico is a subsurface horizon below the A. Items (a) structure, (c) rock structure and (f) weatherable minerals are not tested.

Usage

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

Arguments

Details

Until v0.9.240 the 50 cm were asked of each layer on its own, so that a B latossolico described as B1, B21 and B22 of 35 cm each was none; and since v0.9.61 a B textural did not exclude it unless its clay films were common or more, on a rule the comments attributed to Cap 18 of the book, which deals with families and series.

In the morphological mode a "Bw" or "Bo" of a tropical profile stands for the B latossolico when the data do not show it.

Value

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

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

Description

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

Usage

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

Arguments

Details

The amount of cerosidade (clay_films_amount) and the type of structure (structure_type) are read as the field sheet words them, in English or in Portuguese, whatever the case and the accents: "Comum", "Abundante" and "Prismatica que se desfaz" (written with its accent) of the Brazilian surveys count as "common", "many" and "prismatic" do. Until v0.9.226 the amount was compared with the literal English terms of min_cerosidade, so no profile described in Portuguese could have a B nitico.

The criteria of the B nitico are minima ("cerosidade em quantidade no minimo comum e com grau forte ou moderado", "estrutura ... de grau de desenvolvimento moderado ou forte"), and a range meets a minimum only if all of it does: an amount or a grade written as a range is read by its lower end. "Pouca a comum" is below "comum" and, since v0.9.231, "Fraca a moderada" is below "moderada" for the cerosidade and for the structure.

Value

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

Horizonte B planico (SiBCS Cap 2, p 65-66)

Description

"E um tipo especial de horizonte B textural, com ou sem carater sodico, subjacente a horizontes A ou E, apresentando mudanca textural abrupta ou transicao abrupta associada a relacao textural com valor dentro do especificado para o horizonte B textural (subitem h), porem calculado entre o primeiro sub-horizonte B e o horizonte imediatamente acima (A ou E)".

Usage

B_planico(pedon)

Arguments

Details

Since v0.9.244 the horizon is looked for where the book puts it, in the first B sub-horizon, below an A or an E, by one of the two:

• a mudanca_textural_abrupta from the A or E to it; or

• a transition recorded as abrupt (boundary_distinctness) with a ratio of its clay to that of the horizon above over the limit of item (h) of the B textural (1.50, 1.70 or 1.80).

As a type of B textural, that sub-horizon has a texture francoarenosa or finer (p. 54): one known to be coarser is no B planico, whatever its clay over that of the E. The structure and the colours below are asked of that first sub-horizon. Until v0.9.243 any layer with a jump of clay over the layer above it could be the B planico, the second way was not tested, and the structure and the colours were asked of the layer with the jump. A profile with no horizon designation at all is still tested that way.

The structure (p. 65): "Apresenta estrutura prismatica, colunar ou em blocos angulares e subangulares grandes ou medios e, as vezes, estrutura macica". It is tested where the sheet records it (structure_type, structure_size): a prismatic, columnar or massive structure passes; blocks pass when medium or larger, or when their size is not recorded; any other recorded structure does not pass.

The colours "devem atender a pelo menos um dos seguintes requisitos" (p. 65-66):

• (a) the matrix colour, with or without mottles: "Matiz 10YR ou mais amarelo, cromas <= 3" or "Matizes 7,5YR ou 5YR, cromas <= 2";

• (b) "Coloracao variegada com pelo menos uma cor apresentando matiz e croma conforme especificado no item (a)" (variegated_colors);

• (c) "matiz 10YR ou mais amarelo, cromas >= 4, combinado com mosqueado de croma conforme especificado no item (a)": a mottle colour (mottle_colors) that satisfies item (a).

Value

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

Horizonte B textural (SiBCS Cap 2, p 54-57)

Description

The B textural as the book states it: a subsurface horizon of texture francoarenosa or finer, at least 7.5 cm thick (thickness items a to e), that meets one or more of the items below (v0.9.241).

• (f) an E horizon above the B, the B having more clay than the horizons above it and being no B espodico, plintico or planico;

• (g) a mudanca textural abrupta from the A or E to the B (Cap 1, p 30-31): at least twice the clay when the A or E has less than 200 g/kg, 200 g/kg more otherwise, within 7.5 cm. The distance is read from the distinctness of the transition (boundary_distinctness: abrupt or clear); where it is not recorded the two layers are compared;

• (h) the relacao textural B/A of footnote 4, above 1.50, 1.70 or 1.80 according to the clay of the A (test_ratio_textural_sibcs);

• (i) where the increase is below item (h), the cerosidade of one or more sub-horizons of the upper part of the B (read as its upper half): (1) texture media with no macroaggregates and cerosidade of moderate grade; (2) texture media with prismatic or blocky structure of moderate or strong grade and cerosidade of at least moderate grade; (3) texture argilosa or muito argilosa with that structure and cerosidade at least common and weak or few and moderate; (4) relacao textural of 1.4 or more with a fragipa within 200 cm, the B being no B espodico;

• (j) with a discontinuity of parent material between the A or E and the B, or with only a ploughed layer above the B, items (h) or (i) are needed.

Amounts and grades written as ranges are read by their lower end, the requirements being minima. Lamellae (item d) are not tested.

Usage

B_textural(pedon, ...)

Arguments

Details

Until v0.9.240 this function was the WRB argic horizon, whose clay increase (6 percentage points, a ratio of 1.4 or 20 points, between a layer and the least clayey layer anywhere above it) is not the one of the book, joined to item (h); items (f), (g) and (i) were not tested.

The layers returned are the B sub-horizons (BC excluded) of texture francoarenosa or finer; evidence$upper_layers are those that carry the evidence, from the top of the B down.

The items are stated for the A, E and B horizons. A profile with no horizon designation at all (depth slices, for instance) cannot be read by them and is tested as before, by the clay increase between layers.

In the morphological mode (options(soilKey.morphological_inference = TRUE)) a "t" in the designation of a B horizon stands for the B textural when the items do not show it. The diagnostic engine (options(soilKey.diagnostic_engine = "aqp")) does not change this test: it changed the argic horizon that this function used to be.

Value

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

ClassificationResult: structured outcome of running a key

Description

ClassificationResult: structured outcome of running a key

ClassificationResult: structured outcome of running a key

Details

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

Public fields

Methods

Public methods

• ClassificationResult$new()

• ClassificationResult$print()

• ClassificationResult$summary()

• ClassificationResult$report()

• ClassificationResult$clone()

Method new()

Build a ClassificationResult.

Usage

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

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.

Horizon columns and site properties that soilKey does not recognise are kept but read by no key. PedonRecord$new() warns about them (with the closest recognised names) when it is called from outside the package; see unrecognised_attributes, horizon_attribute_spec and site_attribute_spec. options(soilKey.warn_unrecognised = FALSE) turns the warning off.

Value

An R6 object of class PedonRecord.

Public fields

Methods

Public methods

• PedonRecord$new()

• PedonRecord$validate()

• PedonRecord$to_aqp()

• PedonRecord$from_aqp()

• PedonRecord$add_measurement()

• PedonRecord$summary()

• PedonRecord$print()

• PedonRecord$clone()

Method new()

Construct a PedonRecord.

Usage

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

Arguments

Method validate()

Validate the record against soil-physical sanity rules.

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

Usage

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

Arguments

Returns

Invisibly, a list summarising the validation outcome.

Method to_aqp()

Coerce to an aqp SoilProfileCollection.

Usage

PedonRecord$to_aqp()

Returns

A SoilProfileCollection. Requires the aqp package.

Method from_aqp()

Populate this record from an aqp SoilProfileCollection.

Usage

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

Arguments

Returns

Invisibly self (mutated in place).

Method add_measurement()

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

Usage

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

Arguments

Returns

Invisibly self.

Method summary()

Compact summary list (for serialization or testing).

Usage

PedonRecord$summary(...)

Arguments

Method print()

Pretty-print the record.

Usage

PedonRecord$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

PedonRecord$clone(deep = FALSE)

Arguments

Examples

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

Abrupt textural difference (WRB 2022 Ch 3.2.1)

Description

Sharp clay-content increase between two superimposed mineral layers meeting all of (WRB 2022 3.2.1, p. 72):

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

• underlying starts \>= 10 cm below the 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.

Since v0.9.312 criterion 5 is read from the distinctness of the lower boundary of the overlying layer (boundary_distinctness): abrupt (2 cm or less) or very abrupt passes, clear, gradual or diffuse fails, and a boundary not recorded leaves the pair undecided (NA). Criterion 2 is counted from the mineral soil surface (below organic layers).

Usage

abrupt_textural_difference(pedon)

Arguments

Value

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

Acrisol RSG diagnostic (WRB 2022)

Description

The Acrisols of the WRB 2022 key (Ch 4, p. 119): an argic horizon starting \le 100 cm from the mineral soil surface; a CEC (1 M NH4OAc, pH 7) of < 24 cmolc/kg clay in some subhorizon of the argic horizon within 150 cm of the mineral soil surface; and exchangeable Al > exchangeable (Ca+Mg+K+Na) in half or more of 50-100 cm from the mineral soil surface, or of the lower half of the mineral soil above a limiting layer starting \le 100 cm, whichever is shallower. Where the cations are not available, the pH is read by WRB 2022 Annex 2, Table 9.3.

Usage

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

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 4, Acrisols (p. 119).

Aeolic material (WRB 2022 Ch 3.3.1)

Description

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

Usage

aeolic_material(pedon)

Arguments

Value

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

Albeluvic glossae (WRB 2022 Ch 3.2.2)

Description

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

Usage

albeluvic_glossae(pedon)

Arguments

Value

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

Albic horizon (WRB 2022)

Description

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

Usage

albic(pedon, min_thickness = 1)

Arguments

Details

Sub-tests:

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

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

Value

A DiagnosticResult.

References

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

Alisol RSG diagnostic (WRB 2022)

Description

The Alisols of the WRB 2022 key (Ch 4, p. 121): an argic horizon starting \le 100 cm from the mineral soil surface and exchangeable Al > exchangeable (Ca+Mg+K+Na) in half or more of 50-100 cm (or of the lower half of the mineral soil above a limiting layer starting \le 100 cm). The key reaches them after the Acrisols and Lixisols.

Usage

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

Arguments

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 4, Alisols (p. 121).

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

The answer is read layer by layer and is NA when a value it needs is not recorded (until v0.9.312 an undecided profile returned FALSE); evidence$layer_status holds the answer per layer. A layer fails when Al_ox + 0.5*Fe_ox < min_alfe or the bulk density > max_bd is measured (phosphate retention, an optional path, can still pass it). Where bulk density is not measured, Al_ox + 0.5*Fe_ox >= min_alfe together with a pH in NaF (ph_naf) >= 9.5 in a carbonate-free layer passes, read from the field test of WRB 2022 Ch 3.2.3; this is a proxy, named in notes, reference and evidence$naf_field_test.

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

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

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

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

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

References

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

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

Description

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

Usage

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

Arguments

Details

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

Value

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

v0.9.313 (WRB 2022 Ch 4, p 104, as worded)

The combined thickness is that of every andic or vitric layer within 100 cm of the soil surface (clipped at 100 cm), provided the uppermost starts \<= 25 cm; until v0.9.312 only layers starting \<= 25 cm were added up. Item 1b applies: where a limiting layer starts \> 25 and \<= 50 cm, andic or vitric layers covering \>= 60% of the soil above it qualify. Petroplinthic and pisoplinthic horizons join the exclusions. An argic horizon read from a clay increase alone (no clay films recorded) whose layers all have andic properties does not exclude (Hugo, N4: the clay of andic material does not disperse fully). Layers whose andic or vitric status is not recorded leave the gate undecided (NA) where they could change it.

v0.9.85 buried-exclusion fix

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

Tier-3 strict mode (v0.9.98)

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

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

Description

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

Usage

annotate_wrb_from_usda(pedons)

Arguments

Details

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

Value

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

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

Description

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

Usage

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

Arguments

Value

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

Anthric horizons (WRB 2022)

Description

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

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

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

Either path qualifies.

Usage

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

Arguments

Value

A DiagnosticResult.

References

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

Fill missing horizon attributes from a SoilGrids depth prior

Description

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

Usage

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

Arguments

Details

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

Value

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

Examples

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

## End(Not run)

Apply a step-by-step Vis-NIR / MIR preprocessing pipeline

Description

Composes the canonical soil-spectroscopy sequence, each step optional and applied in this fixed scientific order: reflectance \to (absorbance) \to (Savitzky-Golay smoothing) \to (Savitzky-Golay 1st or 2nd derivative). Each Savitzky-Golay pass trims (window - 1) / 2 columns from each edge; the wavelength axis is trimmed to match and returned so callers can plot the treated spectrum on the correct axis.

Usage

apply_spectral_preprocessing(
  X,
  wavelengths = NULL,
  absorbance = FALSE,
  sg_smooth = FALSE,
  sg_derivative = 0L,
  window = 11L,
  poly = 2L
)

Arguments

Details

The transform is robust: reflectance that looks like a percentage (maximum > 1.5) is rescaled to a 0–1 fraction before the absorbance log, values are clamped away from zero to avoid log(0), and a Savitzky-Golay step that cannot fit the requested window into the available wavelengths is skipped (recorded in steps) rather than erroring.

Value

A list with X (the treated numeric matrix, wavelength column names trimmed to match), wavelengths (numeric) and steps (an ordered character vector describing the transforms actually applied, starting with "Reflectance").

See Also

preprocess_spectra

Examples

X <- matrix(seq(0.1, 0.5, length.out = 3 * 60), nrow = 3, byrow = TRUE)
colnames(X) <- seq(400, 2400, length.out = 60)
res <- apply_spectral_preprocessing(X, absorbance = TRUE,
                                    sg_smooth = TRUE, sg_derivative = 1L)
res$steps          # ordered treatment labels
dim(res$X)         # columns trimmed by the two SG passes

Arenic texture (WRB 2022)

Description

Tests the texture of the Arenosols (WRB 2022 Ch 4, p. 124): within 100 cm of the mineral soil surface, a weighted average texture of loamy sand or sand (silt + 2 * clay < 30), layers of finer texture and layers with \ge 40% coarse fragments each with a combined thickness of < 15 cm (v0.9.314; until then every layer had to be coarser than sandy loam). Diagnostic of Arenosols.

Usage

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

Arguments

Details

Sub-test: test_arenosol_texture. A part of the 100 cm whose texture or coarse fragments are not recorded, or that is not described, leaves the result undecided (NA) when it could change it.

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,
  lithic_discontinuity = 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).

Until v0.9.219 a glossic, albeluvic or retic designation anywhere voided the argic horizon (the WRB 2014 Albeluvisol logic); in WRB 2022 retic properties belong to an argic or natric horizon.

v0.9.310, for system = "wrb2022" (WRB 2022 Ch 3.1.3, p. 35-36):

• criterion 1: the layers have \ge 8% clay;

• criterion 2.a.i (v0.9.317): the coarser-textured layer is not separated from the layer by a lithic discontinuity, read from the material numbers of the designations and from the data of each pair of layers in between (Ch 3.2.7, p. 76-77: the ratio sand to silt, criterion 2.a.iv; coarse fragments, criterion 6);

• criterion 2.a.ii (v0.9.317): no clay increase counts below a plough layer (Ap) that directly overlies the argic horizon;

• criterion 2.a.iii: a layer is compared with a coarser-textured layer above it only across a transitional horizon of \le 15 cm; layers already accepted and layers whose designation has the suffix t are part of the argic horizon, not transitional;

• criterion 2.b.ii: clay films of "common" or more (clay coatings on \ge 15% of the aggregate surfaces) make a layer argic without a clay increase;

• a subsurface horizon: the layer at the mineral soil surface and the A horizons are not part of it.

The USDA argillic and order keys and the SiBCS B textural keep the earlier reading.

Value

A DiagnosticResult.

References

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

Argic / argillic horizon via aqp::getArgillicBounds()

Description

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

• Eluvial clay < 15\

• Eluvial clay 15-40\

• Eluvial clay \>= 40\

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

Usage

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

Arguments

Details

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

Value

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

See Also

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

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

Description

Wraps argic() and inspects the clay_films_amount field at the argic-passing layers. Returns a structured result that B_latossolico() used, from v0.9.61 to v0.9.240, to decide whether a B textural excluded it.

Usage

argic_with_strong_clay_films(pedon)

Arguments

Details

Since v0.9.241 the SiBCS key does not use this rule: the B textural is tested by the items of the book and excludes the B latossolico, whose cerosidade is tested layer by layer (see B_textural and B_latossolico). The function is kept to inspect a dataset.

Value

A list with:

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

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

• argic – the underlying DiagnosticResult from argic().

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

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

Description

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

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

• clay films lining pores or coating ped faces;

• lamellae more than 5 mm thick.

Usage

argillic_clay_films_test(pedon)

Arguments

Details

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

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

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

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

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

Value

A DiagnosticResult.

References

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

Artefacts (WRB 2022 Ch 3.3.2)

Description

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

Usage

artefacts(pedon, min_pct = 1)

Arguments

Value

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

Convert one or more PedonRecord objects to an aqp SoilProfileCollection

Description

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

Usage

as_aqp(x)

Arguments

Details

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

Value

A aqp::SoilProfileCollection.

See Also

from_aqp, the inverse conversion.

Examples

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

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

## End(Not run)

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

Description

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

Usage

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

Arguments

Details

Two input shapes are accepted:

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

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

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

Value

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

See Also

predict_from_spectra, predict_munsell_from_spectra, load_lucas_soil_2018.

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

Description

Applies argic_with_strong_clay_films() to every pedon in pedons and returns a per-pedon table summarising how the rule that B_latossolico() applied from v0.9.61 to v0.9.240 resolves on the benchmark sample: a B textural (the WRB argic horizon, then) excluded the B latossolico only when its clay films were common or more.

Usage

audit_argic_strong_films(pedons, reference_filter = NULL)

Arguments

Details

Since v0.9.241 the SiBCS key does not use that rule (see B_latossolico); the audit shows what it would have done on field-described datasets such as BDsolos and Redape, where clay-film qualifiers are recorded in mixed Portuguese / English tokenisation. The audit is read-only and never invokes classify_sibcs().

Value

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

Examples

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

## End(Not run)

Auto-detect PROJ_LIB and GDAL_DATA directories

Description

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

Usage

auto_set_proj_env(verbose = FALSE)

Arguments

Details

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

Value

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

List ESDB Raster Library attributes available at a given root

Description

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

Usage

available_esdb_attributes(raster_root)

Arguments

Value

A character vector of attribute names (sorted).

Examples

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

## End(Not run)

Batch robustness across many pedons

Description

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

Usage

batch_robustness(pedons, ...)

Arguments

Value

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

Examples

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

## End(Not run)

Benchmark soilKey WRB predictions against AfSP ground truth

Description

Benchmark soilKey WRB predictions against AfSP ground truth

Usage

benchmark_afsp(pedons, verbose = TRUE)

Arguments

Value

List with accuracy, n_compared, confusion, per_class_recall.

Benchmark soilKey classifiers against BDsolos national reference labels

Description

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

Usage

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

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, by_sampling_type, sampling_type) (or list(accuracy = NA_real_, message) when no reference labels were present). by_sampling_type is a data frame with one row per kind of point and one for all the records (n_compared, n_correct, accuracy), or NULL when no pedon carries the field; sampling_type is the kinds the main figures were computed on (NULL for all).

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

Kinds of sampling point

The export marks each record as "Perfil completo", "Perfil parcial" or "Amostra extra" (site$sampling_type, read by load_bdsolos_csv since v0.9.242). An extra sample is not a described profile: in most cases it is two sampled layers, and the thickness a diagnostic horizon is asked for cannot be read from it. The figures of each system (accuracy, n_compared, n_correct, confusion, per_class) are therefore those of the complete profiles by default, and by_sampling_type gives the same counts for every kind and for all the records together. Pedons that carry no site$sampling_type (another source, a hand-made list) are all counted, as before.

See Also

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

Examples

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

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

## End(Not run)

Compare soilKey with ISRIC's names for ISIS profiles

Description

Classifies each pedon read by read_isis with the WRB 2022 and Soil Taxonomy keys and sets the result beside the names ISRIC gives the profile. The WRB comparison uses the Reference Soil Group, and only when ISRIC's name is from the 2022 edition; the USDA one uses the order (ISRIC's USDA names are from the 1975 to 1999 editions, so subgroups are shown but not scored).

Usage

benchmark_isis(pedons)

Arguments

Value

A data frame, one row per profile, with ISRIC's and soilKey's names, wrb_agree and usda_order_agree (NA where ISRIC gives no comparable name) and the number of close calls of each key.

Run the LUCAS Soil 2018 / ESDB WRB benchmark

Description

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

Usage

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

Arguments

Details

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

Value

A list with elements:

predictions

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

confusion

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

accuracy

Overall fraction of correct classifications among in-scope rows.

per_rsg

Per-RSG recall data.frame.

n_in_scope

Number of pedons with both predicted and reference set.

n_total

Total pedons benchmarked.

n_errors

Number of pedons where the classifier errored out.

errors

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

config

Recap of arguments used.

See Also

load_lucas_soil_2018, lookup_esdb, lookup_soilgrids.

Examples

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

## End(Not run)

Benchmark the Australian order key on NatSoil

Description

Classifies NatSoil pedons with classify_asc3 and compares the order with the one the surveyors gave (site$reference_asc_order). A pedon is decided when no order before the assigned one was left undecided for missing data; the agreement is given for all pedons and for the decided ones. The surveys predate the 3rd edition's Arenosols (2021), whose soils earlier editions placed in the Tenosols and Rudosols: the edition figures count an Arenosol given to a surveyed Tenosol or Rudosol as agreement.

Usage

benchmark_natsoil(pedons, cores = 1L, verbose = TRUE, family = FALSE)

Arguments

Value

A list: n; accuracy and accuracy_edition; decided (count), decided_accuracy and decided_accuracy_edition; by_confidence (a data frame by the surveyors' confidence, 1 = all necessary analytical data); recall by surveyed order; confusion (rows the survey, columns soilKey); first_undecided (the first order left undecided, among provisional pedons); suborders, the same for the suborders where the key has them (overall, and over the pedons whose order agrees); great_groups, the same for the great groups (overall, and over the pedons whose order and suborder agree); subgroups, the same for the subgroups (over the pedons whose order, suborder and great group agree); families (with family = TRUE), each family criterion against the surveyors' family codes (site$reference_asc_family), over the pedons whose order (and, for the Hydrosols, suborder) agrees; and results, one row per pedon.

See Also

load_natsoil_pedons, classify_asc3.

Benchmark the Canadian key against the National Pedon Database

Description

Classifies NPDB pedons (load_npdb_pedons) with classify_cssc3 and compares the result with the survey's classification at the level asked.

Usage

benchmark_npdb(
  pedons,
  level = c("order", "great_group", "subgroup"),
  set_aside = "Chernozemic",
  cores = 1L,
  verbose = TRUE
)

Arguments

Details

The records hold no soil climate and no dry colour, which the key reads for the Chernozemic order and its great groups (Ch 3, p. 34; Ch 5, p. 63) and for the Gray Brown Luvisols; the orders named in set_aside (by default the Chernozemic) are therefore reported apart, with where they land, and left out of accuracy. A result is provisional when an undecided class comes before the one assigned ($provisional_because of classify_cssc3); accuracy_decided counts only the results that are not provisional at the level asked or above.

Pedons from npdb_scenario carry estimates as ranges; each is classified at its central estimate and at every combination of the ends of its ranges (and of the moisture subclasses between its two estimates), and a class counts as decided only where every version gives it and none is provisional (otherwise the central class is reported as provisional). Run such pedons with set_aside = character(0) to include the Chernozems.

Value

A list: level; accuracy (share of agreement outside set_aside); accuracy_decided; n_compared; n_decided; accuracy_all (all orders); set_aside (a table of where those pedons land); confusion; per_class_recall; predictions (one row per pedon; scenario marks pedons classified at the ends of their ranges and scenario_split those whose versions disagree).

Benchmark the New Zealand key against the National Soils Database

Description

Classifies NSD pedons (read_nsd_pedons) with classify_nzsc4 and compares the result with the surveyor's NZSC class at the level asked: the order (the first letter of the code), the group (the first two letters) or the subgroup (the whole code). A pedon is compared at a level only when its recorded class reaches that level (a code of one letter names only the order). A result is provisional when a class before the assigned one at the level asked, or a level above it, could not be decided ($provisional_because of classify_nzsc4); accuracy_decided counts only the results that are not provisional.

Usage

benchmark_nsd(
  pedons,
  level = c("order", "group", "subgroup"),
  cores = 1L,
  verbose = TRUE
)

Arguments

Value

A list: level; accuracy; accuracy_decided; n_compared; n_decided; confusion (reference by prediction, codes); per_class_recall; predictions (one row per pedon with a reference: the recorded and predicted codes at every level, agree, provisional and provisional_because).

Run the soilKey performance benchmark

Description

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

Usage

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

Arguments

Details

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

Value

A list with elements:

summary

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

per_pedon

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

config

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

Examples

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

## End(Not run)

Benchmark soilKey SiBCS predictions against the Redape gold standard

Description

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

Usage

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

Arguments

Value

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

v0.9.81 level-aware comparison

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

Run a benchmark across one of the loaded pedon lists

Description

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

Usage

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

Arguments

Value

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

Benchmark the Australian key on Queensland SALI

Description

Classifies SALI pedons (read_sali_pedons) with classify_asc3 and compares them with the surveyors' classification, with the metrics of benchmark_natsoil (which it calls): the order agreement over all pedons and over the decided ones (no order before the assigned one left undecided for missing data), the Arenosols of the 3rd edition counted as Tenosols or Rudosols in the edition figures, the suborders given the order, the great groups given the suborder and the subgroups given the great group. It adds a table by surveyed order and one by the ASC edition the report cites.

Usage

benchmark_sali(pedons, cores = 1L, verbose = TRUE, family = FALSE)

Arguments

Value

The list of benchmark_natsoil, plus by_order (by surveyed order: n, agree and decided_agree in per cent, decided, and soilKey's most frequent order, top_prediction) and by_edition (the same by the edition of the ASC reference, site$sali_asc_edition).

See Also

read_sali_pedons, benchmark_natsoil.

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

Description

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

Usage

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

Arguments

Value

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

See Also

read_spectral_library, fill_from_spectra

Unified cross-dataset benchmark across SiBCS / WRB / USDA

Description

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

Usage

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

Arguments

Value

A list with elements:

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

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

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

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

Datasets and their reference labels

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

1. Loads pedons via the appropriate load_* helper.

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

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

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

Then pools per-system results across datasets.

Engine selection (Phase 1 wiring)

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

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

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

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

See Also

benchmark_bdsolos, benchmark_lucas_2018, benchmark_run_classification, harmonize_to_gsm.

Benchmark soilKey WRB predictions against a USDA-derived ground truth

Description

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

Usage

benchmark_wrb_vs_usda(pedons, verbose = TRUE)

Arguments

Value

A list with accuracy, n_compared, confusion, per_class_recall.

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

Description

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

Usage

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

Arguments

Value

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

See Also

gapfill_by_predicted_taxon

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

Description

v0.9.315: WRB 2022 Ch 3.3.3 (p. 86), the material "contains >= 2 carbonate equivalent" and "shows visible effervescence with 1 M HCl throughout the fine earth". Each layer is read as the Calcaric qualifier reads it (since v0.9.311): the CaCO3 equivalent decides where it is recorded (caco3_pct >= min_caco3_pct), otherwise the field reaction (effervescence_class: moderate or stronger is visible effervescence, none and slight are not). Before v0.9.315 only caco3_pct was read, so a profile described with the HCl reaction alone was never calcaric. TRUE when some layer is calcaric material, FALSE when every layer is not, NA otherwise.

Usage

calcaric_material(pedon, min_caco3_pct = 2)

Arguments

Value

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

Calcic horizon (WRB 2022)

Description

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

Usage

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

Arguments

Details

Sub-tests called:

• test_caco3_concentration – CaCO3 >= 15%.

• test_minimum_thickness – thickness >= 15 cm.

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

Value

A DiagnosticResult.

v0.9.314

The WRB calcic horizon follows WRB 2022 Ch 3.1.4 (p. 37-38) criterion by criterion: criterion 2 is protocalcic properties (secondary carbonates on \ge 5% of the exposed area, secondary_carbonates_pct) or \ge 5% more CaCO3 than an underlying layer with no lithic discontinuity between; a layer of a petrocalcic horizon is not calcic; the 15 cm are those of the adjoining layers. A layer whose criterion 2 cannot be decided (secondary carbonates not recorded) is undecided, not calcic. The USDA calcic horizon and the SiBCS horizonte calcico keep the earlier reading.

References

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

Cambic horizon (WRB 2022)

Description

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

Usage

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

Arguments

Details

v0.2 implementation tests three conditions:

• thickness >= 15 cm (test_minimum_thickness)

• texture sandy loam or finer (test_texture_argic)

• NOT argic AND NOT ferralic

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

Value

A DiagnosticResult.

v0.9.314

The WRB cambic horizon follows WRB 2022 Ch 3.1.5 (p. 39-40): criterion 4 is read layer by layer, so a layer that forms part of an argic, ferralic, calcic, mollic or other listed horizon (or of a layer with andic properties) is set aside, not the whole profile; the subsurface layers are those below the layer at the mineral soil surface that are not A horizons; the 15 cm are those of the adjoining layers; a layer whose texture or structure is not recorded leaves the result undecided. Criterion 3 is not tested. The USDA keys keep the earlier reading.

References

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

Cambic horizon via aqp::getCambicBounds()

Description

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

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

• Soil structure or absence of rock structure.

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

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

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

Usage

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

Arguments

Value

A DiagnosticResult with name = "cambic_aqp".

See Also

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

Load a canonical reference dataset from the SoilTaxonomy package

Description

Reads one of the parsed WRB 2022 / Keys to Soil Taxonomy datasets from the installed SoilTaxonomy package (NCSS-tech, GPL-3). soilKey ships no copy of these data: install SoilTaxonomy from CRAN to use this function.

Usage

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

Arguments

Value

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

See Also

wrb2022_canonical, kst13_canonical, st_features_canonical.

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

Description

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

Usage

canonicalise_kst13ed_gg(gg)

Arguments

Details

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

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

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

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

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

Value

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

References

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

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

Description

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

Usage

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

Arguments

Details

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

Value

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

References

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

Chernic horizon (WRB 2022 3.1.6)

Description

A thick, well-structured, very dark surface horizon with a high base saturation (WRB 2022 3.1.6, pp. 40-41). Every layer of the horizon, from the mineral soil surface down, must have: (1) \>= 50% fine earth and no mulmic material; (2) granular structure, subangular blocky structure of average size \<= 2 cm (very fine, fine or medium), or cloddy / agricultural structure; (3) \>= 1% SOC; (4) moist value \<= 3, dry value \<= 5 and moist chroma \<= 2, or the carbonate-rich (15-40% CaCO3, \>= 1.5% SOC) or the \>= 40% CaCO3 / loamy-sand (value \<= 5, \>= 2.5% SOC) alternatives; (5) \>= 1% more SOC than a parent-material layer of moist value \<= 4, where one is recorded; (6) BS \>= 50%. The layers together must be (7) \>= 30 cm thick. Worm holes belong to the Vermic qualifier, not to this horizon.

Usage

chernic(pedon, min_thickness = 30)

Arguments

Details

A missing dry value is taken as the moist value plus one, as in the mollic colour test. A missing BS is read from pH (Annex 2, Table 9.2).

Value

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

Chernozem RSG diagnostic (WRB 2022)

Description

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

Usage

chernozem(pedon, max_chroma_upper = 2)

Arguments

Value

A DiagnosticResult.

References

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

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

Description

WRB-canonical: chernic horizon AND, starting \<= 50 cm below the lower limit of the mollic horizon and (if a petrocalcic horizon is present) above it, a layer with protocalcic properties \>= 5 cm thick OR a calcic horizon AND base saturation \>= 50% from the mineral soil surface to the protocalcic / calcic layer throughout. Protocalcic properties are visible secondary carbonates (protocalcic_properties); where BS is not recorded it is read from pH (WRB 2022 Annex 2, Table 9.2).

Usage

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

Arguments

Details

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

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

Value

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

Tier-3 strict mode (v0.9.98)

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

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

Description

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

Usage

claric_material(pedon)

Arguments

Value

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

Robustness of classification under input perturbation

Description

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

Usage

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

Arguments

Details

Default perturbation panel:

• clay_pct: ±5

• sand_pct: ±5

• silt_pct: ±5

• ph_h2o: ±0.2 absolute

• oc_pct: ±10

Value

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

Examples

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

## End(Not run)

Classify a pedon across all three taxonomic systems

Description

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

Usage

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

Arguments

Details

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

Value

A named list with elements:

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

• sibcs – as above, from classify_sibcs().

• usda – as above, from classify_usda().

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

Selecting a subset of systems

Pass systems = c("wrb2022", "sibcs") (or any other subset) to skip systems you don't need. Default systems = "all" runs all three. The systems and their aliases come from soilkey_systems.

Errors and partial results

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

Side effects

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

See Also

classify_wrb2022, classify_sibcs, classify_usda.

Examples

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

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

Classify a pedon under the Australian Soil Classification

Description

Keys a PedonRecord through the Australian Soil Classification, 3rd edition (Isbell and the National Committee on Soil and Terrain 2021), following the online version with its errata. Experimental: this release keys the 15 orders (the key to soil orders) and the suborders of all of them: the Kurosols, Sodosols, Chromosols, Ferrosols, Dermosols, Kandosols and Vertosols (colour classes, and the Aquic Vertosols), the Organosols (the dominant kind of peat), the Podosols (saturation of the B, sulfuric and hypersulfidic material), the Hydrosols (the setting, then mottling), the Calcarosols (gypsum and the carbonate classes), the Anthroposols (the kind of human-made material), the Arenosols and Tenosols (chernic horizons, bleaching, hard materials within 0.5 m, carbonate, nodules, then colour) and the Rudosols (salinity, gypsum, shells, carbic materials, hard materials, sand, gravel, layers), and the great groups of the Kurosols, Sodosols, Chromosols, Ferrosols, Dermosols and Kandosols (pans in or under the B, structure, plasticity, base status, exchangeable Ca/Mg, ESP and carbonate of the B2 or B2t), the Vertosols (the surface), Calcarosols (what the soil directly overlies, and the B), Podosols (the kinds of Podosol B), Organosols (drainage, acid sulfate materials, carbonate and acidity), Hydrosols (acid sulfate materials, the upper 0.5 m, and the order the soil would key to apart from wetness), Arenosols, Rudosols and Tenosols (what the soil directly overlies, nodular, gypsic and argic horizons, carbonate, texture, gravel); the Anthroposols have none in the text; and the subgroups of the Kurosols, Sodosols and Chromosols (chernic and vertic features, bleaching, ferric and manganic horizons, sodicity of the lower B, mottling of the B2t, base status, carbonate) and of the Dermosols, Kandosols and Ferrosols (the same features read on the B2, a strongly acid B2, argic and bauxitic horizons in the B, a snuffy A), of the Vertosols and Calcarosols (acid sulfate materials, pans, sodicity, acidity, carbonate and mottling of the upper 0.5 m of the solum and below it, subplasticity, surface carbonate), the Podosols (coherence of the B, pans), the Organosols (what the organic materials overlie), and the Hydrosols, Arenosols, Rudosols and Tenosols (peat kinds, sulfidic materials near the surface, acidity and carbonate of the upper 1.0 m, the B, the A2, the solum or the soil, horizons with all but the thickness; the Rudosolic and Tenosolic great groups of the Redoxic and Oxyaquic Hydrosols take the list of the Rudosol or Tenosol suborder the soil keys to apart from wetness). The name is that of the deepest class assigned, in the book's form "Subgroup, Great Group, Suborder Order" ("Bleached, Eutrophic, Red Chromosol"); rsg_or_order keeps the order. With include_family = TRUE the family follows the name as the book writes it ("Bleached, Eutrophic, Red Chromosol; thick, non-gravelly, loamy/clayey, deep"): see classify_asc3_family.

Usage

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

Arguments

Details

The ASC is largely morphological. The diagnostics read field texture grades (field_texture, NCST Field Handbook codes; lab clay stands in and is undecided near the limits), the Australian horizon notation (A1, A2, B21t, Bhs, Bk ...; FAO/USDA designations are read by the role of each horizon), the boundary between the A and the B, pH (strongly acid: pHw below 5.5), ESP (sodic: 6 or more), subplasticity, free iron, grade of pedality, carbonates and the moisture of the horizons when described (soil_water_status: the Vertosols' cracks are not required in a solum described moist), mottles, soft and hard carbonate, gypsum, the kind of peat, acid sulfate tests, EC of a 1:5 extract, dry and moist strength, ped size, nodules, pans and exchangeable bases. From the site it reads drainage_class (Hydrosols, organic materials, Podosol suborders), tidal_inundation (Hydrosols, organic materials), surface_condition (a cracking surface, Vertosols; a saline one, Salic Hydrosols), landform, landform_element, tidal_zone, subaqueous and salinised (Hydrosol suborders) and designation_system ("asc" for the Australian notation). The choices where the text is silent are listed in system.file("rules", "asc3", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "asc3", the deepest class in name, the order in rsg_or_order, the classes of each level in levels, the key trace, and provisional_because (classes before the assigned ones that could not be decided); with include_family, the family criteria in trace$family, their names in trace$family_label and their codes in trace$family_code.

References

Isbell, R.F. and the National Committee on Soil and Terrain (2021). The Australian Soil Classification, 3rd ed. CSIRO Publishing, Melbourne. Online version: www.soilscienceaustralia.org.au/asc.

See Also

make_asc3_example, classify_asc3_family, soilkey_systems.

Examples

res <- classify_asc3(make_asc3_example("chromosols"), on_missing = "silent")
res$name
classify_asc3(make_asc3_example("chromosols"), on_missing = "silent",
              include_family = TRUE)$name

Family of a soil under the Australian Soil Classification

Description

Places a soil in the family classes of its order (Australian Soil Classification, 3rd edition, the 'Family Criteria' of each order page). The family is not a level of the key: each criterion is a class of its own, given by a one- or two-letter code. Most orders use the thickness of the A1 horizon (of the whole A horizon in the Kurosols, Sodosols and Chromosols and in the Kurosolic, Sodosolic and Chromosolic Hydrosols, as the book's general rule has it), with any organic horizon over it; gravel (2-60 mm) of the surface and A1 horizon (the larger of the estimate of the ground surface, site$surface_gravel_pct or site$surface_coarse_fragments_pct, and that of the A1); the field texture of the A1 (its major part, peaty under organic surface horizons) and the most clayey field texture of the B; soil depth; and water repellence of the surface soil (water_repellence). The Vertosols use laboratory clay (upper 0.1 m and the B), the Calcarosols the depth of the first Bk horizon, the Arenosols and Rudosols the surface soil, and the Organosols the kind and thickness of their organic materials and the texture under them. Soil depth is the depth to rock, a cemented pan (not a thin ironpan), another cemented layer or saprolite; otherwise, in a soil with a B horizon, the depth to the C below it, and in a soil without one, the depth described. The Anthroposols have no family, nor do the Subtidal, Subaqueous and Intertidal Hydrosols. The readings where the text is silent are in system.file("rules", "asc3", "readings.yaml", package = "soilKey") (topic "Families").

Usage

classify_asc3_family(pedon, order = NULL, suborder = NULL, great_group = NULL)

Arguments

Value

A named list of FamilyAttribute, one per criterion of the order that applies, in the order of the book's family name: value is the class name (NULL when undecided or when no class fits), evidence$code the class code ("YY" undecided, "ZZ" no class of the order fits). An empty list when the soil has no family.

References

Isbell, R.F. and the National Committee on Soil and Terrain (2021). The Australian Soil Classification, 3rd ed. CSIRO Publishing, Melbourne. Online version: www.soilscienceaustralia.org.au/asc.

See Also

classify_asc3.

Examples

fam <- classify_asc3_family(make_asc3_example("chromosols"))
vapply(fam, function(a) a$evidence$code, "")

Classify a soil by spectral similarity to OSSL reference profiles

Description

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

Usage

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

Arguments

Details

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

Value

A list with three elements:

distribution

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

neighbours

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

query

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

Distance metric

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

Region filter

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

See Also

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

Examples

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

## End(Not run)

Classify a pedon under the French soil classification (CPCS 1967)

Description

Keys a PedonRecord through the twelve classes of the French soil classification of 1967 (Commission de Pedologie et de Cartographie des Sols). Experimental: this release keys the classes (sols mineraux bruts, sols peu evolues, vertisols, andosols, sols calcimagnesiques, sols isohumiques, sols brunifies, sols podzolises, sols a sesquioxydes de fer et manganese, sols ferrallitiques, sols hydromorphes, sols sodiques), their 35 sub-classes, the climatic ones read from site$koppen_climate, else the USDA soil temperature and moisture regimes, else the latitude (with no climate, the non-climatic or temperate sub-class), their 101 groups and their 276 subgroups (a group or subgroup the data cannot decide leaves the name provisional; when no group of a sub-class, or no subgroup of a group, fits, the name stops at the level above, and none is invented). The names are French, as the text writes them, in name and in levels$name_native; a subgroup named by an adjective is shown after its group ("Rankers, a mor"), one the text names in full stands alone, and the other subgroups whose tests pass are noted in the trace as intergrades.

Usage

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

Arguments

Details

The CPCS gives no key. soilKey keys the classes in an order built from the text's own statements of precedence: raw mineral soils, vertisols, sodic soils, andosols, podzolised, ferrallitic and sesquioxide soils, hydromorphic soils, weakly developed soils, isohumic soils, calcimagnesic soils, and the brunified soils last; a peat is a hydromorphic soil, whatever lies under it. Every threshold of the text is in depths from the top of the first mineral horizon.

The key reads the old French horizon notation (Aoo, Ao, A1, A2, A3, (B), B, Bh, Bfe, Bt, C, Cca, G, g, R, a Roman numeral for a change of parent material), declared with site$designation_system = "cpcs" or recognised by its symbols, beside the FAO letters; where a profile has no designations, soilKey's diagnostic horizons stand in. From the horizons it reads organic carbon and nitrogen, texture, pH, the CEC and the exchangeable bases, carbonate and gypsum, the EC of the saturated paste, Ki (sio2_sulfuric_pct, al2o3_sulfuric_pct), the andic properties, moist and dry Munsell colours, mottles, slickensides, cracks, structure and consistence, clay films, coarse fragments, the sand minerals, the fibre content of peat, ice (ice_pct, ice_form), and the recorded origin of the layers; from the site the climate, the soil temperature regime, the parent material, recorded erosion, the water table, the elevation, patterned ground (patterned_ground) and the humus form (humus_form); for some subgroups also active carbonate (caco3_active_pct), the coarse and fine sand (coarse_sand_pct, fine_sand_pct) and gibbsite (gibbsite_pct). The choices where the text is silent are listed in system.file("rules", "cpcs1967", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "cpcs1967", the deepest class assigned in name, the class in rsg_or_order, the classes of each level in levels (with name_native), the key trace, and provisional_because (classes before the assigned one that could not be decided).

References

Commission de Pedologie et de Cartographie des Sols (1967). Classification des sols. ENSA, Grignon. Digitised by the AFES (2011).

See Also

make_cpcs1967_example, soilkey_systems.

Examples

res <- classify_cpcs1967(make_cpcs1967_example("ferrallitic"), on_missing = "silent")
res$name
res$levels

Classify a pedon under the Comprehensive Soil Classification System of Japan

Description

Keys a PedonRecord through the Comprehensive Soil Classification System of Japan, First Approximation (Obara et al. 2011), following its key to great groups. Experimental: this release keys the ten great groups (Man-made soils, Organic soils, Podzols, Andosols, Dark Red soils, Lowland soils, Red-Yellow soils, Stagnic soils, Brown Forest soils, Regosols), their 27 groups (for instance Fulvic and Allophanic Andosols, Calcaric Dark Red soils, Brown Lowland soils) and their 116 subgroups (Haplic, Argic, Low-humic, Terrace ...) and their 381 soil series groups (lithic, skeletal, fine-textured, high-humic ..., read with the new attributes texture_class_jp and hardness_yamanaka_mm), and gives the soil phases of chapter VIII (temperature, estimated from the air temperature plus 2 C when the soil temperature is not recorded, and the man-made phases). Each level gives the English name of the text's appendix 2 and, in levels$name_native, the Japanese one.

Usage

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

Arguments

Details

The CSCJ shares most of its diagnostics with the Soil Classification System of Japan (2017), and soilKey reads them with the same code (see classify_scsj2017 for the attributes read), by the CSCJ's own limits where it has them: the argic horizon (the WRB 2006 clay increase), the immature kuroboku feature (P retention as its only substitute), and the dark red colour of the Dark Red soils, which also read the origin from limestone or calcareous deposits (rock_origin, layer_origin, the site parent_material, caco3_pct). The choices where the text is silent are listed in system.file("rules", "cscj2011", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "cscj2011", the deepest class in name, the great group in rsg_or_order, the classes of each level in levels (with name_native), the key trace, provisional_because (classes before the assigned one that could not be decided), and in phases the soil phases of chapter VIII (temperature and man-made phases; the class name is left as it is).

References

Obara, H., Ohkura, T., Takata, Y., Kohyama, K., Maejima, Y. and Hamazaki, T. (2011). Comprehensive Soil Classification System of Japan, First Approximation. Bulletin of the National Institute for Agro-Environmental Sciences 29: 1-73.

See Also

make_cscj2011_example, classify_scsj2017, soilkey_systems.

Examples

res <- classify_cscj2011(make_cscj2011_example("dark_red"), on_missing = "silent")
res$name
res$levels

Classify a pedon under the Canadian System of Soil Classification

Description

Keys a PedonRecord through the Canadian System of Soil Classification, 3rd edition (Soil Classification Working Group 1998). Experimental: this release keys the ten orders (Key to Soil Orders, Ch 3, pp. 33-34), their 31 great groups (Key to Soil Great Groups, pp. 35-36) and their 231 subgroups (Key to Soil Subgroups, pp. 37-51). The name is the deepest class assigned: the subgroup (e.g. "Terric Mesisol"), or the great group (e.g. "Solonetz") when no subgroup can be given: the Solonetzic subgroups are named by the colour of the A, and the key has no other subgroup for a Solonetzic soil without an A (one eroded down to its solonetzic B); the order is in rsg_or_order and every level in levels.

Usage

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

Arguments

Details

The Canadian keys are written largely in terms of horizon designations, which the book defines partly by measurable properties. Each diagnostic reads the measured properties first (podzolic B chemistry with pyrophosphate-extractable Fe and Al, the Bt clay increase, the solonetzic B Ca/Na ratio, the chernozemic A, the gley colours) and the surveyor's designations in the Canadian notation second (Bt, Bf, Bm, Btj, Bn, Bv, Bss, Bg, Cz...). When the assigned order rests on designations alone, a warning says so. A profile that declares the FAO notation in site$designation_system ("fao2006", as isis_profile_to_pedon sets it, "fao", "wrb" or "wrb2022") is read through a translation of its designations into the Canadian notation where the letters mean the same (the book's Table 6: E = Ae, Bw = Bm, Bs = Bf, Btn = Bnt, f = z, z = s ...); the letters with no Canadian equivalent are not read, and the evidence lists what each designation was read as. The choices where the book is silent are listed in system.file("rules", "cssc3", "readings.yaml", package = "soilKey").

The chernozemic A horizon includes a soil-climate criterion (mean annual soil temperature at least 0 C, moisture subclass drier than humid), read from site$mean_annual_soil_temp_C and site$soil_moisture_subclass, or approximated from the USDA regimes. Without it the Chernozemic order is undecided and any order keyed after it is reported as provisional ($provisional_because). The Gray and Dark Gray subgroups of the Solods and Solodized Solonetz also ask for a subhumid climate (site$soil_moisture_subclass).

Value

A ClassificationResult with system_id "cssc3", the deepest class assigned in name, the order in rsg_or_order, every level in levels, the key trace, and provisional_because.

References

Soil Classification Working Group (1998). The Canadian System of Soil Classification, 3rd ed. Agriculture and Agri-Food Canada Publication 1646. NRC Research Press, Ottawa.

See Also

make_cssc3_example, soilkey_systems.

Examples

res <- classify_cssc3(make_cssc3_example("podzolic"), on_missing = "silent")
res$name

Classify a pedon under the Chinese Soil Taxonomy (2001)

Description

Keys a PedonRecord through the Chinese Soil Taxonomy (Cooperative Research Group on Chinese Soil Taxonomy, 2001, the English edition published by Science Press). Experimental: this release keys the 14 orders (key 5.1: Histosols, Anthrosols, Spodosols, Andosols, Ferralosols, Vertosols, Aridosols, Halosols, Gleyosols, Isohumosols, Ferrosols, Argosols, Cambosols and Primosols), their 39 suborders and their 138 groups (key 5.2), with soilKey's residuals [E2] [Other Ferralosols], [A1.4] [Other Permagelic Histosols] and [A2.5] [Other Orthic Histosols] where the book prints none (the name stops there, with a note). Since v0.9.375 it keys the subgroups of orders A to G (176, with [A1.3.x] Lithic Hemi-Permagelic Histosols, listed in Appendix 1 only, at its Appendix position); their criteria are written as presets (inst/rules/cst2001/presets.yaml), expanded when the rules are loaded. The groups of orders H to N stop at the group, with a note, until their subgroups follow in a later release.

Usage

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

Arguments

Details

The key is read in the book's order, the first class whose criteria pass assigned, as the book prescribes (each class lacks the properties of the classes before it). The criteria read the 33 diagnostic horizons and the 25 diagnostic characteristics of chapter 3 on the recorded data (see identify_horizons with "cst2001"), with their weaker evidence grades where the book gives them, the soil moisture and temperature regimes (recorded on the site, or from the aridity index, the site's records of paddy, groundwater and permafrost, and the air temperature), and the few criteria the key defines where it uses them. Every test is three-valued: a measurement not recorded leaves it undecided, a field observation not recorded is absent. A class tested before the assigned one that could not be decided makes the name provisional (provisional_because); a class assigned on a reading the book leaves open (gley colours without a ferrous-iron test, cracks observed for their duration) carries a warning; a class the book itself marks provisional is noted as such (levels$book_provisional).

Names are the English of the book, in the plural of the key ("Permagelic Histosols"), with soilKey's Portuguese gloss in levels$name_pt. The approximate equivalents of the order in US Soil Taxonomy (1999) and the WRB (1998), Tables 4.2 and 4.3, are added as a note (qualifiers$correlation_cst and a line in warnings); they never change the classification. A residual suborder or group named for the udic regime (the Udic Andosols, Vertosols, Isohumosols, Ferrosols, Argosols and Cambosols, the Udi- groups) or for the aquic one (the Aqui-Orthic Halosols) reached by a soil whose regime read is another keeps its class, with a note. The diagnostic horizons and characteristics of each layer are in the trace (phase horizons). The readings where the text is silent are listed in system.file("rules", "cst2001", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "cst2001", the subgroup (or the deepest class assigned) in name, the order in rsg_or_order, the classes of each level in levels (with name_pt and book_provisional), the key trace with the horizon panel, provisional_because, and, when a class was assigned on a provisional reading, in candidates the class the key would reach without it (kind "alternative").

References

Cooperative Research Group on Chinese Soil Taxonomy (2001). Chinese Soil Taxonomy. Science Press, Beijing and New York.

See Also

make_cst2001_example, identify_horizons, soilkey_systems.

Examples

res <- classify_cst2001(make_cst2001_example("K3"), on_missing = "silent")
res$name
res$levels

Classify a horizon spreadsheet in all three systems - one file, one line

Description

The shortest path from a spreadsheet to an answer. Reads file with read_pedon_csv and returns the WRB 2022 / SiBCS / USDA names as a one-row data.frame. Missing attributes are handled silently (on_missing = "silent").

Usage

classify_csv(
  file,
  site = NULL,
  sep = "auto",
  systems = c("wrb", "sibcs", "usda")
)

Arguments

Details

The full ClassificationResult objects (with the key trace, evidence grade, qualifiers, ...) and the parsed PedonRecord are attached as attributes "results" and "pedon" for anyone who wants to dig deeper.

Value

A one-row data.frame with one column per system.

See Also

read_pedon_csv, classify_all.

Examples

f <- system.file("extdata", "perfil_exemplo.csv", package = "soilKey")
classify_csv(f)

Classify a pedon in the FAO-Unesco soil legend

Description

Keys a PedonRecord through the FAO-Unesco legend of the Soil Map of the World. Experimental: this release keys the 28 major soil groupings of the Revised Legend (FAO 1988, World Soil Resources Report 60; the text of the ISRIC reprint of 1997, Technical Paper 20), chapter X, pp. 75-89, and their 153 soil units, in the key's order (Histosols, Anthrosols, Leptosols, Vertisols, Fluvisols, Solonchaks, Gleysols, Andosols, Arenosols, Regosols, Podzols, Plinthosols, Ferralsols, Planosols, Solonetz, Greyzems, Chernozems, Kastanozems, Phaeozems, Podzoluvisols, Gypsisols, Calcisols, Nitisols, Alisols, Acrisols, Luvisols, Lixisols, Cambisols), on the 16 diagnostic horizons and 27 diagnostic properties of chapters IV and V read on the data. Under its grouping a soil keys to the first soil unit whose gate passes, in the key's order; the last unit of each grouping is the key's "Other ..." residual (Haplic, Eutric, and the Terric Histosols and Urbic Anthrosols, whose descriptions are shown, not tested). Since v0.9.386 the result also gives the 16 phases of chapter VIII (pp. 67-71) and the texture and slope classes of the map symbol (Appendix 2, p. 107) in $phases, beside the unit, which they never change. Since v0.9.389, edition = "1974" keys the Legend of 1974 (FAO-Unesco, Soil Map of the World, Vol. I, Unesco Paris), pp. 43-53: its 26 major soil groups in the key's order (Histosols, Lithosols, Vertisols, Fluvisols, Solonchaks, Gleysols, Andosols, Arenosols, Regosols, Rankers, Rendzinas, Podzols, Ferralsols, Planosols, Solonetz, Greyzems, Chernozems, Kastanozems, Phaeozems, Podzoluvisols, Xerosols, Yermosols, Nitosols, Acrisols, Luvisols, Cambisols) and their 106 soil units (the Lithosols, Rankers and Rendzinas are single units), on the diagnostic horizons and properties of 1974 read on the data; its registry id is fao1974 (classify_fao1974). Since v0.9.390 its result gives in $phases the 12 phases of 1974 (pp. 5-7: stony, lithic, petric, petrocalcic, petrogypsic, petroferric, phreatic, fragipan, duripan, saline, sodic, cerrado) and the texture and slope classes of its map symbol (pp. 4-5), in the same form.

Usage

classify_fao(
  pedon,
  edition = c("1988", "1974"),
  rules = NULL,
  on_missing = c("warn", "silent", "error"),
  gapfill = FALSE
)

Arguments

Details

The tests are three-valued: a measurement not recorded leaves its criterion undecided, a field observation not recorded is absent. A grouping or unit tested before the assigned one that the data leave undecided makes the result provisional (provisional_because, "major_groups:<code>" or "units:<code>": the candidates). The key has no residual grouping after the Cambisols: a soil that no gate takes is "[Not classified in the FAO-Unesco Revised Legend (1988)]", in brackets because the name is soilKey's, with the gates that failed in the warnings; when no gate passes but some are undecided, the name lists them in brackets as the candidates. Depths are read from the soil surface, H and O horizons included. The readings where the text is silent are in system.file("rules", "fao1988", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "fao1988" ("fao1974" for the Legend of 1974); name holds the soil unit as printed ("Haplic Luvisols") and rsg_or_order the major soil grouping ("Luvisols"); levels has one row per level (major_groups, units) with the code ("LV", "LVh"), name, page of the key and soilKey's Portuguese gloss (name_pt); the key trace of both levels and provisional_because; and phases, a data.frame with one row per phase and one per class of the map symbol (kind "phase", "texture_class", "slope_class"), its status ("present", "absent", "undecided", or "not shown" for a unit the text excludes), present and criterion (TRUE, FALSE, NA), page, basis, flags and the attributes that would decide an undecided phase (missing).

References

FAO (1988). FAO/Unesco Soil Map of the World, Revised Legend, with corrections and updates. World Soil Resources Report 60, FAO, Rome. Reprinted with updates as Technical Paper 20, ISRIC, Wageningen, 1997.

See Also

classify_fao1988, classify_fao1974, make_fao_example, soilkey_systems.

Examples

res <- classify_fao(make_fao_example("LV"), on_missing = "silent")
res$name
res$rsg_or_order
res$levels
res$phases[res$phases$status != "absent", c("kind", "code", "name", "status")]
classify_fao(make_fao_example("Lc", edition = "1974"), edition = "1974",
             on_missing = "silent")$name

Classify a pedon in the FAO-Unesco Legend of 1974

Description

The registry's classifier of fao1974 (aliases fao74, fao_unesco_1974): classify_fao(pedon, edition = "1974"). Experimental and opt-in. See classify_fao.

Usage

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

Arguments

Value

A ClassificationResult, as classify_fao, with system_id "fao1974".

References

FAO-Unesco (1974). Soil Map of the World 1:5 000 000. Volume I, Legend. Unesco, Paris.

See Also

classify_fao, make_fao_example.

Examples

classify_fao1974(make_fao_example("L", edition = "1974"), on_missing = "silent")$name

Classify a pedon in the FAO-Unesco Revised Legend (1988)

Description

The registry's classifier of fao1988 (aliases fao, fao88, revised_legend): classify_fao(pedon, edition = "1988"). See classify_fao.

Usage

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

Arguments

Value

A ClassificationResult, as classify_fao.

See Also

classify_fao, make_fao_example.

Examples

classify_fao1988(make_fao_example("CM"), on_missing = "silent")$name

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

Description

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

Usage

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

Arguments

Details

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

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

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

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

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

Value

A list with elements:

pedon

The (mutated) PedonRecord.

classifications

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

report

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

provider

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

Why local-first by default

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

Architectural invariants preserved

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

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

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

See Also

vlm_provider, extract_horizons_from_pdf, classify_wrb2022, report.

Examples

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

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

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

## End(Not run)

Classify a soil profile from field photographs alone

Description

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

Usage

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

Arguments

Details

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

Value

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

See Also

extract_munsell_from_photo, apply_soilgrids_depth_prior, compute_per_attribute_evidence_grade.

Examples

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

## End(Not run)

Classify a pedon under the Hungarian diagnostic soil classification

Description

Keys a PedonRecord through the Hungarian diagnostic soil classification of Micheli et al. (2024, second approximation), following its key to the soil types. Experimental: this release keys the 15 types (Laptalaj, Antropogen talaj, Koves-sziklas vaztalaj, Kozethatasu talaj, Szolonyec talaj, Szoloncsak talaj, Duzzado agyagtalaj, Reti talaj, Karbonat talaj, Mezosegi talaj, Agyagbemosodasos talaj, Homoktalaj, Barnafold, Hordalektalaj, Foldeskopar). Since v0.9.316 the name also carries the subtype properties of the type's table (before the type, the first with a capital letter) and its variety properties (after it, in parentheses), in the table's order, with the depth modifiers of 8.7 (felszintol, sekelyen, kozepmelyen, melyben) on properties defined by a layer: e.g. "Savanyu, humuszszegeny Agyagbemosodasos talaj (sekelyen kozettormelekes)", with the accents.

Usage

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

Arguments

Details

The names are the Hungarian singular, as the text's naming example writes them; levels$name_en gives an English gloss. The key reads the FAO (2006) horizon notation the text adopts (an l or r suffix shows reductive conditions; i slickensides; k carbonates; n sodium; p ploughing; t clay accumulation; u artefacts; w a cambic horizon), moist and dry Munsell colours, texture (Hungarian names of the USDA triangle the text prints, English names, or lab clay, silt and sand), organic carbon, bulk density, CaCO3, effervescence, secondary carbonates, base saturation, exchangeable Na, Mg and the CEC, structure, slickensides, cracks, clay films, coarse fragments, artefacts, the layer origin, the dipyridyl test (childs_test), redoximorphic features, and the total water-soluble salts (soluble_salts_pct, Hungarian method). From the site it reads land_use, methane_odour, geomembrane, mechanical_mixing_depth_cm and anthropic_truncation. Features a describer records when met (artefacts, mottles, secondary carbonates, cracks) are absent when not recorded. The choices where the text is silent are listed in system.file("rules", "hscs2024", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "hscs2024", the full name in name and the type in rsg_or_order; levels has the type with its English gloss and one row per subtype and variety property named; qualifiers holds the subtypes, the varieties and status, every property of the type's table with its verdict (TRUE, FALSE, NA), depth and label; and the key trace and provisional_because (types before the assigned one that could not be decided).

References

Micheli E., Fuchs M., Lang V., Csorba A., Dobos E., Szegi T., Kele G. (2024). A diagnosztikus szemleletu hazai talajosztalyozasi rendszer. Utmutato. Masodik kozelites. Magyar Agrar- es Elettudomanyi Egyetem, Godollo.

See Also

make_hscs2024_example, soilkey_systems.

Examples

res <- classify_hscs2024(make_hscs2024_example("steppe"), on_missing = "silent")
res$name
res$levels

Classify a pedon under the German KA5 soil systematics (2005)

Description

Keys a PedonRecord to the divisions (Abteilungen), classes (Klassen) and types (Typen) of the German soil systematics of the Bodenkundliche Kartieranleitung, 5th edition (Ad-hoc-AG Boden 2005, KA5), by its key Tab. 51. Experimental: this release keys the 4 divisions, 21 classes and 56 types, and the 223 subtypes of the type texts (pp. 202-262: 138 of the terrestrial types, 85 of the semiterrestrial, subhydric and Moore types), and the varieties and subvarieties of Tab. 46-50 (pp. 263-282).

Usage

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

Arguments

Details

The subtypes (Hugo's decision Q21): inside a type the transitional subtypes (X-Y, a subtype of the type Y with the features of X) are tested first in printed order, then the deviation subtypes in printed order, the Norm subtype last as the fallback; the first that passes names the subtype, and every subtype of the type that passes is listed in trace$subtypes_passing. Each subtype is one of its printed formulas matched on the horizons (match_horizon_sequence), its depth windows from the GOF and its numbers (base saturation, clay differences, Cp/Fep, slope ...). The Rigosol and the Treposol take an open subtype in brackets for the type still recognisable under the R ("[BB-YY]", Q22); the Treposol has no Norm subtype, the Moorgley neither (an uH over a Gr takes the open "[Uebergangsmoorgley]", an hHm under the Erdhochmoor the open "[vermulmtes Erdhochmoor]").

The varieties (Hugo's decision Q1): an additive level after the subtype, rows of level "variety" in levels (the code of Tab. 49 with the digit of its subvariety, the word of the name, the gloss, the full symbol in a symbol column). A variety is offered where Tab. 50 marks the subtype, plus the six of its note 1 (og, c, z, k, v, ku) everywhere; each criterion of Tab. 46 is read on the horizons (the symbols written, or the recorded data), the humus forms only as recorded; one the data leave open is not named but listed in trace$varieties. The name becomes the full name (adjectives before the subtype's name, nouns in brackets before its deciding part: "podsolige Normbraunerde", "(Acker)Gley"), the symbol (rules I-VII: pBBn, g4.p2BBn, BB-rGG) is in trace$variety$symbol. The further subtypes of the type that pass join as a combination (Tab. 46 no. 17; Q21: PP-GG-BB, GGh-GGc).

The overlays (Tab. 46 no. 18) are reported in trace$overlay and the warnings, and enter the name as a variety (YK/BB, Kolluvisol ueber Braunerde); the levels above it do not change. A mineral cover on a Moor keeps the Moor (Hugo's decision Q7): under 2 dm it is named as substrate only, 2 to < 3 dm "flach X ueber HN" (X\HN), 3 to < 4 dm "X ueber HN" (X/HN), the cover keyed as the mineral type it would be. A fersiallitic or ferrallitic palaeosol (a relict or fossil Bj or Bu) under the soil is named "... ueber Fersiallit / Ferrallit" (Q19); a buried soil (fossil horizons of a layer II or deeper) is keyed alone from its own top and named by the thickness of the soil above (under 3 dm "flach", 3 to < 7 dm; 7 dm or more the upper soil alone).

The key reads the horizons of the profile (identify_horizons(pedon, "ka5")): the KA5 notation where the profile is written in it (declared with site$designation_system = "ka5", or recognised by a sign only it writes: the degree sign, a lower-case prefix before a master such as lC, fAh, aM, tmGo, Sw, Sd, Axh, Bfv ...), otherwise soilKey's order of tests on the recorded data. The last symbol of a designation carries the horizon (Bv-Go is a Go, Go-Bv a Bv). Depths are read from the GOF, the top of the first horizon that is not L, O, Of, Oh or Ovh (p. 79). The order and gates are Tab. 51's (the Moore, the subhydric soils, the semiterrestrial soils, the terrestrial soils), with the numbers of the type texts where the compressed key differs and two rules of the figures Abb. 22 and 23 (Hugo's decisions Q5 and Q6). A gate the data leave open makes the result provisional (provisional_because); a type that holds only on the designation, a measurement missing (the Fahlerde without its clay, C13), or by the key's order with the record missing (the Rigosol without the kind of deep cultivation, Q23), is listed there too.

Names as printed (German) in name and levels$name, with soilKey's English gloss in levels$name_en. The horizon panel (one row per layer: depths from the GOF, the horizon read, the route notation, data or both, the candidates, the evidence) is in trace$horizon_panel, the full frame in trace$horizons, the consistency flags of the figures in trace$figures. The readings where the text is silent are listed in system.file("rules", "ka5", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "ka5": the deepest class assigned in name, the division in rsg_or_order, the division, class and type in levels, the key trace, and provisional_because.

References

Ad-hoc-AG Boden (2005). Bodenkundliche Kartieranleitung. 5. Auflage. Bundesanstalt fuer Geowissenschaften und Rohstoffe, Hannover.

See Also

make_ka5_example, identify_horizons, soilkey_systems.

Examples

res <- classify_ka5(make_ka5_example("BB"), on_missing = "silent")
res$name
res$levels

Classify a pedon under the Russian soil classification (Field Guide, 2008)

Description

Keys a PedonRecord to the trunks and divisions of the Russian soil classification, in the version of its Field Guide (Polevoi opredelitel' pochv Rossii, Dokuchaev Soil Science Institute, 2008). Experimental: this release keys the five trunks (key 2.2: the organogenic, synlithogenic, postlithogenic and weakly developed soils, and trunk E, not a soil: rock outcrops, technogenic surface formations, or a deposit that is not humified over a buried soil) and the 27 divisions (key 2.3), and the types of every division (the profile formulas of chapter 4: CA to CJ in v0.9.338, CK to CT in v0.9.339, trunks A, B and D in v0.9.342). The chemozems CU have no types: their name is built from the pollutants and the soil they were (v0.9.342). The subtypes of every division's list follow the type (v0.9.345).

Usage

classify_kidpr2008(
  pedon,
  rules = NULL,
  on_missing = c("warn", "silent", "error"),
  gapfill = FALSE,
  subtypes = TRUE,
  species = subtypes
)

Arguments

Details

The keys read the diagnostic horizons of the profile: the Russian notation where the profile is written in it (declared with site$designation_system = "kidpr", or recognised by an index only it writes: AY, EL, BEL, BHF, BCA, PU, TUR ...), otherwise the key to horizons 2.1 run on the recorded data (see identify_horizons). From them the keys read whether a horizon is present, whether it starts the profile (at the surface, or under a deposit of 40 cm or less), whether it lies directly over another, whether the profile consists of one horizon only, the depth of hard rock, a deposit at the surface (TPO and the deposits the key to horizons finds on the data included), the peat body of trunk A (more than 50 cm, the agro-peat horizons included) and the thickness of a turbated horizon; of the site, a river floodplain on modern alluvium (landform, landform_element, layer_origin, rock_origin, parent_material, the alluvial mark of the notation; a terrace is no floodplain) and the contaminated horizon X (contamination_hazard). The ochre horizon BAN is formed in volcanic ash, so it makes the volcanic soils alone. With several organic and humus horizons at the surface the thickest is the diagnostic one (p. 37), for step 5 of the key to trunks as for the divisions; FAO and WRB transitions (AB, BC, E/B) in which the key on the data finds no diagnostic horizon are transitions, as those of the Russian notation; a missing depth leaves the step that needs it undecided.

The keys are branching trees; soilKey flattens them into ordered lists in which each gate is the conjunction of the conditions of the book's path to the class, and repairs only the gaps the book's own types prove; the other combinations the key leaves without an exit are "not provided by the Field Guide of 2008": the trunk is assigned and the division left unassigned, with a note. Names: an English gloss in name, the Russian of the book in levels$name_native. The readings where the text is silent are listed in system.file("rules", "kidpr2008", "readings.yaml", package = "soilKey").

The type is named by the formula of its profile: the profile is matched against every formula of its division (see kidpr2008_types), closed on the horizons the division's formulas write, most specific first and agro before natural. A profile no formula matches keeps its division, the type unassigned, with the nearest formulas in the warnings and in the trace (phase types_nearest).

A chemozem (CU, an X horizon: pollutants of the extremely hazardous category within 30 cm) is named, as p. 134 asks, by the kind of pollution and the original soil: the pollutants of the layers of the X horizon, and the soil the profile keys to with the X masked (the X overlays and the contamination records removed), down to its type. The type level is soilKey's "[CU:<code of the original soil>]", named "Chemozems polluted with Cu, Ni, Co; original soil: Sod-podzolic"; the original soil keyed is in the trace (phase chemozem), and an original soil left undecided makes the name provisional.

The subtypes (v0.9.345): each division has one list of subtypes in chapter 4 (26 lists, 558 entries; the chemozems have none), each the index of a genetic feature of section 3.2, read by the feature tests (the recorded data first, the Russian notation where they say nothing). The soil is named by its type and every subtype of the list that passes, in the order of the list, comma-separated and in the plural as printed ("Podzolistye gleevatye, yazykovatye"): the subtypes are the rows of level "subtype" of levels (code: soilKey's key of the entry; name the English gloss, name_native the Russian), the full name in English in name and in Russian in qualifiers$name_native. When every entry is FALSE the soil is of the typical subtype, soilKey's "[tipichnye]" ("[typical]", code NA); when some are undecided the name is provisional, the undecided entries in provisional_because ("subtype:<key>") and in a warning. A feature the formula of the type already writes (the g of the gley types, the BF of CB05, the permafrost sign of the cryozems ...) is not named again, and a sentence of 3.2 that names a single type restricts its subtype to it. Each entry, with its evidence, is in the trace (phase subtype). A soil whose type is unassigned gets no subtypes. The lists are in system.file("rules", "kidpr2008", "subtypes.yaml", package = "soilKey").

The species (v0.9.347): the twelve tables of chapter 5.1, the classes of the thickness of the humus, peat and agro horizons, of the depth and place of gleying, of the lower boundary of the bleached horizon, of the layer over the solonetzic horizon, of the depth of the carbonates and of the soluble salts and, in the organogenic trunk, of the decomposition, the botanical composition (peat_botanical_composition) and the thickness of the peat. Each table that applies to the type is read, and its class follows the subtypes in the name, in the order of the tables ("Dernovo-podzolistye [tipichnye], srednemoshchnye, glubokoelyuvial'nye"; the bleached species in the prefix form of p. 136): rows of level "species" of levels (code "<table>:<class>"), qualifiers$species and species_native. A depth not recorded, an undecided layer at the edge of a horizon, or a horizon that reaches the bottom of the description when a deeper class is possible, leaves the table undecided: it is not named, it is listed in qualifiers$species_undecided and in a note, and the name stays as it is. The tables are in system.file("rules", "kidpr2008", "species.yaml", package = "soilKey"); the varieties and ranks (5.2, 5.3) are not keyed.

The 1977 analogue (v0.9.347): when the type is assigned, the rows of the correlation table of chapter 6 that stand for it are added as a note (a line in warnings) and as qualifiers$analogue_1977 (the 2004 name and formula, the page, whether the soils were distinguished in 1977 and the units of 1977 with their level and extent), never changing the classification; where the table says the soils were not distinguished or has no row for the type, the note says so. The table is in system.file("rules", "kidpr2008", "correlation_1977.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "kidpr2008", the deepest class assigned in name (the type with its subtypes, else the division, else the trunk), the trunk in rsg_or_order, the trunk, division, type, subtypes and species in levels (with name_native, the Russian name), the key trace, the notes on a profile that is not a soil or whose combination of horizons the Field Guide does not provide for in warnings, and provisional_because (classes before the assigned one that could not be decided).

References

Polevoi opredelitel' pochv Rossii [Field Guide of Russian Soils] (2008). Dokuchaev Soil Science Institute, Moscow.

See Also

make_kidpr2008_example, identify_horizons, soilkey_systems.

Examples

res <- classify_kidpr2008(make_kidpr2008_example("CA"), on_missing = "silent")
res$name
res$levels

Classify a pedon under the New Zealand Soil Classification

Description

Keys a PedonRecord through the New Zealand Soil Classification, 4th edition (Manaaki Whenua - Landcare Research 2026), following its Key to Soil Orders and keys to groups and subgroups. Experimental: this release keys the 15 orders (Organic, Gley, Ultic, Podzol, Allophanic, Pumice, Melanic, Semiarid, Oxidic, Granular, Pallic, Brown, Anthropic, Recent, Raw Soils), their 77 groups (since 0.9.298, e.g. Orthic Brown Soils, Perch-gley Pallic Soils) and their 336 subgroups (keyed from 0.9.299 to 0.9.302, e.g. Peaty Orthic Gley Soils, Humose Orthic Podzol Soils, Mottled Fragic Pallic Soils, Typic Orthic Brown Soils); seven groups have no subgroups and keep the group name. The Cryic Soils of the appendix are not keyed.

Usage

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

Arguments

Details

The NZSC reads horizon notations and field tests. The diagnostics read the New Zealand notation (Ah, E, Bw, Bt, Bg, Bh, Bs, Bo, Bx, Bw(g), Bhm, Bsm, Blm, CR, R, Of, Om, Oh, Lm, Lh, an e prefix for anthropic soil material; FAO designations are read by the same letters), moist Munsell colours, texture (field_texture words or codes, or lab clay, silt and sand), pH, P retention (phosphate_retention_pct), dry bulk density, volcanic glass, coarse fragments and their origin, structure, clay coatings, carbonate, ESP, and the field tests naf_test (reactive-aluminium test: none, slight, moderate, strong), childs_test, sensitivity_class, fluidity_class, stickiness and strength_moist. From the site it reads drainage_class, parent_material (Melanic Soils), anthropic_truncation and overthickened_a (the note to the key on overthickened A horizons), and designation_system. The groups also read the packing (packing_degree), Ksat (ksat_mm_h), penetration resistance, where the redox segregations are (redox_segregations_location), sulfate S, roots, a Maori cultural layer (maori_cultural_layer) and the colour of coatings; and, on the site, soil_temp_30cm_C, mean_annual_air_temp_C, surface_water, methane_odour, mechanical_mixing_depth_cm and artificially_drained. The subgroups also read sulfidic S (sulfidic_s_pct), the EC of a 1:5 extract (ec_1to5_dS_m), the share of Sphagnum in the fibres (sphagnum_fibres_pct), a shelly layer (shelly_layer), exchangeable Ca and Mg, clay films, the colour of coatings on pores (pore_coatings_hue_moist, pore_coatings_value_moist, pore_coatings_chroma_moist), the weathering of rock fragments (weathering_stage, weathered_fragments_pct) and the cementation class; on the site, mechanical_mixing_purpose and acid_neutralising_amendment (Mixed and Fill Anthropic Soils). Features a describer records when met (stratification, nodules, cracks, refuse or cultural layers, permafrost, surface water) are absent when not recorded. The choices where the text is silent are listed in system.file("rules", "nzsc4", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "nzsc4", the deepest class in name (the subgroup, or the group where no subgroup is keyed yet), the order in rsg_or_order, the classes of each level in levels, the key trace, and provisional_because (classes before the assigned one that could not be decided).

References

Manaaki Whenua - Landcare Research (2026). New Zealand Soil Classification. 4th ed. doi:10.7931/dl1-lrss-4-2026.

See Also

make_nzsc4_example, soilkey_systems.

Examples

res <- classify_nzsc4(make_nzsc4_example("brown"), on_missing = "silent")
res$name

Classify many profiles from one horizon table

Description

Builds one PedonRecord per profile from a table with one row per horizon, and classifies each with classify_all. The column named by id says which profile a horizon belongs to; the other columns use soilKey's names (horizon_attribute_spec), or are renamed and converted by map. Site properties (site_attribute_spec), such as soil_moisture_regime, come from sites.

Usage

classify_profiles(
  horizons,
  sites = NULL,
  id = "profile_id",
  map = NULL,
  systems = "all",
  on_missing = "silent",
  ...
)

Arguments

Details

The names are checked once for the whole table: a horizon column or site property that no key reads is named in one warning (see unrecognised_attributes), not once per profile. Within a profile the horizons are put in order of top_cm. A profile that cannot be built or classified gets its reason in the error column, and the others are classified as usual.

Value

A data.frame with one row per profile, in the order of their first horizon in horizons: the id column, one column per system with the name of the class (as in the summary of classify_all), missing (the attributes the keys asked for and did not find, comma-separated) and error (NA, or why the profile could not be classified). The attributes "results" and "pedons" hold the full classify_all results and the pedons, in lists named by profile id.

See Also

classify_all for one pedon, classify_csv for one profile in a spreadsheet, unrecognised_attributes to check the names first.

Examples

h <- rbind(
  cbind(profile_id = "p1", as.data.frame(make_ferralsol_canonical()$horizons)),
  cbind(profile_id = "p2", as.data.frame(make_phaeozem_canonical()$horizons)))
s <- data.frame(profile_id = c("p1", "p2"),
                soil_moisture_regime = c("udic", "ustic"))
res <- classify_profiles(h, sites = s, systems = "usda")
res[, c("profile_id", "usda", "error")]


# Columns named and measured differently: rename and convert with `map`.
h2 <- h
names(h2)[names(h2) == "oc_pct"] <- "ORGC"
h2$ORGC <- h2$ORGC * 10                      # g/kg
m <- data.frame(from = "ORGC", to = "oc_pct", factor = 0.1)
classify_profiles(h2, sites = s, map = m)[, c("profile_id", "wrb", "sibcs", "usda")]

Attach a pedon to the references of the French Referentiel pedologique 2008

Description

Attaches a PedonRecord to the references of the Referentiel pedologique 2008 (AFES; Baize and Girard coord.; Editions Quae, 2009). Experimental: this release tests the 110 references of the 34 groups of references (GER): alocrisols (2), andosols (6), anthroposols (5), arenosols (1), brunisols (2), the solums dominated by calcium or magnesium (7: rendosols, calcosols, dolomitosols, rendisols, calcisols, magnesisols, calcarisols), chernosols (3), colluviosols (1), cryosols (2), ferrallitisols and oxydisols (7), ferruginosols (4), fersialsols (4), fluviosols (4), grisols (3), gypsosols (2), histosols (5), leptismectisols (1), lithosols (1), luvisols (6), nitosols (1), organosols (4), pelosols (3), peyrosols (1), phaeosols (2), planosols (3), podzosols (8), rankosols (1), reductisols et redoxisols (3), regosols (1), salisols et sodisols (7), thalassosols (3), thiosols et sulfatosols (2), veracrisols (1) and vertisols (4). The horizons of the intertropical chapters (F, OX, RT, ND, FE, OXc, OXm) are read only in the intertropical domain, and the results of those chapters and of the nitosols say that the book calls them a first version (Q18); a fluviosol needs a recorded alluvial origin and is provisional while the position in the valley and the water table are not recorded (Q14). The histosols read their predominant H horizon between 40 and 120 cm, the luvisols their texture contrast by the bands of the chapter, the organosols the S/CEC of their Aho as a whole. The reductisols and redoxisols read the functional reductic or redox features starting within 50 cm and continuing over 50 cm (a G within 50 cm makes a reductisol whatever lies above), and their doubles with the luvisols, podzosols, pelosols, brunisols, colluviosols, cryosols and histosols are those the book names; the depth class of the hydromorphy is in trace$hydromorphy. The salisols and sodisols read the salic and sodic horizons within 60 cm, the thalassosols a recorded marine material (provisional while the tidal flooding or the polder is not recorded), the thiosols and sulfatosols, first in every case, the sulfur within 50 cm, the veracrisols their vermihumic Ah, the vertisols their SV and V, litho against topo by the site, else the SV.

Usage

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

Arguments

Details

The RP is not a key: a solum attaches to one, two or no reference, simply or imperfectly (pp. XIV, XVII). Every reference is tested every time: its sequences of reference horizons, matched on the horizon frame (the RP notation where the profile is written in it, else the horizons identified on the data, identify_horizons(pedon, "rp2008")), and the side tests of its chapter (depths, thicknesses, forbidden horizons, saturation, carbonates, permafrost, colluvial or anthropic materials). Each test is evaluated strictly and with the tolerances of p. 64 (depth and thickness 10 to 200 cm, pH +/- 0.2, CEC +/- 1, S/CEC +/- 5, organic carbon 8 +/- 2 and 30 +/- 5; any other threshold strict): a reference met only within tolerance, or by an imperfect case its chapter names (calcosol leptique, rendosol pachique, arenosol redoxique ...), is an imperfect attachment, never a simple one. The main name follows the book's explicit statements of precedence, then the degree, then the order of the rapid key (pp. 66-68); a double attachment is written only for the pairs the book prescribes (calcisol-calcosol, the anthroposols transformes); with no reference, the name is "[non rattache]" and the three nearest references are listed. The choice of one name is a convention of soilKey, and $candidates lists every reference that may attach the solum with its degree and the criteria that fail, pass only within tolerance or are undecided.

Names are French, as printed, in the singular (name, levels$name_native), with an English gloss (levels$name_en); the GER is a label (rsg_or_order, levels$ger), not a level. The qualifiers and the types come later. The readings where the text is silent are listed in system.file("rules", "rp2008", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "rp2008": the main name in name ("[non rattache]" when nothing attaches), the GER label in rsg_or_order, the references in the name in levels (level "references", code, name, name_native, name_en, ger, attachment: simple, imperfect, simple_or_imperfect, double), every reference that may attach in candidates (with the columns of ClassificationResult, group the GER, plus name_en, implemented and precedence, the book's statements that put a reference of the name before it or exclude it), the evaluation of every reference, the horizon frame and the rapid key in trace (with trace$position, the depth of the first ND, OXm or OXc of a ferrallitisol or oxydisol and its proximal or distal type), and provisional_because ("references:<code>": the references or GER that could take the name once their data are known).

References

Baize D., Girard M.-C. (coord.) (2009). Referentiel pedologique 2008. AFES, Editions Quae, Versailles.

See Also

make_rp2008_example, soilkey_systems, within_tolerance.

Examples

res <- classify_rp2008(make_rp2008_example("calcosols"), on_missing = "silent")
res$name
res$candidates[, c("code", "degree", "in_name")]

Classify a pedon under the Soil Classification System of Japan

Description

Keys a PedonRecord through the Soil Classification System of Japan (Japanese Society of Pedology 2017), following its key to great groups. Experimental: this release keys the ten great groups (Man-made soils, Organic Soils, Andosols, Podzols, Fluvic soils, Red-Yellow soils, Stagnic soils, Eutrosols, Brown Forest soils, Regosols) and their 26 groups (for instance Allophanic and Non-allophanic Andosols, Fluvic Paddy soils, Magnesian Eutrosols, Sandy Regosols), and their 120 subgroups (Haplic, Humic, Cumulic, Aquic ...); the soil phases follow. Each level gives the official English name and, in levels$name_native, the Japanese one.

Usage

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

Arguments

Details

The SCSJ reads the Japanese horizon notation (H, O, A, E, B, C, G with Go and Gr, R; p ploughed, g gleyed, t, w, s, h, ir, mn; a 2 or II prefix for a lithologic discontinuity, a trailing b for buried; the FAO/USDA notation by the same letters), moist Munsell colours, texture, organic carbon, the phosphate absorption coefficient (phosphate_absorption_coef, mg P2O5/100 g) or its substitutes (P retention, Alo + 1/2 Feo) and the field active-aluminium test (active_al_test), rubbed fibre, pH, base saturation, exchangeable Ca and Mg, Fe(d), Sio, Alp/Alo, the exchange acidity (exchange_acidity_y1), the dipyridyl test (childs_test), fluidity and n_value, mottles and where they are, artefacts, and the recorded origin of the layers (layer_origin, rock_origin: fill, volcanic ejecta, alluvial deposits). From the site it reads land_use or flood_irrigated (paddy land), parent_material, drainage_class, artificially_drained, acid_neutralising_amendment and designation_system. The choices where the text is silent are listed in system.file("rules", "scsj2017", "readings.yaml", package = "soilKey").

Value

A ClassificationResult with system_id "scsj2017", the deepest class in name, the great group in rsg_or_order, the classes of each level in levels (with name_native), the key trace, provisional_because (classes before the assigned one that could not be decided), and in phases the soil phases of chapter V (temperature, man-made and forest phases; the class name is left as it is).

References

The Fifth Committee for Soil Classification and Nomenclature (2017). Soil Classification System of Japan. The Japanese Society of Pedology.

See Also

make_scsj2017_example, soilkey_systems.

Examples

res <- classify_scsj2017(make_scsj2017_example("andosol"), on_missing = "silent")
res$name
res$levels

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

Description

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

Usage

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

Arguments

Value

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

Examples

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

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

Description

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

Usage

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

Arguments

Details

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

Value

Lista nomeada de FamilyAttribute.

Status v0.7.14.A

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

References

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

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

Description

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

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

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

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

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

Usage

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

Arguments

Details

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

Value

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

References

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

Examples

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

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

Description

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

Usage

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

Arguments

Value

Named list of FamilyAttribute objects.

References

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

See Also

family_label_usda, classify_usda.

Classify a PedonRecord via Embrapa's SmartSolosExpert REST API

Description

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

Usage

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

Arguments

Details

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

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

Value

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

References

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

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

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

See Also

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

Examples

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

## End(Not run)

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

Description

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

Usage

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

Arguments

Value

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

Posterior distribution over classification outcomes

Description

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

Usage

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

Arguments

Value

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

See Also

classification_robustness, get_perturbation_scale, compute_per_attribute_evidence_grade.

Examples

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

Classify a pedon under WRB 2022

Description

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

Usage

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

Arguments

Value

A ClassificationResult.

Examples

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

Classify a pedon under the South African soil classification (1991)

Description

Keys a PedonRecord to the soil forms of the South African soil classification of 1991 (Soil Classification Working Group, 1991; the "Blue Book"). Experimental: the book itself is not available to soilKey; the key is read from its open pages (the AGIS key and form pages, the general rules, the topsoil pages), SASRI (1999) and van Huyssteen (2020). It keys the 73 forms and, since v0.9.359, their 404 families.

Usage

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

Arguments

Details

Each layer is read as one of the 30 diagnostic horizons and materials (see identify_horizons): from the name written in diagnostic_za (or in the designations of a profile declared with site$designation_system = "za"), else by soilKey's tests on the recorded data, three-valued, with WRB numbers standing in, flagged, where no open source gives the book's (the podzol B, the placic pan, the dorbank, the carbonate horizons and the colours of the subsoil). The profile is first read by the general rules: only horizons whose top lies above 1500 mm count; a recent deposit thinner than 500 mm over a buried soil is set aside and the buried soil classified, a thicker one is classified alone (recent_deposit, else its origin, flagged); a profile with no topsoil whose first horizon is a red or yellow-brown apedal B, a neocarbonate B, a dorbank or a hard plinthic B is read as truncated, an orthic A supplied.

A form holds when its horizons are the first of the profile's, in order (layers of no diagnostic horizon skipped), and the horizon that follows is not one that would make another form (Hutton over hard rock is Hutton; Hutton over a soft plinthic B is Bainsvlei). A description that stops above 1500 mm leaves the longer forms undecided, so the shorter one is provisional. When no form passes and some are undecided, the name lists them in the order of the key, provisional ("[Undecided in the South African soil classification (1991): Inanda ([Ia]), Arcadia (Ar), or not classified]", v0.9.402). The 500 mm rules of the form pages are tested too (Valsrivier, Sepane, Swartland, the podzol forms; Witbank, Dundee, Namib over a buried soil). A sequence no form has gives no form, with the nearest forms in the warnings; an orthic A under 100 mm thick over nothing diagnostic is the land class "rock and lithosols" (general rules). Lichtenburg (orthic A, red apedal B, hard plinthic B) is named by van Huyssteen (2020) but not by the AGIS key of 1991: it is keyed, always provisional. The readings soilKey makes where the open sources are silent are in system.file("rules", "za1991", "readings.yaml", package = "soilKey").

The families (v0.9.359) are read by the 19 family criteria of the book, each on the horizon its family names (the B1 of the red apedal B, the E, the upper G, the layer under the placic pan ...), as the form key identified it: the first family whose classes all hold is the family; with a criterion undecided for lack of data, the result names the families left possible and soilKey's partial code, an "x" for each undecided digit ("Hutton, [Hu1x00]"). The name follows the identification of the book: the form, the family code and name, and the USDA texture class of the A when its clay, silt and sand are recorded (with the sand grade of sand_grade): "Hutton, Hu1200 Kelvin, sandy loam".

Value

A ClassificationResult with system_id "za1991": the form in rsg_or_order, the full name (form, family, texture) in name, the form and the family in levels (with name_en, soilKey's gloss of the form: the sequence of its horizons), the family read in qualifiers$za_family (its code and name, the partial code of an undecided family, the texture, and every criterion read: its class, the layers read, the stand-ins and the attributes missing), the sequence read in qualifiers$za_sequence and the identified layers in qualifiers$za_horizons (with za_truncated, za_land_class and za_nearest when they apply), the general rules applied, the stand-ins used and the nearest forms in warnings, and provisional_because.

References

Soil Classification Working Group (1991). Soil classification: a taxonomic system for South Africa. Memoirs on the Agricultural Natural Resources of South Africa No. 15. Department of Agricultural Development, Pretoria.

See Also

make_za1991_example, identify_horizons, soilkey_systems.

Examples

res <- classify_za1991(make_za1991_example("hutton"), on_missing = "silent")
res$name
res$qualifiers$za_sequence

Clear the in-memory KST13 cache

Description

Useful after pointing options(soilKey.kst13_dir) at other copies of the files mid-session. Frees ~3.1 MB.

Usage

clear_kst13_cache()

Value

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

Clear the soilKey OSSL cache

Description

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

Usage

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

Arguments

Value

Invisibly, the character vector of files that were removed.

Cohesic horizon (WRB 2022, Chapter 3.1.7)

Description

A subsurface horizon with a massive or weak subangular blocky structure, poor in organic matter and iron oxides, with a kaolinite-dominated, low-activity clay fraction, and hard when dry. It is the diagnostic basis of the Cohesic qualifier and corresponds to the caracter coeso of the Brazilian SiBCS (typical of the coastal "Tabuleiros" Latossolos and Argissolos).

Usage

cohesic(
  pedon,
  max_oc = 0.5,
  min_clay = 15,
  max_cec_per_clay = 24,
  min_thickness = 10
)

Arguments

Details

Diagnostic criteria (all required): mineral material with (1) < 0.5% soil organic carbon; (2) >= 15% clay; (3) a CEC (by 1 M NH4OAc, pH 7) of < 24 cmol_c per kg clay; (4) a massive or weak subangular blocky structure; (5) not cemented; (6) a rupture-resistance class, when dry, of at least hard; and (7) a thickness of >= 10 cm.

Value

A DiagnosticResult.

References

IUSS Working Group WRB (2022), Chapter 3.1.7, Cohesic horizon.

Combine multiple spatial priors via weighted geometric mean

Description

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

Usage

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

Arguments

Details

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

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

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

Value

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

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

Description

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

Usage

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

Arguments

Value

A list with soilkey, aqp, agree.

Cross-validate the local SiBCS classifier against the SmartSolosExpert API

Description

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

Usage

compare_smartsolos(pedon, ...)

Arguments

Value

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

Examples

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

## End(Not run)

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

Description

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

Usage

compute_ki(sio2_pct, al2o3_pct)

Arguments

Details

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

Value

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

References

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

Examples

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

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

Description

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

Usage

compute_kr(sio2_pct, al2o3_pct, fe2o3_pct)

Arguments

Details

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

Value

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

References

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

Examples

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

Per-attribute provenance-aware evidence grade

Description

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

Usage

compute_per_attribute_evidence_grade(pedon)

Arguments

Details

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

Value

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

See Also

classify_from_photos, the global evidence grade reported on every ClassificationResult.

Examples

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

Continuous rock (WRB 2022 Ch 3.2.5)

Description

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

Usage

continuous_rock(pedon)

Arguments

Value

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

Honest taxonomic-completeness report

Description

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

Usage

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

Arguments

Value

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

Examples

# WRB diagnostic horizons are measured against soilKey's own table, offline.
cov <- coverage_report("wrb_horizons")
cov$overall

# The USDA axes read the KST 13th edition from ncss-tech/SoilKnowledgeBase,
# downloaded on first use, so they need a connection the first time.
# Needs network access; skipped offline and in batch checks.
online <- interactive() && requireNamespace("httr", quietly = TRUE) &&
  !inherits(try(httr::HEAD("https://raw.githubusercontent.com", httr::timeout(5)),
                silent = TRUE), "try-error")
if (online) {
  usda <- try(coverage_report("usda_subgroup"), silent = TRUE)
  if (!inherits(usda, "try-error")) head(usda$missing)
}

CPCS 1967 class gates (internal)

Description

The tests of the twelve classes of the French soil classification (CPCS 1967), read by classify_cpcs1967 in the order of inst/rules/cpcs1967/key.yaml. Each returns a DiagnosticResult.

Usage

raw_mineral_soils_cpcs(pedon)

weakly_developed_soils_cpcs(pedon)

vertisols_cpcs(pedon)

sodic_soils_cpcs(pedon)

andosols_cpcs(pedon)

podzolised_soils_cpcs(pedon)

ferrallitic_soils_cpcs(pedon)

sesquioxide_soils_cpcs(pedon)

hydromorphic_soils_cpcs(pedon)

isohumic_soils_cpcs(pedon)

calcimagnesic_soils_cpcs(pedon)

brunified_soils_cpcs(pedon)

Arguments

Value

A DiagnosticResult.