soilDB: fetchSDA_spatial – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

fetchSDA_spatial

Query Soil Data Access and Return Spatial Data

Description

This is a high-level "fetch" method to facilitate spatial queries to Soil Data Access (SDA) based on mapunit key (mukey) and national mapunit symbol (nationalmusym) for mupolygon (SSURGO) or gsmmupolygon (STATSGO) geometry OR legend key (lkey) and area symbols (areasymbol) for sapolygon (Soil Survey Area; SSA) geometry).

A Soil Data Access spatial query is made returning geometry and key identifying information about the mapunit or area of interest. Additional columns from the mapunit or legend table can be included using add.fields argument.

This function automatically "chunks" the input vector (using soilDB::makeChunks) of mapunit identifiers to minimize the likelihood of exceeding the SDA data request size. The number of chunks varies with the chunk.size setting and the length of your input vector. If you are working with many mapunits and/or large extents, you may need to decrease this number in order to have more chunks.

Querying regions with complex mapping may require smaller chunk.size. Numerically adjacent IDs in the input vector may share common qualities (say, all from same soil survey area or region) which could cause specific chunks to perform "poorly" (slow or error) no matter what the chunk size is. Shuffling the order of the inputs using sample may help to eliminate problems related to this, depending on how you obtained your set of MUKEY/nationalmusym to query. One could feasibly use muacres as a heuristic to adjust for total acreage within chunks.

Usage

fetchSDA_spatial(
  x,
  by.col = "mukey",
  method = "feature",
  geom.src = "mupolygon",
  db = "SSURGO",
  add.fields = NULL,
  chunk.size = 10,
  verbose = TRUE
)

Arguments

`x`	A vector of MUKEYs / national mapunit symbols (for mupolygon geometry); OR legend keys (LKEY) / area symbols (for sapolygon geometry)
`by.col`	Column name containing mapunit identifier `"mukey"`, `"nmusym"`, or `"areasymbol"` for `geom.src` `sapolygon`; default is inferred from `is.numeric(x) == TRUE` for `mukey` or `lkey` and (`nationalmusym` or `areasymbol` otherwise.
`method`	geometry result type: `"feature"` returns polygons, `"bbox"` returns the bounding box of each polygon, and `"point"` returns a single point within each polygon.
`geom.src`	Either `mupolygon` or `sapolygon`
`db`	Default: SSURGO. When `geom.src` is `mupolygon`, use STATSGO polygon geometry instead of SSURGO by setting `db = "STATSGO"`
`add.fields`	Column names from `mapunit` or `legend` table to add to result. Must specify parent table name as the prefix `mapunit` before column name e.g. `mapunit.muname`.
`chunk.size`	How many queries should spatial request be divided into? Necessary for large results. Default: 10
`verbose`	Print messages?

Details

Note that STATSGO data are fetched using CLIPAREASYMBOL = 'US' to avoid duplicating state and national subsets of the geometry.

Value

A Spatial*DataFrame corresponding to SDA spatial data for all symbols requested. Default result contains geometry with attribute table containing unique feature ID, symbol and area symbol plus additional fields in result specified with add.fields.

Author(s)

Andrew G. Brown

Examples

if(requireNamespace("curl") &
   curl::has_internet()) {

   # get spatial data for a single mukey
    single.mukey <- fetchSDA_spatial(x = "2924882")

    # demonstrate fetching full extent (multi-mukey) of national musym
    full.extent.nmusym <- fetchSDA_spatial(x = "2x8l5", by = "nmusym")

    # compare extent of nmusym to single mukey within it
    if(require(sp)) {
     plot(full.extent.nmusym, col = "RED",border=0)
     plot(single.mukey, add = TRUE, col = "BLUE", border=0)
    }

    # demo adding a field (`muname`) to attribute table of result
    head(fetchSDA_spatial(x = "2x8l5", by="nmusym", add.fields="muname"))
}

soilDB

Soil Database Interface

v2.6.1

GPL (>= 3)

Authors

Dylan Beaudette [aut], Jay Skovlin [aut], Stephen Roecker [aut], Andrew Brown [aut, cre]

Initial release

2021-04-7