Introduction

This document demonstrates how to use the soilDB package to download KSSL data from SoilWeb. These data are from the September 2016 snapshot, and will be updated as future snapshots are released. Comparisons are made via graphical summaries of key soil properties with depth, using data structures and functions from the aqp package.

Installation

With a recent version of R (>= 2.15), it is possible to get all of the packages that this tutorial depends on via:

# stable packages from CRAN
install.packages('maps', dep=TRUE)
install.packages('plyr', dep=TRUE)
install.packages('reshape2', dep=TRUE)
install.packages('soilDB', dep=TRUE)

# latest versions from GitHub
devtools::install_github("ncss-tech/aqp", dependencies=FALSE, upgrade_dependencies=FALSE)
devtools::install_github("ncss-tech/soilDB", dependencies=FALSE, upgrade_dependencies=FALSE)

Quick Example: getting lab characterization (KSSL) and basic morphology (NASIS)

KSSL data are from the September 2016 snapshot, NASIS data are from the April 2016 snapshot. Details pending.

library(soilDB)
library(plyr)
library(reshape2)


# get lab and morphologic data
s <- fetchKSSL(series='auburn', returnMorphologicData = TRUE)

# the result is a list, check it out
str(s, 2)
## List of 2
##  $ SPC  :Formal class 'SoilProfileCollection' [package "aqp"] with 7 slots
##  $ morph:List of 4
##   ..$ phcolor    :'data.frame':  132 obs. of  6 variables:
##   ..$ phfrags    :'data.frame':  40 obs. of  9 variables:
##   ..$ phpores    :'data.frame':  94 obs. of  5 variables:
##   ..$ phstructure:'data.frame':  55 obs. of  6 variables:
# check out the "raw" morphologic data:
lapply(s$morph, head)
## $phcolor
##   labsampnum colorpct colorhue colorvalue colorchroma colormoistst
## 1   10N04396       NA    7.5YR          4           2        Moist
## 2   10N04396       NA    7.5YR          5           3          Dry
## 3   10N04397       NA    7.5YR          3           3        Moist
## 4   10N04397       NA    7.5YR          5           4          Dry
## 5   10N04398       NA    7.5YR          4           4        Moist
## 6   10N04398       NA    7.5YR          5           4          Dry
## 
## $phfrags
##   labsampnum fragvol             fragkind fragsize_l fragsize_r fragsize_h fragshp fraground
## 1   10N04396       2 Greenstone fragments          2          3          5      NA        NA
## 2   10N04397       4 Greenstone fragments          2         10         20      NA        NA
## 3   10N04397       2 Greenstone fragments          2         10         20      NA        NA
## 4   10N04398       2 Greenstone fragments          2          3          5      NA        NA
## 5   10N04398       1 Greenstone fragments          2         10         20      NA        NA
## 6   10N04399       7 Greenstone fragments          2          3          5      NA        NA
##            fraghard
## 1   Weakly cemented
## 2 Strongly cemented
## 3   Weakly cemented
## 4   Weakly cemented
## 5 Strongly cemented
## 6   Weakly cemented
## 
## $phpores
##   labsampnum poreqty  poresize porecont   poreshp
## 1   10N04396     0.8 Very fine       NA Irregular
## 2   10N04396     0.8    Medium       NA   Tubular
## 3   10N04397     0.8 Very fine       NA Irregular
## 4   10N04397     0.8    Medium       NA   Tubular
## 5   10N04398     3.0 Very fine       NA Irregular
## 6   10N04398     0.8    Medium       NA   Tubular
## 
## $phstructure
##   labsampnum structgrade structsize        structtype structid structpartsto
## 1   10N04396    Moderate       Fine          Granular       NA            NA
## 2   10N04397    Moderate     Medium Subangular blocky       NA            NA
## 3   10N04398    Moderate     Medium Subangular blocky       NA            NA
## 4   10N04399    Moderate     Medium Subangular blocky       NA            NA
## 5   40A23590        <NA>       <NA>           Massive       NA            NA
## 6   40A23592        <NA>       <NA>           Massive       NA            NA
# extract pedons into SoilProfileCollection
pedons <- s$SPC

# simplify color data
# note that both horizon ID and color "percentage" must be specified
s.colors <- simplifyColorData(s$morph$phcolor, id.var = 'labsampnum', wt='colorpct')

# merge color data into SPC
h <- horizons(pedons)
h <- join(h, s.colors, by='labsampnum', type='left', match='first')
horizons(pedons) <- h

# check
par(mar=c(0,0,0,0))
plot(pedons, color='moist_soil_color', print.id=FALSE, name='hzn_desgn')

# simplify fragment data
s.frags <- simplfyFragmentData(s$morph$phfrags, id.var='labsampnum')

# merge fragment data into SPC
h <- horizons(pedons)
h <- join(h, s.frags, by='labsampnum', type='left', match='first')
horizons(pedons) <- h


# check
par(mar=c(0,0,3,0))
plot(pedons, color='total_frags_pct', print.id=FALSE, name='hzn_desgn')

Fetch Data Associated with a Set of IDs

Fetching KSSL data for a set of IDs requires some additional "helper" functions. The following example fetches data according to a vector of "pedlabsampnum" IDs, extracts the horizon color data, filters missing data, and combines the results into a single table.

First, paste the following code into your script or console to initialize our helper functions.

# get data associated with a single ID
# no records -> NULL returned
getPedons <- function(x) {
  suppressMessages(fetchKSSL(pedlabsampnum=x, returnMorphologicData = TRUE))
}

# extract a morphologic table from each record set
# NULL data are filtered out
# converted to data.frame
extractMorphTable <- function(x, table='phcolor') {
  m <- lapply(x, function(i) i[['morph']][[table]])
  # index pedons with data
  idx <- which(sapply(m, length) > 0) 
  if(length(idx) < 1)
    return(NULL)
  # filter non-NULL and convert to DF
  m <- ldply(m[idx])
  return(m)
}

Next, use the getPedons() helper function to fetch lab and morphologic data according to a vector of pedlabsampnum IDs. Note that the results are a list of lists. Select morphologic data are extracted and combined with the extractMorphTable() function.

# pedons indexed by "pedlabsampnum" ID
pls <- c("04N0610", "04N0611", "04N0612", "04N0613")
# iterate over IDs and get data
res <- lapply(pls, getPedons)

# check: OK
str(res, 2)
## List of 4
##  $ :List of 2
##   ..$ SPC  :Formal class 'SoilProfileCollection' [package "aqp"] with 7 slots
##   ..$ morph:List of 4
##  $ :List of 2
##   ..$ SPC  :Formal class 'SoilProfileCollection' [package "aqp"] with 7 slots
##   ..$ morph:List of 4
##  $ :List of 2
##   ..$ SPC  :Formal class 'SoilProfileCollection' [package "aqp"] with 7 slots
##   ..$ morph:List of 4
##  $ :List of 2
##   ..$ SPC  :Formal class 'SoilProfileCollection' [package "aqp"] with 7 slots
##   ..$ morph:List of 4
# extract phcolor data from list of records
# result is a data.frame with all non-NULL rows
phcolor <- extractMorphTable(res, table='phcolor')

# check: OK
head(phcolor)
##   labsampnum colorpct colorhue colorvalue colorchroma colormoistst
## 1   04N03392       NA     10YR          3           2        Moist
## 2   04N03392        2     10YR          4           6        Moist
## 3   04N03393        2    2.5YR          4           6         <NA>
## 4   04N03393       NA     10YR          3           1         <NA>
## 5   04N03393        1     10YR          4           3        Moist
## 6   04N03394       NA    7.5YR          5           8        Moist

Finally, extract the SoilProfileCollection objects from res and combine into a single object. We can now join our combined color data with the combined pedon data.

# extract pedons from list
pedons <- lapply(res, function(i) i$SPC)
# combine into a single SPC object
pedons <- do.call('rbind', pedons)

# check: looks good
plot(pedons, color='estimated_ph_h2o', name='hzn_desgn')