Package 'soilKey'

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.

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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)

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

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.

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.

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.

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.

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

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.

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)

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.

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)

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

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)

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.

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.

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.

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.

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.

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.

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)

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.

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)

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.

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)

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.

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

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)

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.

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

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

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.

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.

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

Description

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

Usage

calcaric_material(pedon, min_caco3_pct = 2)

Arguments

Value

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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)

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

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

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

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

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

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)

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

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)

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)

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)

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). The subtype and variety properties that the system adds to the name are not keyed yet.

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 type in name and rsg_or_order, the type with its English gloss in levels, 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

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

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

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

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.

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

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.

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)

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.

Description

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

Usage

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

Arguments

Value

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

See Also

classification_robustness, get_perturbation_scale, compute_per_attribute_evidence_grade.

Examples

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

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

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.

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.

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
)