extract_soils_POLARIS: Extract soil information from the POLARIS soil dataset for...

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

Extract soil information from the POLARIS soil dataset for SOILWAT2 applications

Description

Extract soil information from the POLARIS soil dataset for SOILWAT2 applications

Usage

extract_soils_POLARIS(
  x,
  crs = 4326,
  vars = c("bd", "sand", "clay", "silt"),
  stat = "mean",
  path = ".",
  method = c("asis", "fix_with_buffer"),
  fix_criteria = list(bd = list(op = "<", value = 0.6), texture = list(op = "<", value =
    0.5)),
  buffer_m = NULL,
  fun = NULL,
  na.rm = TRUE,
  digits = 3L,
  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.
vars	A vector of character strings. See Chaney et al. 2019
stat	A character string. See Chaney et al. 2019
path	A character string. The path to the local copy of the POLARIS folder hierarchy, e.g., dirname(prepare_script_for_POLARIS()).
method	A character string. Method that determines extraction approach: (i) values are extracted using arguments buffer_m, fun, and na.rm and are returned "asis" or (ii) values are extracted for point locations, i.e., temporarily setting buffer_m = NULL; then, sites with problematic values (as determined by fix_criteria) are extracted again under "fix_with_buffer" based on buffer_m, fun, and na.rm
fix_criteria	A named list. Names correspond to vars or to "texture" if criterion is to be applied to the sum of sand, clay, and silt. Each element is applied to the variable of the element name to determine whether a site has problematic values. Elements are each a named list with two elements "op" for the relationship operator, e.g., "<", and "value" for the value to compare against. See examples.
buffer_m	A numeric value. The radius of a buffer around each point from which to extract cell values and across which fun is applied. Passed to extract. Set to NULL to extract POLARIS gridcell values at point locations.
fun	A function if method is either value or a named list of functions if method = "fix_with_buffer" where names correspond to vars or to "texture" if function is to be applied (individually) to sand, clay, and silt. Summarizing gridcell values if more than one value is extracted per location. See extract.
na.rm	A logical value. Passed to fun.
digits	An integer value. The number of digits to which soil texture variables are rounded. Skip rounding if NA or NULL.
verbose	A logical value.

Notes

A local copy of POLARIS is required. The function prepare_script_for_POLARIS creates a script that can be used to download POLARIS files.

POLARIS uses weight-based percent as unit for sand, clay, silt; values occur in 1 soil texture in units of weight-based fractions.

References

Chaney, N. W., B. Minasny, J. D. Herman, T. W. Nauman, C. Brungard, C. L. S. Morgan, A. B. McBratney, E. F. Wood, and Y. T. Yimam. 2019. POLARIS soil properties: 30-meter probabilistic maps of soil properties over the contiguous United States. Water Resources Research 55:2916-2938. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1029/2018WR022797")}.

See Also

extract

Examples

script_to_download_polaris <- prepare_script_for_POLARIS()

## Execute script to download data
## (or set `path_polaris` to your local copy)

path_polaris <- dirname(script_to_download_polaris)
vars <- c("bd", "sand", "clay", "silt")
stat <- "mean"

## Check that we have POLARIS data
has_POLARIS <- isTRUE(all(
  check_POLARIS(path = path_polaris, vars = vars, stat = stat)
))

if (has_POLARIS) {

  locations <- matrix(
    data = c(-120.1286878, -111.8511136, 39.8182913, 36.9047396),
    nrow = 2
  )

  ## Extract median of mean gridcell values across 100-m buffer
  ## around point locations
  res1 <- extract_soils_POLARIS(
    x = locations,
    vars = vars,
    stat = stat,
    path = path_polaris,
    buffer_m = 100,
    fun = median,
    na.rm = TRUE
  )

  ## Extract mean gridcell values at point locations and use 70-m buffer at
  ## sites with bad values
  res2 <- extract_soils_POLARIS(
    x = locations,
    vars = vars,
    stat = stat,
    path = path_polaris,
    method = "fix_with_buffer",
    fix_criteria = list(
      bd = list(op = "<", value = 0.6),
      texture = list(op = "<", value = 50)
    ),
    buffer_m = 70,
    fun = list(
      bd = function(x, na.rm = TRUE) median(x[x > 0.6], na.rm = na.rm),
      texture = median
    ),
    na.rm = TRUE,
    digits = 3
  )
}

# Clean up example
unlink(script_to_download_polaris)

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