extract_soils_NRCS_SDA: Extract soil information from the Soil Data Access SDA...

In DrylandEcology/rSW2exter: Access External Data as Input for SOILWAT2 and STEPWAT2 Simulations

Extract soil information from the Soil Data Access SDA service by NRCS for SOILWAT2 applications

Description

Extract soil information from the Soil Data Access SDA service by NRCS for SOILWAT2 applications

Usage

extract_soils_NRCS_SDA(
  x,
  crs = 4326,
  mukeys = NULL,
  method = c("SSURGO", "STATSGO", "SSURGO_then_STATSGO"),
  sql_template = NA,
  only_majcomp = TRUE,
  only_soilcomp = TRUE,
  remove_organic_horizons = c("none", "all", "at_surface"),
  replace_missing_fragvol_with_zero = c("none", "all", "at_surface"),
  estimate_missing_bulkdensity = FALSE,
  restrict_by_ec_or_ph = TRUE,
  impute = FALSE,
  digits = 3L,
  chunk_size = 1000L,
  progress_bar = FALSE,
  verbose = FALSE
)

Arguments

x	A numerical two-dimensional object (a matrix, array, or data.frame) with longitude/X, latitude/Y as columns; a sp::SpatialPoints object; or a terra::SpatVector object; or a sf object with a point geometry, i.e., an object with a class sf or sfc.
crs	An object which is a crs or from which one can be derived. x can be numeric as a EPSG number; a character string as a wkt; a character string as a proj4 (not recommended because outdated); or of a class including raster::Raster, sp::Spatial, sp::CRS, or a sf or sfc class.
mukeys	A character or integer vector. List of soil map unit keys for which soil information should be extracted. Provide locations or mukeys.
method	A character string. Method indicating whether SDA should query "SSURGO", "STATSGO", or "SSURGO_then_STATSGO" which attempts to replace locations without "SSURGO" soil information, e.g., due to unmapped areas, with "STATSGO" data.
sql_template	A character vector. A valid T-SQL query with a "WHERE" clause so that the code can inject chunks of bind_params values via format injection_format. If NA, then the default query is loaded, see examples.
only_majcomp	A logical value. If TRUE and extraction is from "SSURGO", then the query extracts only major components. If FALSE, then the query extracts components that are major and those that are not (see majcompflag of fetch_soils_from_NRCS_SDA). Ignored if extraction is from "STATSGO".
only_soilcomp	A logical value. If TRUE, then query restricts to soil components. If FALSE, then query includes all components including "Miscellaneous areas" and "NOTCOM" (not complete) components.
remove_organic_horizons	A character string. Method indicating how to deal with organic horizons as determined by function is_NRCS_horizon_organic. See details.
replace_missing_fragvol_with_zero	A character string. Method indicating how missing/null values of rock/gravel fragment fractions should be interpreted; passed to set_missing_soils_to_value. The options are one of "all" Missing/null values of rack/gravel fragments are replaced by 0 See also argument nullFragsAreZero of function fetchSDA. "at_surface" Missing/null values of rack/gravel fragments are replaced by 0 Note, remaining missing values in deeper horizons can subsequently be imputed by argument impute. "none" Missing/null values remain unmodified unless argument impute is activated.
estimate_missing_bulkdensity	A logical value. Estimate missing bulk density values from saturated water content and gravel volume. See estimate_bulkdensity.
restrict_by_ec_or_ph	A logical value. Include depth restrictions by ph <= 3.5 or ec >= 16. This option requires additional variables.
impute	A logical value. Impute missing values with a shallow-depth value carried deeper approach (in analogy to LOCF). Consequently, missing values in the shallowest horizon are not imputed. See impute_df.
digits	An integer value. The number of digits to which soil texture variables are rounded. Skip rounding if NA or NULL.
chunk_size	An integer value. The size of chunks into which locations is broken up and looped over for processing.
progress_bar	A logical value. Display a progress bar as the code loops over the chunks?
verbose	A logical value.

Details

NRCS soil datasets SSURGO and STATSGO are organized in soil map units mukey that are spatially explicit (i.e., we can query their values by geographic location) and within each mukey into soil map unit components cokey which have no explicit spatial arrangement within a soil map unit. Because soil texture information is specific to soil map unit components, geographic location alone is insufficient to query soil texture.

This function relies that soil information of exactly one cokey per each location or mukeys is returned by fetch_soils_from_NRCS_SDA. The default SQL template "nrcs_sql_template.sql" extracts the "dominant component". The dominant component is defined as the the first cokey with the highest representative component percent comppct_r that is a soil component. See GetDominantComponent.py from https://github.com/ncss-tech/SoilDataDevelopmentToolbox.

Whereas mukey is expected to identify the same soil map unit across different releases of the NRCS database, a component cannot be tracked by its cokey across releases. A component of a soil map unit is best identified by a unique combination of compname, comppct_r, and localphase.

The argument remove_organic_horizons is one of

"all"

All organic layers (at surface or buried) are removed and horizon number and depths are recalculated.

"at_surface"

Organic layer(s) at the soil surface are removed and horizon number and depths are recalculated. Buried organic horizons remain unmodified.

"none"

Horizons are not modified.

Notes

A live internet connection is required to access SDA.

See Also

fetchSDA and SDA_query

Examples

## Not run: 
if (curl::has_internet()) {
  locations <- matrix(
    data = c(-120.325, -111.245, 39.855, 36.753),
    nrow = 2
  )

  # Example 1: extract soils by mukey values
  extract_soils_NRCS_SDA(mukeys = c(471168, 1606800))

  # Example 2: extract soils by geographic location
  extract_soils_NRCS_SDA(x = locations)

  # Example 3: first identify mukey values by geographic location,
  # then query soils from SSURGO by mukey,
  # but still pass locations in case we need to query STATSGO as well

  mukeys <- fetch_mukeys_spatially_NRCS_SDA(
    x = locations,
    db = "SSURGO",
    progress_bar = TRUE
  )

  extract_soils_NRCS_SDA(
    x = locations,
    mukeys = mukeys[["mukeys"]],
    method = "SSURGO_then_STATSGO",
    remove_organic_horizons = "at_surface",
    replace_missing_fragvol_with_zero = "at_surface",
    estimate_missing_bulkdensity = TRUE,
    restrict_by_ec_or_ph = FALSE,
    impute = TRUE,
    progress_bar = TRUE,
    verbose = TRUE
  )
}

## End(Not run)

DrylandEcology/rSW2exter documentation built on May 4, 2024, 10:53 p.m.