New functions for interacting with AWDB API: Snow Courses

R/AWDB-requests-and-util.R

@@ -0,0 +1,53 @@
+##
+##
+##
+
+## 
+.AWDB_elementSets <- list(
+  'SCAN' = c(
+    "STO", "SMS", "RDC", "SAL", "PREC", "TOBS", "SRADV", 
+    "WDIRV", "WSPDV", "WSPDX", "DPTP", "PRCP", 
+    "PVPV", "RHUM", "RHUMN", "RHUMX", "SVPV", "SNWD", 
+    "NTRDV", "WDIR", "WTEQ"
+  ), 
+  'SNTL' = c(
+    "STO", "SMS", "TOBS", "RDC", "SAL", 
+    "PREC", "WTEQ", "SNWD", "PTEMP", 
+    "WDIRV", "WSPDX", "WSPDV", "SRADV", "RHUMV", "SRADX", "RHUMX", 
+    "RHUM", "SRAD", "SRADN", "RHUMN", "PRES", "SWINV", "SWOTV", "WDIRZ", 
+    "LWINV", "LWOTV", "PVPV"
+  ), 
+  'SNOW' = c("SNDN", "SNWD", "WTEQ"), 
+  'SNTLT' = c(
+    "TOBS", "SNWD", "STO", "SMS", "WSPDV", 
+    "WDIRV", "WSPDX", "PREC", "RDC", "SAL", "WDIRZ", 
+    "SMV", "SRADV", "STV", "AWDC", "RHUM", 
+    "RHUMN", "RHUMV", "RHUMX", "SRAD", "SRADN", "SRADX", "WDIR"
+  )
+)
+
+
+
+#' @title Get AWDB Element (Sensor) Metadata
+#' @description This function retrieves all element (sensor) metadata from the AWDB webservice.
+#' 
+#' @param ... Additional arguments to `.soilDB_curl_get_JSON()`, such as `timeout = 120`
+#' @return A `data.frame` unless network or server error, then `NULL`
+#' 
+get_AWDB_elements <- function(...) {
+
+  .u <- 'https://wcc.sc.egov.usda.gov/awdbRestApi/services/v1/reference-data?referenceLists=elements&visibility=all'
+  .res <- .soilDB_curl_get_JSON(.u, gzip = FALSE, quiet = TRUE, ...)
+
+  # errors result in NULL
+  if(inherits(.res, 'data.frame')) {
+    .res <- .res$elements
+  }
+
+  return(.res)
+}
+
+
+
+
+

R/SDA-spatial.R

@@ -99,20 +99,31 @@ processSDA_WKT <- function(d, g='geom', crs = 4326, p4s = NULL, as_sf = TRUE) {
 #' @aliases SDA_spatialQuery
 #'
 #' @param geom an `sf` or `Spatial*` object, with valid CRS. May contain multiple features.
+#' 
 #' @param what a character vector specifying what to return. `'mukey'`: `data.frame` with intersecting map unit keys and names, `'mupolygon'`, `'mupoint'`, `'muline'` overlapping or intersecting map unit polygons, points or lines from selected database, ``featpoint'` or `'featline'` for special feature points and lines, 'areasymbol'`: `data.frame` with intersecting soil survey areas, `'sapolygon'`: overlapping or intersecting soil survey area polygons (SSURGO only)
+#' 
 #' @param geomIntersection logical; `FALSE` (default): overlapping map unit polygons returned, `TRUE`: intersection of `geom` + map unit polygons is returned.
+#' 
 #' @param geomAcres logical; `TRUE` (default): calculate acres of result geometry in column `"area_ac"` when `what` returns a geometry column. `FALSE` does not calculate acres.
+#' 
 #' @param db a character vector identifying the Soil Geographic Databases (`'SSURGO'` or `'STATSGO'`) to query. Option \var{STATSGO} works with `what = "mukey"` and `what = "mupolygon"`.
+#' 
 #' @param byFeature Iterate over features, returning a combined data.frame where each feature is uniquely identified by value in `idcol`. Default `FALSE`.
+#' 
 #' @param idcol Unique IDs used for individual features when `byFeature = TRUE`; Default `"gid"`
+#' 
 #' @param query_string Default: `FALSE`; if `TRUE` return a character string containing query that would be sent to SDA via `SDA_query`
+#' 
 #' @param as_Spatial Return sp classes? e.g. `Spatial*DataFrame`. Default: `FALSE`.
 #'
 #' @return A `data.frame` if `what = 'mukey'`, otherwise an `sf` object. A `try-error` in the event the request cannot be made or if there is an error in the query.
-#' @note Row-order is not preserved across features in \code{geom} and returned object. Use `byFeature` argument to iterate over features and return results that are 1:1 with the inputs. Polygon area in acres is computed server-side when `what = 'mupolygon'` and `geomIntersection = TRUE`.
+#' 
+#' @note Row-order is not preserved across features in `geom` and returned object. Use `byFeature` argument to iterate over features and return results that are 1:1 with the inputs. Polygon area in acres is computed server-side when `what = 'mupolygon'` and `geomIntersection = TRUE`.
+#' 
 #' @author D.E. Beaudette, A.G. Brown, D.R. Schlaepfer
-#' @seealso \code{\link{SDA_query}}
+#' @seealso [SDA_query()]
 #' @keywords manip
+#' 
 #' @examplesIf requireNamespace("aqp") && requireNamespace("sf")
 #' \dontrun{
 #' library(aqp)
@@ -268,8 +279,10 @@ SDA_spatialQuery <- function(geom,
         query_string = query_string
       )
       res2[[idcol]] <- i
-      res2
+
+      return(res2)
     }))
+
     return(res)
   }
 
@@ -286,7 +299,8 @@ SDA_spatialQuery <- function(geom,
   if (as_Spatial && requireNamespace("sf")) {
     res <- sf::as_Spatial(res)
   }
-  res
+
+  return(res)
 }
 
 .SDA_spatialQuery <- function(geom,
@@ -447,5 +461,6 @@ SDA_spatialQuery <- function(geom,
 
     res <- suppressMessages(SDA_query(q))
   }
-  res
+
+  return(res)
 }

R/fetchSDA_spatial.R

@@ -5,15 +5,25 @@
 #' A Soil Data Access query returns geometry and key identifying information about the map unit or area of interest. Additional columns from the map unit or legend table can be included; see `add.fields` argument.
 #'
 #' @param x A vector of map unit keys (`mukey`) or national map unit symbols (`nationalmusym`) for `mupolygon`, `muline` or `mupoint`; feature keys (`featkey`) for `featpoint` and `featline`; legend keys (`lkey`) or soil survey area symbols (`areasymbol`) for `sapolygon` geometry. If `geom.src="mlrapolygon"` then `x` refers to `MLRARSYM` (major land resource area symbols).
+#' 
 #' @param by.col Column name containing map unit identifier `"mukey"`, `"nationalmusym"`, or `"ecoclassid"` for `geom.src` `mupolygon` OR `"areasymbol"`, `"areaname"`, `"mlraoffice"`, `"mouagncyresp"` for `geom.src` `sapolygon`; default is determined by `isTRUE(is.numeric(x))` for `mukey`, `featkey` or `lkey`, using `nationalmusym` or `areasymbol` otherwise.
+#' 
 #' @param method geometry result type: `"feature"` returns polygons, `"bbox"` returns the bounding box of each polygon (via `STEnvelope()`), `"point"` returns a single point (via `STPointOnSurface()`) within each polygon, `"extent"` returns an aggregate bounding box (the extent of all polygons, `geometry::EnvelopeAggregate()`) ), `"convexhull"` (`geometry::ConvexHullAggregate()`) returns the aggregate convex hull around all polygons, `"union"` (`geometry::UnionAggregate()`) and `"collection"` (`geometry::CollectionAggregate()`) return a `MULTIPOLYGON` or a `GEOMETRYCOLLECTION`, respectively, for each `mukey`, `nationalmusym`, or `areasymbol `. In the case of the latter four aggregation methods, the groups for aggregation depend on `by.col` (default by `"mukey"`).
+#' 
 #' @param geom.src Either `mupolygon` (map unit polygons), `muline` (map unit lines), `mupoint` (map unit points), `featpoint` (feature points), `featline` (feature lines), `sapolygon` (soil survey area boundary polygons), or `mlrapolygon` (major land resource area boundary polygons)
+#' 
 #' @param db Default: `"SSURGO"`. When `geom.src` is `mupolygon`, use STATSGO polygon geometry instead of SSURGO by setting `db = "STATSGO"`
+#' 
 #' @param add.fields Column names from `mapunit` or `legend` table to add to result. Must specify parent table name as the prefix before column name e.g. `mapunit.muname`.
+#' 
 #' @param chunk.size Number of values of `x` to process per query. Necessary for large results. Default: `10`
+#' 
 #' @param verbose Print messages?
+#' 
 #' @param as_Spatial Return sp classes? e.g. `Spatial*DataFrame`. Default: `FALSE`.
+#' 
 #' @return an `sf` data.frame corresponding to SDA spatial data for all symbols requested. If `as_Spatial=TRUE` returns a `Spatial*DataFrame` from the sp package via `sf::as_Spatial()` for backward compatibility. Default result contains geometry with attribute table containing unique feature ID, symbol and area symbol plus additional fields in result specified with `add.fields`.
+#' 
 #' @details
 #'
 #' This function automatically "chunks" the input vector (using `makeChunks()`) of map unit 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 map units and/or large extents, you may need to decrease this number in order to have more chunks.

data-raw/scan-snotel-current/dump-all-sites.R

@@ -0,0 +1,12 @@
+## Optionally download all SCAN, SNOTEL, and associated cooperator site metadata
+## J.M. Skovlin and D.E. Beaudette
+## 2025-03-06
+
+
+
+# all stations and cooperators
+u <- 'https://wcc.sc.egov.usda.gov/awdbRestApi/services/v1/stations'
+
+
+
+