-
Notifications
You must be signed in to change notification settings - Fork 19
/
fetchNASIS.R
123 lines (115 loc) · 6.55 KB
/
fetchNASIS.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
#' @title Get a pedon or component data `SoilProfileCollection` from NASIS
#'
#' @description Fetch commonly used site/pedon/horizon or mapunit component data from NASIS,
#' returned as a `SoilProfileCollection` object.
#'
#' This function imports data from NASIS into R as a `SoilProfileCollection` object.
#' It "flattens" NASIS pedon and component tables, including their child tables, into several
#' more manageable data frames. Primarily these functions access the local NASIS database using
#' an ODBC connection. The `dsn` argument allows you to specify a path or `DBIConnection`
#' to an SQLite database. The argument `from = "pedon_report"`, data can be read
#' from the NASIS Report 'fetchNASIS', from either text file or URL (specified as `url`). The primary purpose
#' of `fetchNASIS(from = "pedon_report")` is importing datasets larger than 8000+
#' pedons/components.
#'
#' The value of `nullFragsAreZero` will have a significant impact on the
#' rock fragment fractions returned by fetchNASIS. Set `nullFragsAreZero = FALSE` in those cases where there are many data-gaps and NULL rock
#' fragment values should be interpreted as NULL. Set
#' \code{nullFragsAreZero = TRUE} in those cases where NULL rock
#' fragment values should be interpreted as 0.
#'
#' This function attempts to do most of the boilerplate work when extracting
#' site/pedon/horizon or component data from a local NASIS database. Pedon IDs
#' that are missing horizon data, or have errors in their horizonation are printed on the
#' console. Pedons with combination horizons (e.g. B/C) are erroneously marked
#' as errors due to the way in which they are stored in NASIS as two
#' overlapping horizon records.
#'
#' Tutorials:
#'
#' - [fetchNASIS Columns](http://ncss-tech.github.io/soilDB/articles/fetchNASIS.html)
#' - [fetchNASIS Pedons Tutorial](http://ncss-tech.github.io/AQP/soilDB/fetchNASIS-mini-tutorial.html)
#' - [fetchNASIS Components Tutorial](http://ncss-tech.github.io/AQP/soilDB/NASIS-component-data.html)
#'
#' @aliases fetchNASIS get_phorizon_from_NASIS_db
#' 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:
#' `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
#' the results? (default: `FALSE`)
#' @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 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
#' @seealso `get_component_data_from_NASIS()`
#' @author D. E. Beaudette, J. M. Skovlin, S.M. Roecker, A.G. Brown
#'
#' @export fetchNASIS
fetchNASIS <- function(from = 'pedons',
url = NULL,
SS = TRUE,
rmHzErrors = FALSE,
nullFragsAreZero = TRUE,
soilColorState = 'moist',
mixColors = TRUE,
lab = FALSE,
fill = FALSE,
dropAdditional = TRUE,
dropNonRepresentative = TRUE,
duplicates = FALSE,
stringsAsFactors = NULL,
dsn = NULL) {
res <- NULL
if (!missing(stringsAsFactors) && is.logical(stringsAsFactors)) {
.Deprecated(msg = sprintf("stringsAsFactors argument is deprecated.\nSetting package option with `NASISDomainsAsFactor(%s)`", stringsAsFactors))
NASISDomainsAsFactor(stringsAsFactors)
}
# sanity check
if (!from %in% c('pedons', 'components', 'pedon_report')) {
stop('Must specify: pedons, components or pedon_report', call. = FALSE)
}
if (from == 'pedons') {
# pass arguments through
res <- .fetchNASIS_pedons(SS = SS,
fill = fill,
rmHzErrors = rmHzErrors,
nullFragsAreZero = nullFragsAreZero,
soilColorState = soilColorState,
mixColors = mixColors,
lab = lab,
dsn = dsn)
}
if (from == 'components') {
# pass arguments through
res <- .fetchNASIS_components(SS = SS,
rmHzErrors = rmHzErrors,
nullFragsAreZero = nullFragsAreZero,
fill = fill,
dsn = dsn,
dropAdditional = dropAdditional,
dropNotRepresentative = dropNonRepresentative,
duplicates = duplicates)
}
if (from == 'pedon_report') {
# pass arguments through
res <- .fetchNASIS_report(url = url,
rmHzErrors = rmHzErrors,
nullFragsAreZero = nullFragsAreZero,
soilColorState = soilColorState,
)
}
return(res)
}