Package 'soilKey'

Description

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

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

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

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

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

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

Usage

abrupt_textural_difference(pedon)

Arguments

Description

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

Usage

acric_andisol_usda(pedon)

Arguments

Description

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

Usage

acric_oxisol_usda(pedon)

Arguments

Description

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

Usage

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

Arguments

Value

A DiagnosticResult.

References

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

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

Description

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

Usage

aeric_oxisol_usda(pedon)

Arguments

Description

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

Usage

aeric_subgroup_usda(pedon)

Arguments

Description

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

Usage

al_rich_spodic_usda(pedon)

Arguments

Value

A DiagnosticResult.

Description

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

Usage

albaquult_qualifying_usda(pedon)

Arguments

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

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

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

Usage

albic_horizon_usda(pedon)

Arguments

Value

A DiagnosticResult.

Description

Albic Subgroup helper (Albaquultic / Albaquic)

Usage

albic_subgroup_usda(pedon)

Arguments

Description

Albolls qualifier: mollic + albic + argillic.

Usage

alboll_qualifying_usda(pedon)

Arguments

Description

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

Usage

alfic_subgroup_usda(pedon)

Arguments

Description

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

Usage

alfisol_qualifying_usda(pedon)

Arguments

Description

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

Usage

alfisol_usda(pedon)

Arguments

Description

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

Usage

alic_andisol_usda(pedon)

Arguments

Description

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

Usage

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

Arguments

Value

A DiagnosticResult.

References

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

Description

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

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

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

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

Usage

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

Arguments

Value

A DiagnosticResult.

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

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

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

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

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

References

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

Description

Soil materials with one or both of the following:

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

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

Usage

andic_soil_properties_usda(pedon)

Arguments

Details

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

Value

A DiagnosticResult.

References

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

Description

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

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

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

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

Usage

andic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

Description

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

• a depth of 60 cm; or

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

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

Usage

andisol_qualifying_usda(pedon)

Arguments

Value

A DiagnosticResult.

References

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

Description

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

Usage

andisol_usda(pedon)

Arguments

Description

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

Usage

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

Arguments

Details

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

v0.9.85 buried-exclusion fix

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

Description

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

Usage

anhydrous_conditions_usda(pedon)

Arguments

Details

Required characteristics:

• Mean annual soil temperature <= 0 C; AND

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

• No ice-impregnated permafrost in that layer; AND

• One of:

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

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

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

Value

A DiagnosticResult.

References

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

Description

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

Usage

anionic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

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

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

Aqualf Suborder qualifier (aquic conditions in argillic Alfisol).

Usage

aqualf_qualifying_usda(pedon)

Arguments

Description

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

Usage

aquand_qualifying_usda(pedon)

Arguments

Description

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

Usage

aquandic_subgroup_usda(pedon)

Arguments

Description

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

Usage

aquent_qualifying_usda(pedon)

Arguments

Description

Aquept Suborder qualifier

Usage

aquept_qualifying_usda(pedon)

Arguments

Description

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

Usage

aquert_qualifying_usda(pedon)

Arguments

Description

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

Usage

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

Arguments

Details

Three types of saturation are defined:

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

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

• Anthric saturation: cultivated/flood-irrigated.

Implementation (v0.8.x):

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

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

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

Value

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

References

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

Description

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

Usage

aquic_subgroup_usda(pedon)

Arguments

Value

A DiagnosticResult.

Description

Aquolls qualifier (aquic conditions in mollic).

Usage

aquoll_qualifying_usda(pedon)

Arguments

Description

Aquult Suborder qualifier Pass when aquic_conditions within 50 cm.

Usage

aquult_qualifying_usda(pedon)

Arguments

Description

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

Usage

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

Arguments

Details

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

Value

A DiagnosticResult.

Description

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

Usage

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

Arguments

Details

Sub-test: test_coarse_texture_throughout.

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

Value

A DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

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

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

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

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

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

Value

A DiagnosticResult.

References

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

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

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

Usage

argic_aridisol_usda(pedon)

Arguments

Description

Argic Mollisol Suborder helper – delegates argillic_within_usda.

Usage

argic_mollisol_usda(pedon)

Arguments

Description

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

Usage

argic_subgroup_usda(pedon)

Arguments

Description

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

Usage

argic_with_strong_clay_films(pedon)

Arguments

Value

A list with:

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

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

• argic – the underlying DiagnosticResult from argic().

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

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

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

Usage

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

Arguments

Value

A DiagnosticResult.

Description

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

Usage

argillic_usda(pedon, ...)

Arguments

Value

A DiagnosticResult.

References

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

Description

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

Usage

argillic_within_usda(pedon, max_top_cm = 100)

Arguments

Value

A DiagnosticResult.

Description

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

Usage

argissolo(pedon)

Arguments

Description

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

Usage

argissolo_acinzentado(pedon)

Arguments

Description

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

Usage

argissolo_amarelo(pedon)

Arguments

Description

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

Usage

argissolo_bruno_acinzentado(pedon)

Arguments

Description

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

Usage

argissolo_vermelho(pedon)

Arguments

Description

Argissolos Vermelho-Amarelos (catch-all dos Argissolos)

Usage

argissolo_vermelho_amarelo(pedon)

Arguments

Description

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

Usage

aridisol_qualifying_usda(pedon)

Arguments

Description

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

Usage

aridisol_usda(pedon)

Arguments

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

Description

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

Usage

as_aqp(x)

Arguments

Details

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

Value

A aqp::SoilProfileCollection.

See Also

from_aqp, the inverse conversion.

Examples

if (requireNamespace("aqp", quietly = TRUE)) {
  pedons <- list(make_ferralsol_canonical(), make_luvisol_canonical())
  spc <- as_aqp(pedons)
  length(spc)         # 2 profiles
  aqp::horizons(spc)  # one row per horizon, aqp-named columns
}

Description

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

Usage

atividade_argila_alta(pedon, min_ta = 27)

Arguments

Details

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

Value

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

References

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

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 v0.9.61 B_latossolico() latossolic-vs-argic rule resolves on the benchmark sample.

Usage

audit_argic_strong_films(pedons, reference_filter = NULL)

Arguments

Details

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

Value

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

Examples

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

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

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

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

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

Description

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

• Espessura minima de 50 cm;

• Textura francoarenosa ou mais fina;

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

• < 5% volume mostrando estrutura da rocha original;

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

• Cerosidade no maximo pouca e fraca.

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

Usage

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

Arguments

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

Description

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

Usage

B_planico(pedon)

Arguments

Description

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

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

• textura \>= francoarenosa.

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

Usage

B_textural(pedon, ...)

Arguments

Description

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

Usage

batch_robustness(pedons, ...)

Arguments

Value

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

Examples

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

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
)

Arguments

Value

A list with elements:

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

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

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

Reference label coverage

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

Comparison level

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

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

Errors and missing-label handling

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

See Also

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

Examples

# Requires a user-provided BDsolos CSV; guarded so the example
# no-ops on CRAN when the file is absent.
csv_path <- "RJ.csv"
if (file.exists(csv_path)) {
  peds <- load_bdsolos_csv(csv_path)
  bench <- benchmark_bdsolos(peds, systems = c("sibcs", "wrb2022", "usda"))
  bench$coverage      # how many pedons had each reference label
  bench$per_system$sibcs$accuracy
  bench$per_system$sibcs$confusion

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

Description

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

Usage

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

Arguments

Details

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

Value

A list with elements:

predictions

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

confusion

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

accuracy

Overall fraction of correct classifications among in-scope rows.

per_rsg

Per-RSG recall data.frame.

n_in_scope

Number of pedons with both predicted and reference set.

n_total

Total pedons benchmarked.

n_errors

Number of pedons where the classifier errored out.

errors

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

config

Recap of arguments used.

See Also

load_lucas_soil_2018, lookup_esdb, lookup_soilgrids.

Examples

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

Description

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

Usage

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

Arguments

Details

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

Value

A list with elements:

summary

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

per_pedon

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

config

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

Examples

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

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

Arguments

Value

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

Description

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

Usage

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

Arguments

Value

A list with elements:

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

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

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

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

Datasets and their reference labels

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

1. Loads pedons via the appropriate load_* helper.

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

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

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

Then pools per-system results across datasets.

Engine selection (Phase 1 wiring)

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

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

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

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

See Also

benchmark_bdsolos, benchmark_lucas_2018, benchmark_run_classification, harmonize_to_gsm.

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

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

Description

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

Usage

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

Arguments

Details

Sub-tests called:

• test_caco3_concentration – CaCO3 >= 15%.

• test_minimum_thickness – thickness >= 15 cm.

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

Value

A DiagnosticResult.

References

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

Description

Calcic horizon (USDA, delegates to WRB calcic).

Usage

calcic_horizon_usda(pedon, max_top_cm = 100)

Arguments

Description

Calcic Subgroup helper – delegates to calcic_horizon_usda within max_top_cm.

Usage

calcic_subgroup_usda(pedon, max_top_cm = 100)

Arguments

Description

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

Usage

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

Arguments

Details

v0.2 implementation tests three conditions:

• thickness >= 15 cm (test_minimum_thickness)

• texture sandy loam or finer (test_texture_argic)

• NOT argic AND NOT ferralic

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

Value

A DiagnosticResult.

References

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

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

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

Usage

cambissolo(pedon)

Arguments

Description

Cambissolos Fluvicos (Cap 6): carater fluvico.

Usage

cambissolo_fluvico(pedon)

Arguments

Description

Cambissolos Haplicos (catch-all).

Usage

cambissolo_haplico(pedon)

Arguments

Description

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

Usage

cambissolo_histico(pedon)

Arguments

Description

Cambissolos Humicos (Cap 6): horizonte A humico.

Usage

cambissolo_humico(pedon)

Arguments

Description

Resolution order:

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

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

Usage

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

Arguments

Value

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

See Also

wrb2022_canonical, kst13_canonical, st_features_canonical.

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

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

Usage

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

Arguments

Details

Criterios canonicos (todos verificados em horizontes B):

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

Value

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

References

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

Description

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

Usage

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

Arguments

Description

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

Usage

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

Arguments

Details

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

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_argiluvico(pedon, max_depth_cm = 150)

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_cambissolico(pedon)

Arguments

Details

Implementado como uma interseccao de duas condicoes:

1. B_incipiente passa em ao menos um horizonte

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

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Description

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

Usage

carater_chernossolico(pedon, min_ta = 20)

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_coeso(pedon, max_depth_cm = 150)

Arguments

Details

Criterios canonicos:

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

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

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

Value

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

References

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

Description

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

Usage

carater_durico(pedon, max_depth_cm = 150)

Arguments

Details

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

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

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_fluvico(pedon)

Arguments

Description

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

Usage

carater_gleissolico(pedon, max_depth_cm = 150)

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_hidromorfico(pedon, max_depth_cm = 100)

Arguments

Details

Implementacao v0.7.5 (aproximacao):

• horizonte_glei dentro de max_depth_cm, OR

• carater_redoxico ate max_depth_cm, OR

• designation pattern Eg dentro de max_depth_cm.

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_hipocarbonatico(pedon, max_depth_cm = NULL)

Arguments

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_latossolico(pedon, max_depth_cm = 150)

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Details

Implementacao v0.7.4 (aproximacao):

• cerosidade $\ge$ comum + moderada, AND

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_palico(pedon, min_solum_cm = 80)

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_petroplintico(pedon, max_depth_cm = 150)

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_placico(pedon, max_depth_cm = 150)

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

carater_planossolico(pedon, max_depth_cm = 150)

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Description

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

Usage

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

Arguments

Details

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

Value

DiagnosticResult.

References

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

Description

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

Usage

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

Arguments

Description

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

Usage

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