Merge pull request #360 from ncss-tech/nasislocaldoc

Add helpfile on NASIS Local Database sources

R/database-sources.R

@@ -0,0 +1,17 @@
+#' NASIS Local Database
+#'
+#' This is a guide on using databases that follow the NASIS schema. Most of the time users are querying an instance of the Microsoft SQL Server NASIS local transactional database running on their computer. It is possible to create file-based "snapshots" of a local instance of the NASIS database using SQLite. See `[createStaticNASIS()]` for details. These file-based snapshots, or other custom connections, can generally be specified to NASIS-related functions via the `dsn` argument.
+#' 
+#' # Working With Coded Values and Decoding
+#' 
+#' Some values (choice lists) in NASIS are conventionally stored using numeric codes. The codes are defined by "domain" and allow for both "names" and "labels" as well as other descriptive information to be provided for each choice list element. See `get_NASIS_column_metadata()` for details.
+#' 
+#' Many soilDB functions call the function `uncode()` internally to handle conversion to human-readable values using official NASIS domains. If writing queries directly against the database source, such as a connection created with `NASIS()` or query run with `dbQueryNASIS()`, you call `uncode()` on the _data.frame_ result of your query. Conversion of internal values to choice list names is based on domains associated with result column names.
+#' 
+#' When using a custom SQLite database, sometimes values in the database are delivered pre-decoded to make the database more directly usable. An example of this would be the Kellogg Soil Survey Laboratory morphologic database, the NASIS data corresponding to the laboratory analyses available through the \link[=fetchLDM]{Lab Data Mart (LDM)}. 
+#' 
+#' To avoid issues with offsets between internal storage value and external readable value (for data such as farmland classification or Munsell color value and chroma), you should not call `uncode()` multiple times. Also, you can disable the "decoding" behavior made internally in soilDB functions by setting `options(soilDB.NASIS.skip_uncode = TRUE)`.
+#' 
+#' 
+#' @name NASISLocalDatabase
+NULL

R/fetchNASIS.R

@@ -35,25 +35,25 @@
 #' get_phfmp_from_NASIS_db
 #' get_concentrations_from_NASIS_db
 #' 
-#' @param from determines what objects should fetched? Default: `'pedons'`. Alternately, `'components'`, or `'pedon_report'`.
-#' @param url string specifying the url for the NASIS pedon_report (default:
+#' @param from Determines what objects should fetched? Default: `'pedons'`. Alternately, `'components'`, or `'pedon_report'`.
+#' @param url String specifying the url for the NASIS pedon_report (default:
 #' `NULL`)
-#' @param SS fetch data from the currently loaded selected set in NASIS or from
-#' the entire local database (default: `TRUE`)
-#' @param rmHzErrors should pedons with horizon depth errors be removed from
+#' @param SS Fetch data from the currently loaded selected set in NASIS or from
+#' the entire Local database (default: `TRUE`)
+#' @param rmHzErrors Should pedons with horizon depth errors be removed from
 #' the results? (default: `FALSE`)
-#' @param nullFragsAreZero should fragment volumes of `NULL` be interpreted as `0`?
+#' @param nullFragsAreZero Should fragment volumes of `NULL` be interpreted as `0`?
 #' (default: `TRUE`), see details
 #' @param soilColorState Used only for `from = 'pedons'`; which colors should be used to generate the convenience field `soil_color`? (`'moist'` or `'dry'`)
-#' @param mixColors should mixed colors be calculated (Default: `TRUE`) where multiple colors are populated for the same moisture state in a horizon? `FALSE` takes the dominant color for each horizon moist/dry state.
-#' @param lab should the `phlabresults` child table be fetched with site/pedon/horizon data (default: `FALSE`)
-#' @param fill include pedon or component records without horizon data in result? (default: `FALSE`)
+#' @param mixColors Should mixed colors be calculated (Default: `TRUE`) where multiple colors are populated for the same moisture state in a horizon? `FALSE` takes the dominant color for each horizon moist/dry state.
+#' @param lab Should the `phlabresults` child table be fetched with site/pedon/horizon data (default: `FALSE`)
+#' @param fill Include pedon or component records without horizon data in result? (default: `FALSE`)
 #' @param dropAdditional Used only for `from='components'` with `duplicates = TRUE`. Prevent "duplication" of `mustatus == "additional"`  mapunits? Default: `TRUE`
 #' @param dropNonRepresentative Used only for `from='components'` with `duplicates = TRUE`. Prevent "duplication" of non-representative data mapunits? Default: `TRUE`
 #' @param duplicates Used only for `from='components'`. Duplicate components for all instances of use (i.e. one for each legend data mapunit is used on; optionally for additional mapunits, and/or non-representative data mapunits?). This will include columns from `get_component_correlation_data_from_NASIS_db()` that identify which legend(s) a component is used on.
 #' @param stringsAsFactors deprecated
-#' @param dsn Optional: path to local SQLite database containing NASIS table structure; default: `NULL`
-#' @return a `SoilProfileCollection` object
+#' @param dsn Optional: path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: `NULL`
+#' @return A `SoilProfileCollection` object
 #' @seealso `get_component_data_from_NASIS()`
 #' @author D. E. Beaudette, J. M. Skovlin, S.M. Roecker, A.G. Brown
 #' 

R/get_RMF_from_NASIS_db.R

@@ -6,7 +6,7 @@
 #'
 #' @param SS logical, limit query to the selected set
 #'
-#' @param dsn optional path to local SQLite database containing NASIS table structure; default: `NULL`
+#' @param dsn optional path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: `NULL`
 #' 
 #' @return a `list` with two `data.frame` objects:
 #'   * `RMF`: contents of "phrdxfeatures" table, often >1 row per horizon

R/get_soilseries_from_NASIS.R

@@ -4,7 +4,7 @@
 #' from the local NASIS database (all series) or via web report (named series
 #' only).
 #' @param stringsAsFactors deprecated
-#' @param dsn Optional: path to local SQLite database containing NASIS table structure; default: `NULL`
+#' @param dsn Optional: path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: `NULL`
 #' @param delimiter _character_. Used to collapse `taxminalogy` records where multiple values are used to describe strongly contrasting control sections. Default `" over "` creates combination mineralogy classes as they would be used in the family name.
 #' @param SS _logical_. Fetch data from the currently loaded selected set in NASIS or from the entire local database (default: `FALSE`; this is to allow for queries against the full Series Classification database as default)
 #' @return A \code{data.frame}

R/uncode.R

@@ -179,7 +179,7 @@ NASISDomainsAsFactor <- function(x = NULL) {
 #' 
 #' These data are derived from the MetadataDomainDetail, MetadataDomainMaster, and MetadataTableColumn tables and help with mapping between values stored in the NASIS database and human-readable values. The human-readable values align with the values returned in public facing interfaces such as SSURGO via Soil Data Access and NASIS Web Reports. The data in these tables can also be used to create _ordered_ factors where options for levels of a particular data element follow a logical `ChoiceSequence`.
 #'
-#' @param dsn Optional: path to local SQLite database containing NASIS table structure; default: `NULL`
+#' @param dsn Optional: path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: `NULL`
 #' @param include_description Include "ChoiceDescription" column? Default: `FALSE`
 #' @details If a local NASIS instance is set up, and this is the first time `get_NASIS_metadata()` has been called, the metadata will be obtained from the NASIS local database. Subsequent runs in the same session will use a copy of the data object `NASIS.metadata` cached in `soilDB.env` which can be accessed with `get_soilDB_env()$NASIS.metadata`.
 #' 
@@ -268,7 +268,7 @@ get_NASIS_column_metadata <- function(x,
 #' @param droplevels Drop unused factor levels? Default: `TRUE` (used only when `factor=TRUE`)
 #' @param ordered Should the result be an ordered factor? Default: `TRUE` (use _only_ if `DomainRanked` is true for all choices)
 #' @param simplify Should list result with length 1 be reduced to a single vector? Default: `TRUE`
-#' @param dsn Optional: path to local SQLite database containing NASIS table structure; default: NULL
+#' @param dsn Optional: path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: NULL
 #' @return A list of "choices" based on the input `x` that have been converted to a consistent target set of levels (specified by `choice`) via NASIS 7 metadata. 
 #' 
 #' When `factor=TRUE` the result is a factor, possibly ordered when `ordered=TRUE` and the target domain is a "ranked" domain (i.e. `ChoiceSequence` has logical meaning).
@@ -363,7 +363,7 @@ NASISChoiceList <- function(x = NULL,
 #' @param what.table Column to match `table` against. Default: `TablePhysicalName`.
 #' @param what.column Column to match `column` against. Default: `ColumnPhysicalName`.
 #' @param query_string Default: `FALSE`; if `TRUE` return a character containing query that would be sent to NASIS.
-#' @param dsn Optional: path to local SQLite database containing NASIS table structure; default: `NULL`
+#' @param dsn Optional: path or _DBIConnection_ to \link[=NASISLocalDatabase]{local database containing NASIS table structure}; default: `NULL`
 #' @details For NASIS choice lists based on domain and column names see `get_NASIS_metadata()` and `NASISChoiceList()`. This function (`get_NASIS_table_metadata()`) is intended for higher-level description of the expected contents of a NASIS database instance, rather than the codes/specific values used within columns.
 #' @seealso `get_NASIS_metadata()` `NASISChoiceList()` `uncode()` `code()`
 #' @return a `data.frame`