Rd2roxygen

R/ISSR800.R

@@ -1,36 +1,37 @@
-
-#' @title ISSR-800 Web Coverage Service (WCS)
+#' ISSR-800 Web Coverage Service (WCS)
 #' 
-#' @author D.E. Beaudette and A.G. Brown
+#' Intermediate-scale gridded (800m) soil property and interpretation maps from
+#' aggregated SSURGO and STATSGO data. These maps were developed by
+#' USDA-NRCS-SPSD staff in collaboration with UCD-LAWR. Originally for
+#' educational use and [interactive thematic maps](https://casoilresource.lawr.ucdavis.edu/soil-properties/), these data are a suitable alternative to gridded STATSGO-derived thematic soil maps. The full size grids can be [downloaded here](https://casoilresource.lawr.ucdavis.edu/soil-properties/download.php)
 #' 
-#' @description Intermediate-scale gridded (800m) soil property and interpretation maps from aggregated SSURGO and STATSGO data. These maps were developed by USDA-NRCS-SPSD staff in collaboration with UCD-LAWR. Originally for educational use and \href{https://casoilresource.lawr.ucdavis.edu/soil-properties/}{interactive thematic maps}, these data are a suitable alternative to gridded STATSGO-derived thematic soil maps. The full size grids can be \href{https://casoilresource.lawr.ucdavis.edu/soil-properties/download.php}{downloaded here}.
+#' \code{aoi} should be specified as either a \code{Spatial*}, \code{sf},
+#' \code{sfc} or \code{bbox} object or a \code{list} containing:
 #' 
+#' \describe{ \item{list("aoi")}{bounding-box specified as (xmin, ymin, xmax,
+#' ymax) e.g. c(-114.16, 47.65, -114.08, 47.68)} \item{list("crs")}{coordinate
+#' reference system of BBOX, e.g. '+init=epsg:4326'} }
 #' 
+#' The WCS query is parameterized using \code{raster::extent} derived from the
+#' above AOI specification, after conversion to the native CRS (EPSG:6350) of
+#' the ISSR-800 grids.
 #' 
-#' @param aoi area of interest (AOI) defined using a \code{Spatial*}, a \code{sf}, \code{sfc} or \code{bbox} object or a \code{list}, see details
+#' Variables available from this WCS can be queried using \code{WCS_details(wcs
+#' = 'ISSR800')}.
 #' 
+#' @param aoi area of interest (AOI) defined using a \code{Spatial*}, a
+#' \code{sf}, \code{sfc} or \code{bbox} object or a \code{list}, see details
 #' @param var ISSR-800 grid name, see details
-#' 
-#' @param res grid resolution, units of meters. The native resolution of ISSR-800 grids (this WCS) is 800m.
-#' 
-#' @param quiet logical, passed to \code{download.file} to enable / suppress URL and progress bar for download.
-#'  
-#' @details \code{aoi} should be specified as either a \code{Spatial*}, \code{sf}, \code{sfc} or \code{bbox} object or a \code{list} containing:
-#' 
-#' \describe{
-#'   \item{\code{aoi}}{bounding-box specified as (xmin, ymin, xmax, ymax) e.g. c(-114.16, 47.65, -114.08, 47.68)}
-#'   \item{\code{crs}}{coordinate reference system of BBOX, e.g. '+init=epsg:4326'}
-#' }
-#' 
-#' The WCS query is parameterized using \code{raster::extent} derived from the above AOI specification, after conversion to the native CRS (EPSG:6350) of the ISSR-800 grids.
-#' 
-#' Variables available from this WCS can be queried using \code{WCS_details(wcs = 'ISSR800')}.
-#' 
-#' @note There are still some issues to be resolved related to the encoding of NA Variables with a natural zero (e.g. SAR) have 0 set to NA.
-#' 
-#' @return \code{raster} object containing indexed map unit keys and associated raster attribute table
-#' 
-#' @export
+#' @param res grid resolution, units of meters. The native resolution of
+#' ISSR-800 grids (this WCS) is 800m.
+#' @param quiet logical, passed to \code{download.file} to enable / suppress
+#' URL and progress bar for download.
+#' @return \code{raster} object containing indexed map unit keys and associated
+#' raster attribute table
+#' @note There are still some issues to be resolved related to the encoding of
+#' NA Variables with a natural zero (e.g. SAR) have 0 set to NA.
+#' @author D.E. Beaudette and A.G. Brown
+#' @export ISSR800.wcs
 ISSR800.wcs <- function(aoi, var, res = 800, quiet = FALSE) {
 
   if(!requireNamespace('rgdal', quietly=TRUE))

R/KSSL_VG_model.R

@@ -1,4 +1,3 @@
-
 # define van Genuchten model as a function
 # this is tailored to the parameters stored in our KSSL data
 # https://en.wikipedia.org/wiki/Water_retention_curve
@@ -55,13 +54,43 @@
 #' \href{https://en.wikipedia.org/wiki/Water_retention_curve}{water retention curve estimation}
 #' 
 # 'van Genuchten, M.Th. (1980). "A closed-form equation for predicting the hydraulic conductivity of unsaturated soils". Soil Science Society of America Journal. 44 (5): 892-898. 
+
+
+#' Develop a Water Retention Curve from KSSL Data
 #' 
+#' Water retention curve modeling via van Genuchten model and KSSL data.
 #' 
+#' This function was developed to work with measured or estimated parameters the [van Genuchten model](https://en.wikipedia.org/wiki/Water_retention_curve), as generated by the [ROSETTA  model](https://www.ars.usda.gov/pacific-west-area/riverside-ca/agricultural-water-efficiency-and-salinity-research-unit/docs/model/rosetta-model/). 
 #' 
-#' @export
-#'
+#' As such, \code{VG_params} should have the following format and
+#' conventions: \describe{ \item{theta_r}{saturated water content, values
+#' should be in the range of {0, 1}} \item{theta_s}{residual water content,
+#' values should be in the range of {0, 1}} \item{alpha}{related to the inverse
+#' of the air entry suction, function expects log10-transformed values with
+#' units of cm} \item{npar}{index of pore size distribution, function expects
+#' log10-transformed values with units of 1/cm} }
+#' 
+#' @param VG_params \code{data.frame} or \code{list} object with the parameters
+#' of the van Genuchten model, see details
+#' @param phi_min lower limit for water potential in kPa
+#' @param phi_max upper limit for water potential in kPa
+#' @param pts number of points to include in estimated water retention curve
+#' @return A list with the following components: \describe{
+#' \item{VG_curve}{estimated water retention curve: paired estimates of water
+#' potential (phi) and water content (theta)} \item{VG_function}{spline
+#' function for converting water potential (phi, units of kPa) to estimated
+#' volumetric water content (theta, units of percent, range: {0, 1})}
+#' \item{VG_inverse_function}{spline function for converting volumetric water
+#' content (theta, units of percent, range: {0, 1}) to estimated water
+#' potential (phi, units of kPa)} }
+#' 
+#' @note A practical example is given in the [fetchSCAN tutorial](http://ncss-tech.github.io/AQP/soilDB/fetchSCAN-demo.html).
+#'  
+#' @author D.E. Beaudette
+#' @references [water retention curve estimation](https://en.wikipedia.org/wiki/Water_retention_curve)
 #' @examples
 #' 
+#' 
 #' # basic example
 #' d <- data.frame(
 #'   theta_r = 0.0337216, 
@@ -74,6 +103,8 @@
 #' 
 #' str(vg)
 #' 
+#' 
+#' @export KSSL_VG_model
 KSSL_VG_model <- function(VG_params, phi_min=10^-6, phi_max=10^8, pts=100) {
 
   # sanity check: no NA allowed

R/OSDquery.R

@@ -1,13 +1,28 @@
-
 # https://www.postgresql.org/docs/9.5/static/textsearch-controls.html
 # these are all parameters expected by the SoilWeb OSD Fulltext search
 
-
-
-#' @title Full text searching of the USDA-NRCS Official Series Descriptions
+#' Full text searching of the USDA-NRCS Official Series Descriptions
+#' 
+#' This is an example of how chunks of text parsed from OSD records can be made search-able with [PostgreSQL full-text indexing](https://www.postgresql.org/docs/9.5/textsearch.html). This query system utilizes [special syntax](https://www.postgresql.org/docs/9.5/datatype-textsearch.html). 
+#' 
+#' Each search field (except for the "brief narrative" and MLRA) corresponds with a section header in an OSD. The results may not include every OSD due to formatting errors and typos. Results are scored based on the number of times search terms match words in associated sections. This is the R API corresponding to the [SoilWeb PostgreSQL OSD full-text search API](https://casoilresource.lawr.ucdavis.edu/osd-search/)
+#' 
+#' See \url{https://casoilresource.lawr.ucdavis.edu/osd-search/}
+#' for more information. \itemize{ \item family level taxa are derived from SC
+#' database, not parsed OSD records \item MLRA are derived via spatial
+#' intersection (SSURGO x MLRA polygons) \item MLRA-filtering is only possible
+#' for series used in the current SSURGO snapshot (component name) \item
+#' logical AND: \code{&} \item logical OR: \code{|} \item wildcard, e.g.
+#' rhy-something \verb{rhy:*} \item search terms with spaces need doubled
+#' single quotes: \verb{''san joaquin''} \item combine search terms into a
+#' single expression: \verb{(grano:* | granite)} }
+#' 
+#' Related documentation can be found in the following tutorials:
+#' 
+#'  - [Soil Series Query Functions](http://ncss-tech.github.io/AQP/soilDB/soil-series-query-functions.html)
+#'  - [Competing Soil Series](https://ncss-tech.github.io/AQP/soilDB/competing-series.html)
+#'  - [Siblings](https://ncss-tech.github.io/AQP/soilDB/siblings.html)
 #' 
-#' @description This is a rough example of how chunks of text parsed from OSD records can be made search-able with the \href{https://www.postgresql.org/docs/9.5/textsearch.html}{PostgreSQL fulltext indexing} and query system (\href{https://www.postgresql.org/docs/9.5/datatype-textsearch.html}{syntax details}). Each search field (except for the "brief narrative" and MLRA) corresponds with a section header in an OSD. The results may not include every OSD due to formatting errors and typos. Results are scored based on the number of times search terms match words in associated sections. This is the R API corresponding to \href{https://casoilresource.lawr.ucdavis.edu/osd-search/}{this webpage}.
-#'
 #' @param mlra a comma-delimited list of MLRA to search ('17,18,22A')
 #' @param taxonomic_class search family level classification
 #' @param typical_pedon search typical pedon section
@@ -17,43 +32,16 @@
 #' @param competing_series search competing series section
 #' @param geog_location search geographic setting section
 #' @param geog_assoc_soils search geographically associated soils section
-#' 
-#' @details 
-#' See \href{https://casoilresource.lawr.ucdavis.edu/osd-search/}{this webpage} for more information.
-#'
-#' * family level taxa are derived from SC database, not parsed OSD records
-#' * MLRA are derived via spatial intersection (SSURGO x MLRA polygons)
-#' * MLRA-filtering is only possible for series used in the current SSURGO snapshot (component name)
-#' * logical AND: `&`
-#' * logical OR: `|`
-#' * wildcard, e.g. rhy-something `rhy:*`
-#' * search terms with spaces need doubled single quotes: `''san joaquin''`
-#' * combine search terms into a single expression: `(grano:* | granite)`
-#' 
-#' Related documentation can be found in the following tutorials
-#' 
-#' * \href{http://ncss-tech.github.io/AQP/soilDB/soil-series-query-functions.html}{overview of all soil series query functions}
-#'   
-#' * \href{https://ncss-tech.github.io/AQP/soilDB/competing-series.html}{competing soil series}
-#'   
-#' * \href{https://ncss-tech.github.io/AQP/soilDB/siblings.html}{siblings}
-#' 
-#' @references \url{https://www.nrcs.usda.gov/wps/portal/nrcs/detailfull/soils/home/?cid=nrcs142p2_053587}
-#' 
-#' @author D.E. Beaudette
-#' 
+#' @return a \code{data.frame} object containing soil series names that match
+#' patterns supplied as arguments.
 #' @note SoilWeb maintains a snapshot of the Official Series Description data.
-#' 
+#' @author D.E. Beaudette
 #' @seealso \code{\link{fetchOSD}, \link{siblings}, \link{fetchOSD}}
-#' 
+#' @references
+#' \url{https://www.nrcs.usda.gov/wps/portal/nrcs/detailfull/soils/home/?cid=nrcs142p2_053587}
 #' @keywords manip
-#' 
-#' @return a \code{data.frame} object containing soil series names that match patterns supplied as arguments.
-#' @export
-#'
 #' @examples
 #' 
-#' 
 #' \donttest{
 #' if(requireNamespace("curl") &
 #'    curl::has_internet() &
@@ -71,6 +59,8 @@
 #' }
 #' }
 #' 
+#' 
+#' @export OSDquery
 OSDquery <- function(mlra='', taxonomic_class='', typical_pedon='', brief_narrative='', ric='', use_and_veg='', competing_series='', geog_location='', geog_assoc_soils='') {
 
   # check for required packages