A collection of functions to support soil survey

Description

This package contains mish-mash of functionality and sample data related to the daily business of soil survey operations with the USDA-NRCS. Many of the functions are highly specialized and inherit default arguments from the names used by the various NCSS (National Cooperative Soil Survey) databases. A detailed description of this package with links to associated tutorials can be found at the project website.

CDEC Snow Course List

Description

The CDEC snow course list, updated September 2019

Usage

data(CDEC.snow.courses)

Format

A data frame with 259 observations on the following 9 variables.

course_number

course number

name

connotative course label

id

course ID

elev_feet

course elevation in feet

latitude

latitude

longitude

longitude

april.1.Avg.inches

average inches of snow as of April 1st

agency

responsible agency

watershed

watershed label

Source

Data were scraped from http://cdec.water.ca.gov/misc/SnowCourses.html, 2019.

Examples

data(CDEC.snow.courses)
head(CDEC.snow.courses)

CDEC Sensor Details (by Station)

Description

Query CDEC Website for Sensor Details

Usage

CDEC_StationInfo(s)

Arguments

Details

This function requires the rvest package.

Value

A list object containing site metadata, sensor metadata, and possibly comments about the site.

Author(s)

D.E. Beaudette

See Also

⁠[CDECquery]⁠

Easy Access to the CDEC API

Description

A (relatively) simple interface to the CDEC website.

Usage

CDECquery(id, sensor, interval = "D", start, end)

Arguments

Details

Sensors that report data on an ⁠interval other than monthly ('M'), daily ('D'), or hourly ('H') can be queried with an ⁠event‘ interval (’E'). Soil moisture and temperature sensors are an example of this type of reporting. See examples below.

1.

Station IDs can be found here: http://cdec.water.ca.gov/staInfo.html

2a.

Sensor IDs can be found using this URL: http://cdec.water.ca.gov/dynamicapp/staMeta?station_id=, followed by the station ID.

2b.

Sensor details can be accessed using CDEC_StationInfo with the station ID.

3.

Reservoir capacities can be found here: http://cdec.water.ca.gov/misc/resinfo.html

4.

A new interactive map of CDEC stations can be found here: http://cdec.water.ca.gov

Value

A data.frame with the following fields: datetime, year, month, value.

Author(s)

D.E. Beaudette

References

http://cdec.water.ca.gov/queryCSV.html

See Also

CDECsnowQuery(), CDEC_StationInfo()

Get snow survey data (California only) from the CDEC website.

Description

Get snow survey data (California only) from the CDEC website.

Usage

CDECsnowQuery(course, start_yr, end_yr)

Arguments

Details

This function downloads data from the CDEC website, therefore an internet connection is required. The SWE column contains adjusted SWE if available (Adjusted column), otherwise the reported SWE is used (Water column). See the tutorial for examples.

Value

A data.frame with results from CDEC.

Note

Snow course locations, ID numbers, and other information can be found here: http://cdec.water.ca.gov/misc/SnowCourses.html

Author(s)

D.E. Beaudette

References

http://cdec.water.ca.gov/cgi-progs/snowQuery

Estimate Effective Sample Size

Description

Estimation of effective sample size (ESS). See Fortin & Dale 2005, p. 223, Equation 5.15 using global Moran's I as 'rho'.

Usage

ESS_by_Moran_I(n, rho)

Arguments

Value

numeric; estimated Effective Sample Size

Author(s)

D.E. Beaudette

References

Fortin, M.J. and Dale, M.R.T. (2005) Spatial Analysis: A Guide for Ecologists. Cambridge University Press, Cambridge, 1-30.

Frost-Free Day Evaluation

Description

Evaluation frost-free days and related metrics from daily climate records.

Usage

FFD(
  d,
  returnDailyPr = TRUE,
  minDays = 165,
  frostTemp = 32,
  endSpringDOY = 182,
  startFallDOY = 213
)

Arguments

Details

The default frostTemp=32 is suitable for use with minimum daily temperatures in degrees Fahrenheit. Use frostTemp = 0 for temperatures in degrees Celsius.

FFD tutorial

Value

a data.frame when a returnDailyPr = FALSE, otherwise a list with the following elements:

• summary: FFD summary statistics as a data.frame

• fm: frost matrix

• Pr.frost: Pr(frost|day): daily probability of frost

Author(s)

D.E. Beaudette

Examples

# 11 years of data from highland meadows
data('HHM', package = 'sharpshootR')
x.ffd <- FFD(HHM, returnDailyPr = FALSE, frostTemp = 32)

str(x.ffd)

Plot output from FFD()

Description

Plot output from FFD()

Usage

FFDplot(s, sub.title = NULL)

Arguments

Value

nothing, function is called to generate graphical output

Examples

# 11 years of data from highland meadows
data('HHM', package = 'sharpshootR')
x.ffd <- FFD(HHM, returnDailyPr = TRUE, frostTemp=32)

FFDplot(x.ffd)

Highland Meadows

Description

11 years of climate data from the Highland Meadows weather station, as maintained by CA DWR.

Usage

data("HHM")

Format

A data frame with 3469 observations on the following 12 variables.

station_id

a character vector

dur_code

a character vector

sensor_num

a numeric vector

sensor_type

a character vector

value

a numeric vector

flag

a character vector

units

a character vector

datetime

a POSIXct

year

a numeric vector

month

a factor with levels January February March April May June July August September October November December

water_year

a numeric vector

water_day

a numeric vector

Sensor Data Timeline from Henry Mount Soil and Water DB

Description

This function generates a simple chart of start/end dates for non-NA sensor data returned by soilDB::fetchHenry(). Data are organized according to sensor name + sensor depth.

Usage

HenryTimeLine(sensor_data, ...)

Arguments

Value

a lattice graphics object

Author(s)

D.E. Beaudette

LL2PLSS

Description

Uses latitude and longitude coordinates to return the PLSS section geometry from the BLM PLSS web service.

Usage

LL2PLSS(x, y, returnlevel = c("I", "S"))

Arguments

Details

This function accepts geographic coordinates and returns the PLSS fabric geometry to the quarter-quarter section. returnlevel defaults to 'I' which returns smallest intersected sectional aliquot geometry, 'S' will return the section geometry of the coordinates. See https://gis.blm.gov/arcgis/rest/services/Cadastral/BLM_Natl_PLSS_CadNSDI/MapServer for details.

Value

sf object with geometry and PLSS definition.

Note

This function requires the following packages: httr, jsonlite, and sf.

Author(s)

D.E. Beaudette, Jay Skovlin, A.G. Brown

See Also

PLSS2LL(), formatPLSS()

Compute Moran's I for a raster sampled from a mapunit extent

Description

Compute Moran's I using a subset of sample collected within the extent of a mapunit. This is likely an under-estimate of SA because we are including pixels both inside/outside MU delineations

Usage

Moran_I_ByRaster(
  r,
  mu.extent = NULL,
  n = NULL,
  k = NULL,
  do.correlogram = FALSE,
  cor.order = 5,
  crop.raster = TRUE
)

Arguments

Details

This function uses the spdep::moran.test() function

Value

If do.correlogram is TRUE a list with estimated Moran's I (⁠$I⁠) and the correlogram (⁠$correlogram⁠), otherwise the estimated Moran's I value.

Author(s)

D.E. Beaudette

Example output from soilDB::fetchOSD()

Description

These example data are used to test various functions in this package when network access may be limited.

Usage

data(OSDexamples)

Format

An object of class list of length 18.

Percentiles of Cumulative Precipitation

Description

Generate a plot representing percentiles of cumulative precipitation, given a historic record, and criteria for selecting a year of data for comparison.

Usage

PCP_plot(
  x,
  this.year,
  this.day = NULL,
  method = "exemplar",
  q.color = "RoyalBlue",
  c.color = "firebrick",
  ...
)

Arguments

Details

This is very much a work in progress. Further examples at https://ncss-tech.github.io/AQP/sharpshootR/CDEC.html, and https://ncss-tech.github.io/AQP/sharpshootR/cumulative-PPT.html.

Value

nothing, this function is called to create graphical output

Author(s)

D.E. Beaudette

See Also

soilDB::waterDayYear()

PLSS2LL

Description

Fetch latitude and longitude (centroid) coordinates for coded PLSS information from the BLM PLSS web service.

Usage

PLSS2LL(p, plssid = "plssid")

Arguments

Value

A data.frame of PLSS codes and coordinates.

Note

This function expects that the input p will have a 'plssid' column generated by the formatPLSS() function. Requires the following packages: httr, and jsonlite.

Author(s)

D.E. Beaudette, Jay Skovlin, A.G. Brown

See Also

LL2PLSS(), formatPLSS()

Soil Taxonomy Dendrogram

Description

Plot a dendrogram based on the first 4 levels of Soil Taxonomy, with soil profiles hanging below. A dissimilarity matrix is computed using Gower's distance metric for nominal (KST.order = FALSE) or ordinal (KST.order = TRUE) scale variables, based on soil order, suborder, greatgroup, and subgroup taxa.

Usage

SoilTaxonomyDendrogram(
  spc,
  KST.order = TRUE,
  rotationOrder = NULL,
  level = c(soilorder = "soilorder", suborder = "suborder", greatgroup = "greatgroup",
    subgroup = "subgroup"),
  cluster.method = c("divisive", "agglomerative"),
  cluster.args = list(),
  name = "hzname",
  name.style = "center-center",
  id.style = "side",
  n.depth.ticks = 6,
  scaling.factor = 0.015,
  cex.names = 0.75,
  cex.id = 0.75,
  width = 0.25,
  y.offset = 0.5,
  shrink = FALSE,
  font.id = 2,
  cex.taxon.labels = 0.66,
  font.taxon.labels = 3,
  dend.color = par("fg"),
  dend.width = 1,
  dend.type = c("phylogram", "cladogram"),
  max.depth = ifelse(is.infinite(max(spc)), 200, max(spc)),
  ...
)

Arguments

Details

This function looks for specific site-level attributes named: "soilorder", "suborder", "greatgroup", and "subgroup", or their NASIS physical column name analogues "taxorder", "taxsuborder", "taxgrtgroup", and "taxsubgrp". See https://github.com/ncss-tech/sharpshootR/blob/master/misc/soilTaxonomyDendrogram-examples.R for some examples.

The rotationOrder argument uses ape::rotateConstr() to reorder leaves within the hclust representation of the ST hierarchy. Perfect sorting is not always possible.

Value

An invisibly-returned list containing:

• dist: pair-wise dissimilarity matrix

• order: final ordering of hclust leaves

Author(s)

D.E. Beaudette

SSURGO Data Associated with the Amador Soil Series

Description

SSURGO Data Associated with the Amador Soil Series

Usage

data(amador)

Format

A subset of data taken from the "component" table of SSURGO

mukey

map unit key

compname

component name

comppct_r

component percentage

Source

USDA-NRCS SSURGO Database

Plot Aspect Data

Description

Plot a graphical summary of multiple aspect measurements on a circular diagram.

Usage

aspect.plot(
  p,
  q = c(0.05, 0.5, 0.95),
  p.bins = 60,
  p.bw = 30,
  stack = TRUE,
  p.axis = seq(0, 350, by = 10),
  plot.title = NULL,
  line.col = "RoyalBlue",
  line.lwd = 1,
  line.lty = 2,
  arrow.col = line.col,
  arrow.lwd = 1,
  arrow.lty = 1,
  arrow.length = 0.15,
  ...
)

Arguments

Details

Spread and central tendency are depicted with a combination of circular histogram and kernel density estimate. The circular mean, and relative confidence in that mean are depicted with an arrow: longer arrow lengths correspond to greater confidence in the mean.

Value

This function is primarily called for graphical output, also invisibly returns circular stats.

Note

Manual adjustment of p.bw may be required in order to get an optimal circular density plot. This function requires the package circular, version 0.4-7 or later.

Author(s)

D.E. Beaudette

Examples

# simulate some data
p.narrow <- runif(n = 25, min = 215, max = 280)
p.wide <- runif(n = 25, min = 0, max = 270)

# set figure margins to 0, 2-column plot
op <- par(no.readonly = TRUE)
par(mar = c(0, 0, 0, 0), mfcol = c(1, 2))

# plot, save circular stats 
x <- aspect.plot(p.narrow, p.bw = 10, 
plot.title = 'Soil A', pch = 21, col = 'black', bg = 'RoyalBlue')

y <- aspect.plot(p.wide, p.bw = 10, 
plot.title = 'Soil B', pch = 21, col = 'black', bg = 'RoyalBlue')

# reset output device options
par(op) 

x

Create a Venn Diagram of Simulated Color Mixtures

Description

Create a Venn Diagram of Simulated Color Mixtures

Usage

colorMixtureVenn(
  chips,
  w = rep(1, times = length(chips))/length(chips),
  mixingMethod = "exact",
  ellipse = FALSE,
  labels = TRUE,
  names = FALSE,
  sncs = 0.85
)

Arguments

Value

This function is called to create graphical output, nothing returned.

Examples

if(requireNamespace("venn") & requireNamespace("gower")) {

chips <- c('10YR 8/1', '2.5YR 3/6', '10YR 2/2')
names(chips) <- c("tan", "dark red", "dark brown")

colorMixtureVenn(chips)
colorMixtureVenn(chips, names = TRUE)

colorMixtureVenn(chips, w = c(1, 1, 1), names = TRUE)
colorMixtureVenn(chips, w = c(10, 5, 1), names = TRUE)

}

Create an adjacency matrix from a data.frame of component data

Description

Create an adjacency matrix from SSURGO component data

Usage

component.adj.matrix(
  d,
  mu = "mukey",
  co = "compname",
  wt = "comppct_r",
  method = c("community.matrix", "occurrence"),
  standardization = "max",
  metric = "jaccard",
  rm.orphans = TRUE,
  similarity = TRUE,
  return.comm.matrix = FALSE
)

Arguments

Value

A similarity or adjacency matrix suitable for use with igraph functions or anything else that can accommodate a similarity matrix.

Author(s)

D.E. Beaudette

Examples

if (requireNamespace("igraph") && requireNamespace("vegan")) {
  # load sample data set
  data(amador)

  # convert into adjacency matrix
  m <- component.adj.matrix(amador)

  # plot network diagram, with Amador soil highlighted
  plotSoilRelationGraph(m, s = 'amador')
}

Sample Polygons at a Fixed Density

Description

Perform constant-density sampling of polygons.

Usage

constantDensitySampling(
  x,
  polygon.id = "pID",
  n.pts.per.ac = 1,
  min.samples = 5,
  sampling.type = "regular"
)

Arguments

Value

SpatVector of sample points

Author(s)

D.E. Beaudette

Simple Daily Water Balance

Description

Simple interface to the hydromad "leaky bucket" soil moisture model, with accommodation for typical inputs from common soil data and climate sources. Critical points along the water retention curve are specified using volumetric water content (VWC): satiation (saturation), field capacity (typically 1/3 bar suction), and permanent wilting point (typically 15 bar suction).

Usage

dailyWB(x, daily.data, id, MS.style = "default", S_0 = 0.5, M = 0, etmult = 1)

Arguments

Value

a data.frame

References

Farmer, D., M. Sivapalan, Farmer, D. (2003). Climate, soil and vegetation controls upon the variability of water balance in temperate and semiarid landscapes: downward approach to water balance analysis. Water Resources Research 39(2), p 1035.

Bai, Y., T. Wagener, P. Reed (2009). A top-down framework for watershed model evaluation and selection under uncertainty. Environmental Modelling and Software 24(8), pp. 901-916.

Perform daily water balance modeling using SSURGO and DAYMET

Description

Pending.

Usage

dailyWB_SSURGO(
  x,
  cokeys = NULL,
  start = 1988,
  end = 2018,
  modelDepth = 100,
  MS.style = "default",
  a.ss = 0.1,
  S_0 = 0.5,
  bufferRadiusMeters = 1
)

Arguments

Value

data.frame of daily water balance results

Author(s)

D.E. Beaudette

References

Farmer, D., M. Sivapalan, Farmer, D. (2003). Climate, soil and vegetation controls upon the variability of water balance in temperate and semiarid landscapes: downward approach to water balance analysis. Water Resources Research 39(2), p 1035.

Diagnostic Property Plot (base graphics)

Description

Generate a graphical description of the presence/absence of soil diagnostic properties.

Usage

diagnosticPropertyPlot(
  f,
  v,
  k,
  grid.label = "upedonid",
  dend.label = "upedonid",
  sort.vars = TRUE
)

Arguments

Details

This function attempts to display several pieces of information within a single figure. First, soil profiles are sorted according to the presence/absence of diagnostic features named in v. Second, these diagnostic features are sorted according to their distribution among soil profiles. Third, a binary grid is established with row-ordering of profiles based on step 1 and column-ordering based on step 2. Blue cells represent the presence of a diagnostic feature. Soils with similar diagnostic features should 'clump' together. See examples below.

Value

a list is silently returned by this function, containing:

rd

a data.frame containing IDs and grouping code

profile.order

a vector containing the order of soil profiles (row-order in figure), according to diagnostic property values

var.order

a vector containing the order of variables (column-order in figure), according to their distribution among profiles

Author(s)

D.E. Beaudette and J.M. Skovlin

See Also

multinominal2logical()

Diagnostic Property Plot (lattice)

Description

Generate a graphical description of the presence/absence of soil diagnostic properties.

Usage

diagnosticPropertyPlot2(f, v, k, grid.label = "upedonid", sort.vars = TRUE)

Arguments

Details

This function attempts to display several pieces of information within a single figure. First, soil profiles are sorted according to the presence/absence of diagnostic features named in v. Second, these diagnostic features are sorted according to their distribution among soil profiles. Third, a binary grid is established with row-ordering of profiles based on step 1 and column-ordering based on step 2. Blue cells represent the presence of a diagnostic feature. Soils with similar diagnostic features should 'clump' together. See examples below.

Value

a list is silently returned by this function, containing:

rd

a data.frame containing IDs and grouping code

profile.order

a vector containing the order of soil profiles (row-order in figure), according to diagnostic property values

var.order

a vector containing the order of variables (column-order in figure), according to their distribution among profiles

Author(s)

D.E. Beaudette and J.M. Skovlin

See Also

multinominal2logical

Compute Euclidean distance along a gradient.

Description

This function computes Euclidean distance along points aligned to a given gradient (e.g. elevation).

Usage

dist.along.grad(coords, var, grad.order, grad.scaled.min, grad.scaled.max)

Arguments

Details

This function is primarily intended for use within plotTransect.

Value

A data.frame object:

scaled.grad

scaled gradient values

scaled.distance

cumulative distance, scaled to the interval of 0.5, nrow(coords) + 0.5

distance

cumulative distance computed along gradient, e.g. transect distance

variable

sorted gradient values

x

x coordinates, ordered by gradient values

y

y coordinate, ordered by gradient values

grad.order

a vector index describing the sort order defined by gradient values

Note

This function is very much a work in progress, ideas welcome.

Author(s)

D.E. Beaudette

See Also

plotTransect

Dueling Dendrograms

Description

Graphically compare two related dendrograms

Usage

dueling.dendrograms(
  p.1,
  p.2,
  lab.1 = "D1",
  lab.2 = "D2",
  cex.nodelabels = 0.75,
  arrow.length = 0.05
)

Arguments

Details

Connector arrows are used to link nodes from the left-hand dendrogram to the right-hand dendrogram.

Value

nothing is returned, function is called to generate graphical output

Author(s)

D.E. Beaudette

A very simple estimation of soil moisture state based on volumetric water content

Description

This is a very simple classification of volumetric water content (VWC) into 5 "moisture states", based on an interpretation of water retention thresholds. Classification is performed using VWC at satiation, field capacity (typically 1/3 bar suction), permanent wilting point (typically 15 bar suction), and water surplus in mm. The inputs to this function are closely aligned with the assumptions and output from hydromad::hydromad(sma = 'bucket', ...).

Soil moisture classification rules are as follows:

• VWC <= pwp: "very dry"

• VWC > pwp AND <= (mid-point between fc and pwp): "dry"

• VWC > (mid-point between fc and pwp) AND <= fc: "moist"

• VWC > fc: "very moist"

• VWC > fc AND U (surplus) > 4mm: "wet"

Usage

estimateSoilMoistureState(
  VWC,
  U,
  sat,
  fc,
  pwp,
  style = c("default", "newhall")
)

Arguments

Value

vector of moisture states (ordered factor)

Author(s)

D.E. Beaudette

Examples

# "very moist"
estimateSoilMoistureState(VWC = 0.3, U = 0, sat = 0.35, fc = 0.25, pwp = 0.15)
estimateSoilMoistureState(VWC = 0.3, U = 2, sat = 0.35, fc = 0.25, pwp = 0.15)

"wet"
estimateSoilMoistureState(VWC = 0.3, U = 5, sat = 0.35, fc = 0.25, pwp = 0.15)

# "very dry"
estimateSoilMoistureState(VWC = 0.15, U = 0, sat = 0.35, fc = 0.25, pwp = 0.15)

# "dry" 
estimateSoilMoistureState(VWC = 0.18, U = 0, sat = 0.35, fc = 0.25, pwp = 0.15)

formatPLSS

Description

Format PLSS information into a coded format that can be digested by PLSS web service.

Usage

formatPLSS(p, type = "SN")

Arguments

Details

This function is typically accessed as a helper function to prepare data for use within PLSS2LL() function.

Value

A vector of PLSS codes.

Note

This function expects that the Polygon object has coordinates associated with a projected CRS– e.g. units of meters.

This function requires the following packages: stringi.

Author(s)

D.E. Beaudette, Jay Skovlin, A.G. Brown

See Also

PLSS2LL()

Examples

# create some data
d <- data.frame(
  id = 1:3,
  qq = c('SW', 'SW', 'SE'),
  q = c('NE', 'NW', 'SE'),
  s = c(17, 32, 30),
  t = c('T36N', 'T35N', 'T35N'),
  r = c('R29W', 'R28W', 'R28W'),
  type = 'SN',
  m = 'MT20',
  stringsAsFactors = FALSE
)
# add column names

names(d) <- c('id', 'qq', 'q', 's', 't', 'r', 'type', 'm')
# generate formatted PLSS codes
formatPLSS(d, type='SN')

Generate a unique ID for line segments

Description

Generate a unique ID for a line segment, based on the non-cryptographic murmur32 hash.

Usage

generateLineHash(x, precision = -1, algo = "murmur32")

Arguments

Details

The input sf object must NOT contain multi-part features. The precision specified should be tailored to the coordinate system in use and the snapping tolerance used to create join decision line segments. A precision of 4 is reasonable for geographic coordinates (snapping tolerance of 0.0001 degrees or ~ 10 meters). A precision of -1 (snapping tolerance of 10 meters) is reasonable for projected coordinate systems with units in meters.

Value

A vector of unique IDs created from the hash of line segment start and end vertex coordinates. Unique IDs are returned in the order of records of x and can therefore be saved into a new column of the associated attribute table. NA is returned for empty geometries.

Note

An error is issued if any non-unique IDs are generated. This could be caused by using coordinates that do not contain enough precision for unique hashing.

Author(s)

D.E. Beaudette

Examples

if(requireNamespace("sf")) {

# 10 random line segments
# shared end vertices
.x <- runif(n = 11, min = 0, max = 100)
.y <- runif(n = 11, min = 0, max = 100)
m <- matrix(c(.x, .y), ncol = 2, byrow = TRUE)

# init LINESTRING geometries
a <- lapply(1:(nrow(m) - 1), function(i) {
  .idx <- c(i, i+1)
  geom <- sf::st_sfc(sf::st_linestring(m[.idx, ]))
  a <- sf::st_sf(geom)
  
})

# flatten list -> 10 feature sf object
a <- do.call('rbind', a)

# line hashes
a$id <- generateLineHash(a, precision = 0)

# graphical check
plot(a, lwd = 2, key.width = lcm(4), axes = TRUE, las = 1)


# simulate empty geometry
a$geom[2] <- sf::st_sfc(sf::st_linestring())

# NA returned for empty geometry
generateLineHash(a, precision = 0)

}

Hue Position Chart

Description

A simple visualization of the hue positions for a given Munsell value/chroma according to Soil Survey Technical Note 2.

Usage

huePositionPlot(
  value = 6,
  chroma = 6,
  chip.cex = 4.5,
  label.cex = 0.75,
  contour.dE00 = FALSE,
  origin = NULL,
  origin.cex = 0.75,
  grid.res = 2,
  ...
)

Arguments

Value

nothing, function is called to generate graphical output

Examples

huePositionPlot(value = 4, chroma = 4)

huePositionPlot(value = 6, chroma = 6)

huePositionPlot(value = 8, chroma = 8)

huePositionPlot(value = 6, chroma = 6, contour.dE00 = TRUE, grid.res = 2)

# shift origin to arbitrary CIELAB coordinates or Munsell color
huePositionPlot(origin = cbind(40, 5, 15), origin.cex = 0.5)

huePositionPlot(origin = '5G 6/4', origin.cex = 0.5)

huePositionPlot(origin = '10YR 3/4', origin.cex = 0.5)

huePositionPlot(value = 3, chroma = 4, origin = '10YR 3/4', origin.cex = 0.5)

Hydrologic Ordering of a Geomorphic Proportion Matrix

Description

Hydrologic Ordering of a Geomorphic Proportion Matrix

Usage

hydOrder(x, g, clust = TRUE, j.amount = 0)

Arguments

Value

when clust = FALSE a vector of series names, in hydrologic ordering, otherwise a list with the following elements:

• clust: rotated hclust object

• hyd.order: vector of series names, in hydrologic ordering

• clust.hyd.order: vector of series names, after clustering + rotation, approximate hydrologic ordering

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

• obj: objective function value (sum of squared rank differences), used by iterateHydOrder()

Author(s)

D.E. Beaudette

Examples

# example data, similar to results from soilDB::fetchOSD(..., extended = TRUE)
data("OSDexamples")

# no clustering of the geomorphic proportion matrix
h <- hydOrder(OSDexamples$hillpos, g = 'hillpos', clust = FALSE)

# compare with original order

data.frame(
original = OSDexamples$hillpos$series,
ordered = h
)

# cluster results
h <- hydOrder(OSDexamples$hillpos, g = 'hillpos', clust = TRUE)
str(h)

Mineral Soil Material Criteria from 12th Ed. of KST

Description

Evaluate mineral soil material criteria based on soil organic carbon, clay content, and length of saturation.

Usage

isMineralSoilMaterial(soc, clay, saturation = TRUE)

Arguments

Value

data.frame of criteria test results

Iteratively Attempt Hydrologic Ordering of Geomorphic Proportion Matrix

Description

Iteratively Attempt Hydrologic Ordering of Geomorphic Proportion Matrix

Usage

iterateHydOrder(
  x,
  g,
  target = 0.9,
  maxIter = 20,
  j.amount = 0.05,
  verbose = FALSE,
  trace = FALSE
)

Arguments

Details

This function is used by the suite of geomorphic proportion visualization functions (⁠viz*⁠) to attempt rotation of a dendrogram according to "hydrologic ordering" rules. A perfect rotation is not always possible, and reported as a match rate in the returned score value

Value

A list with the following elements:

• clust: rotated hclust object

• hyd.order: vector of series names, in hydrologic ordering

• clust.hyd.order: vector of series names, after clustering + rotation, approximate hydrologic ordering

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

• obj: objective function value (sum of squared rank differences), used by iterateHydOrder()

• niter: number of iterations

• trace: list of results by iteration, only when trace = TRUE

Author(s)

D.E. Beaudette

Examples

# example data, similar to results from soilDB::fetchOSD(..., extended = TRUE)
data("OSDexamples")

# single iteration of hydrologic ordering
h1 <- hydOrder(OSDexamples$hillpos, g = 'hillpos', clust = TRUE)

# perform several iterations, keep the best one
h2 <- iterateHydOrder(OSDexamples$hillpos, 'hillpos', verbose = TRUE)

# compare: only slightly better match rate achieved
h1$match.rate
h2$match.rate

# return trace log for eval of objective function
# increase max iterations
h2 <- iterateHydOrder(OSDexamples$hillpos, 'hillpos', maxIter = 100, verbose = TRUE, trace = TRUE)

# inspect objective function evolution
tr <- h2$trace
obj <- sapply(tr, '[[', 'obj')

plot(obj, type = 'b')
hist(obj)

# in this case the clustering of hillpos proportions has only two possible configurations

Join Document Adjacency

Description

Convert a set of line segment "join decisions" into a weighted adjacency matrix describing which map unit symbols touch.

Usage

joinAdjacency(x, vars = c("l_musym", "r_musym"))

Arguments

Value

A weighted adjacency matrix is returned, suitable for plotting directly with plotSoilRelationGraph().

Author(s)

D.E. Beaudette

See Also

plotSoilRelationGraph()

Compute moisture state proportions

Description

Compute moisture state proportions

Usage

moistureStateProportions(x, id = "compname", step = c("month", "week", "doy"))

Arguments

Value

data.frame

Statistics on Soil Moisture State

Description

Statistics on Soil Moisture State

Usage

moistureStateStats(x, id = "compname")

Arguments

Value

data.frame containing the most-likely moisture state and Shannon entropy.

Apply a threshold to soil moisture states

Description

Apply a threshold to soil moisture states

Usage

moistureStateThreshold(
  x,
  id = "compname",
  threshold = "moist",
  operator = c("<", ">", "==", "<=", ">=")
)

Arguments

Value

data.frame

Author(s)

D.E. Beaudette

Monthly Water Balances

Description

Perform a monthly water balance by "leaky bucket" model, inspired by code from bucket.sim of hydromad package, as defined in Bai et al., (2009) (model "SMA_S1"). The plant available water-holding storage (soil thickness * awc) is used as the "bucket capacity". All water in excess of this capacity is lumped into a single "surplus" term.

Usage

monthlyWB(
  AWC,
  PPT,
  PET,
  S_init = 1,
  starting_month = 1,
  rep = 1,
  keep_last = FALSE,
  distribute = FALSE,
  method = c("equal", "random", "gaussian"),
  k = 10
)

Arguments

Details

See the monthly water balance tutorial for further examples and discussion.

A number of important assumptions are made by this style of water balance modeling:

• the concept of field capacity is built into the specified bucket size

• the influence of aquitards or local terrain cannot be integrated into this model

• interception is not used in this model

Value

a data.frame with the following elements:

• PPT: monthly PPT (mm)

• PET: monthly PET (mm)

• U: monthly surplus (mm)

• S: monthly soil moisture storage (mm)

• ET: monthly AET (mm)

• D: monthly deficit (mm)

• month: month number

• mo: month label

References

Arkley R, Ulrich R. 1962. The use of calculated actual and potential evapotranspiration for estimating potential plant growth. Hilgardia 32(10):443-469.

Bai, Y., T. Wagener, P. Reed (2009). A top-down framework for watershed model evaluation and selection under uncertainty. Environmental Modelling and Software 24(8), pp. 901-916.

Farmer, D., M. Sivapalan, Farmer, D. (2003). Climate, soil and vegetation controls upon the variability of water balance in temperate and semiarid landscapes: downward approach to water balance analysis. Water Resources Research 39(2), p 1035.

Water Balance Summaries

Description

A summary of a monthly water balance, including estimates of total and consecutive "dry", "moist", "wet" conditions, total surplus, deficit, and AET, and annual AET/PET ratio.

Usage

monthlyWB_summary(w, AWC = NULL, PWP = NULL, FC = NULL, SAT = NULL)

Arguments

Value

monthlyWB_summary(): a data.frame containing:

• cumulative (dry, moist, wet) days

• consecutive (dry_con, moist_con, wet_con) days

• total deficit (total_deficit) in mm

• total surplus (total_surplus) in mm

• total actual evapotranspiration (total_AET) in mm

• annual actual evapotranspiration to potential evapotranspiration ratio (annual_AET_PET_ratio)

Note

Work in progress: AWC, PWP, FC, and SAT arguments are currently ignored!

Convert Multinominal to Logical Matrix

Description

Convert a single multinominal, site-level attribute from a SoilProfileCollection into a matrix of corresponding logical values. The result contains IDs from the SoilProfileCollection and can easily be joined to the original site-level data.

Usage

multinominal2logical(x, v)

Arguments

Value

A data.frame with IDs in the first column, and as many columns of logical vectors as there were levels in v. See examples.

Author(s)

D.E. Beaudette

See Also

diagnosticPropertyPlot()

Examples

if(require(soilDB) &
   require(aqp) &
   require(latticeExtra)) {
  
  
  # sample data, an SPC
  data(loafercreek, package='soilDB')
  
  # convert to logical matrix
  hp <- multinominal2logical(loafercreek, 'hillslopeprof')
  
  # join-in to site data
  site(loafercreek) <- hp
  
  # variable names
  v <- c('lithic.contact', 'paralithic.contact', 
         'argillic.horizon', 'toeslope', 'footslope', 
         'backslope', 'shoulder', 'summit')
  
  # visualize with some other diagnostic features
  x <- diagnosticPropertyPlot(loafercreek, v, k = 5, 
                              grid.label = 'bedrckkind', dend.label = 'upedonid')  
}

Demonstration of Percentiles vs. Mean / SD

Description

This function can be used to graphically demonstrate the relationship between distribution shape, an idealized normal distribution (based on sample mean and sd) shape, and measures of central tendency / spread.

Usage

percentileDemo(x, labels.signif = 3, pctile.color = "RoyalBlue", 
mean.color = "Orange", range.color = "DarkRed", 
hist.breaks = 30, boxp = FALSE, ...)

Arguments

Value

A 1-row matrix of summary stats is invisibly returned.

Note

This function is mainly for educational purposes.

Author(s)

D.E. Beaudette

References

https://ncss-tech.github.io/soil-range-in-characteristics/why-percentiles.html

Examples

if (requireNamespace("Hmisc")) {
  x <- rnorm(100)
  percentileDemo(x)
  
  x <- rlnorm(100)
  percentileDemo(x)
}

Visual Demonstration of Available Soil Water

Description

Generate a simplistic diagram of the various fractions of water held within soil pore-space. Largely inspired by Figure 2 from O'Geen (2013).

Usage

plotAvailWater(
  x,
  width = 0.25,
  cols = c(grey(0.5), "DarkGreen", "LightBlue", "RoyalBlue"),
  name.cex = 0.8,
  annotate = TRUE
)

Arguments

Value

nothing, function is called to generate graphical output

Author(s)

D.E. Beaudette

References

O'Geen, A. T. (2013) Soil Water Dynamics. Nature Education Knowledge 4(5):9.

Examples

# demonstration
s <- data.frame(
  name = c('loamy sand', 'sandy loam', 'silt loam', 'clay loam'), 
  pwp = c(0.05, 0.1, 0.18, 0.2), 
  fc = c(0.1, 0.2, 0.38, 0.35), 
  sat = c(0.25, 0.3, 0.45, 0.4))
s$solid <- with(s, 1-sat)

par(mar=c(5, 6, 0.5, 0.5))
plotAvailWater(s, name.cex=1.25)



  
  if(requireNamespace("aqp")) {
    
    # demonstration using idealized AWC by soil texture
    data("ROSETTA.centroids", package = "aqp")
    
    # subset columns
    x <- ROSETTA.centroids[, c('texture', 'pwp', 'fc', 'sat', 'awc')]
    
    # adjust to expected names / additional data required by plotAvailWater
    names(x)[1] <- 'name'
    x$solid <- with(x, 1 - sat)
    
    # re-order based on approximate AWC
    x <- x[order(x$awc), ]
    
    op <- par(no.readonly = TRUE)
    
    par(mar=c(5, 6.5, 0.5, 0.5))
    plotAvailWater(x, name.cex = 1)
    
    par(op)
    
  }
  
  
  # use some real data from SSURGO
  if(requireNamespace("curl") &&
     requireNamespace("httr") &&
     curl::has_internet() &&
     require("soilDB")) {
    
    q <- "SELECT hzdept_r as hztop, hzdepb_r as hzbottom, 
hzname as name, wsatiated_r/100.0 as sat, 
wthirdbar_r/100.0 as fc, wfifteenbar_r/100.0 as pwp, awc_r as awc
FROM chorizon 
WHERE cokey IN (SELECT cokey from component where compname = 'dunstone') 
AND wsatiated_r IS NOT NULL 
ORDER BY cokey, hzdept_r ASC;"
    
    x <- SDA_query(q)
    x <- unique(x)
    x <- x[order(x$name), ]
    x$solid <- with(x, 1-sat)
    
    op <- par(no.readonly = TRUE)
    
    par(mar=c(5, 5, 0.5, 0.5))
    plotAvailWater(x)
    
    par(op)
  }
  

Graphical Demonstration of Declining Availability Functions

Description

This function is provides a standardized approach for the visualization of "declining availability functions" (DAF) used by various water-balance simulations. The DAF is an approximation of physical constraints on plant water extraction efficiency, as a function of declining soil moisture.

Usage

plotDAF(s = c("B", "C", "D", "G"), res = 0.01, ...)

DAF.C(x, intercept = 0)

DAF.G(x, threshold = 0.75)

DAF.B(x)

DAF.D(x)

Arguments

Value

nothing, function called for graphical output

AET/PET ratio in (0, 1)

AET/PET ratio in (0, 1)

AET/PET ratio in (0, 1)

AET/PET ratio in (0, 1)

Examples

# multi-figure output
op <- par(no.readonly = TRUE)
par(mfrow = c(2, 2))

# defaults
plotDAF('C')
plotDAF('G')
plotDAF('B')
plotDAF('D')


# adjust intercept term for DAF 'C'
plotDAF('C', intercept = 0.1)
title(sub = 'intercept = 0.1', font.sub = 3)
plotDAF('C', intercept = 0.3)
title(sub = 'intercept = 0.3', font.sub = 3)

# adjust threshold term for DAF 'G'
plotDAF('G', threshold = 0.5)
title(sub = 'threshold = 0.5', font.sub = 3)
plotDAF('G', threshold = 0.9)
title(sub = 'threshold = 0.9', font.sub = 3)


# reset output device options
par(op) 

Present a SoilProfileCollection aligned to a geomorphic summary as cross-section.

Description

Present a SoilProfileCollection aligned to a geomorphic summary as cross-section.

Usage

plotGeomorphCrossSection(
  x,
  type = c("line", "bar"),
  g = "hillpos",
  clust = TRUE,
  col = c("#377EB8", "#4DAF4A", "#984EA3", "#FF7F00", "#E41A1C"),
  ...
)

Arguments

Details

Additional arguments to aqp::plotSPC() can be provided using options(.aqp.plotSPC.args = list(...)). For example, adjustments to maximum depth and profile width can be set via: ⁠options(.aqp.plotSPC.args = list(max.depth = 150, width = 0.35)⁠. Default arguments can be reset with ⁠options(.aqp.plotSPC.args = NULL⁠).

When clust = TRUE, especially for SoilProfileCollections with a wide range in depth, it may be necessary to adjust the scaling.factor argument to aqp::plotSPC() via: options(.aqp.plotSPC.args = list(scaling.factor = 0.01)). Larger values will increase the height of profile sketches.

Value

nothing, function is called to generate graphical output

Author(s)

D.E. Beaudette

Visualize Soil Relationships via Chord Diagram

Description

Visualize Soil Relationships via Chord Diagram

Usage

plotSoilRelationChordGraph(
  m,
  s,
  mult = 2,
  base.color = "grey",
  highlight.colors = c("RoyalBlue", "DarkOrange", "DarkGreen"),
  add.legend = TRUE,
  ...
)

Arguments

Details

This function is experimental. Documentation pending. See http://jokergoo.github.io/circlize/ for ideas.

Value

nothing, function is called to generate graphical output

Author(s)

D.E. Beaudette

Plot a component relation graph

Description

Plot a component relation graph based on an adjacency or similarity matrix.

Usage

plotSoilRelationGraph(
  m,
  s = "",
  plot.style = c("network", "dendrogram", "none"),
  graph.mode = "upper",
  spanning.tree = NULL,
  del.edges = NULL,
  vertex.scaling.method = "degree",
  vertex.scaling.factor = 2,
  edge.scaling.factor = 1,
  vertex.alpha = 0.65,
  edge.transparency = 1,
  edge.col = grey(0.5),
  edge.highlight.col = "royalblue",
  g.layout = igraph::layout_with_fr,
  vertex.label.color = "black",
  delete.singletons = FALSE,
  ...
)

Arguments

Details

Vertex size is based on a normalized index of connectivity:

• "degree" size = sqrt(igraph::degree(g) / max(igraph::degree(g))) * scaling.factor

• "distance" size = sqrt(igraph::distance(V -> s) / max(igraph::distance(V -> s))) * scaling.factor, where distance(V->s) is the distance from all nodes to the named series, s.

Edge width can be optionally scaled by edge weight by specifying an edge.scaling.factor value. The maximum spanning tree represents a sub-graph where the sum of edge weights are maximized. The minimum spanning tree represents a sub-graph where the sum of edge weights are minimized. The maximum spanning tree is likely a more useful simplification of the full graph, in which only the strongest relationships (e.g. most common co-occurrences) are preserved.

The maximum spanning tree + edges with weights > n-th quantile is an experimental hybrid. The 'backbone' of the graph is created by the maximum spanning tree, and augmented by 'strong' auxiliary edges–defined by a value between 0 and 1.

The graph.mode argument is passed to igraph::graph_from_adjacency_matrix() and determines how vertex relationships are coded in the adjacency matrix m. Typically, the default value of 'upper' (the upper triangle of m contains adjacency information) is the desired mode. If m contains directional information, set graph.mode to 'directed'. This has the side-effect of altering the default community detection algorithm from igraph::cluster_fast_greedy to igraph::cluster_walktrap.

Value

an igraph graph object is invisibly returned

Note

The default output for plot.style=network is nondeterministic when using most igraph layouts, including the default igraph::layour_with_fr. Previous versions of sharpshootR hard-coded a random seed via set.seed(1010101). Consider adding this if you are trying to recreate previous output.

Author(s)

D.E. Beaudette

Examples

# consider setting a random seed for consistent output from run to run
# prior releases of sharpshootR used:
# set.seed(1010101)

if (requireNamespace("igraph") && requireNamespace("vegan")) {
  # load sample data set
  data(amador)

  # create weighted adjacency matrix (see ?component.adj.matrix for details)
  m <- component.adj.matrix(amador)

  # plot network diagram, with Amador soil highlighted
  plotSoilRelationGraph(m, s='amador')

  # dendrogram representation
  plotSoilRelationGraph(m, s='amador', plot.style='dendrogram')

  # compare methods
  m.o <- component.adj.matrix(amador, method='occurrence')

  op <- par(no.readonly = TRUE)

  par(mfcol=c(1,2))
  plotSoilRelationGraph(m, s='amador', plot.style='dendrogram')
  title('community matrix')
  plotSoilRelationGraph(m.o, s='amador', plot.style='dendrogram')
  title('occurence')

  # investigate max spanning tree
  plotSoilRelationGraph(m, spanning.tree='max')

  # investigate max spanning tree + edges with weights > 75-th pctile
  plotSoilRelationGraph(m, spanning.tree=0.75)

  par(op)

  
  
    if(requireNamespace("curl") &
       curl::has_internet() &
       require(soilDB)) {
    
      # get similar data from soilweb, for the Pardee series
      s <- 'pardee'
      d <- siblings(s, component.data = TRUE)
    
      # normalize component names
      d$sib.data$compname <- tolower(d$sib.data$compname)
    
      # keep only major components
      d$sib.data <- subset(d$sib.data, subset=compkind == 'Series')
    
      # build adj. matrix and plot
      m <- component.adj.matrix(d$sib.data)
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram')
    
      # alter plotting style, see ?plot.phylo
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram', type='fan')
      plotSoilRelationGraph(m, s=s, plot.style='dendrogram', 
                            type='unrooted', use.edge.length=FALSE) 
    
    }
  
}

Arrange Profiles along a Transect

Description

Plot a collection of Soil Profiles linked to their position along some gradient (e.g. transect).

Usage

plotTransect(
  s,
  xy,
  grad.var.name,
  grad.var.order = order(site(s)[[grad.var.name]]),
  transect.col = "RoyalBlue",
  tick.number = 7,
  y.offset = 100,
  scaling.factor = 0.5,
  distance.axis.title = "Distance Along Transect (km)",
  grad.axis.title = NULL,
  dist.scaling.factor = 1000,
  spacing = c("regular", "relative"),
  fix.relative.pos = list(thresh = 0.6, maxIter = 5000),
  ...
)

Arguments

Details

Depending on the nature of your SoilProfileCollection and associated gradient values, it may be necessary to tinker with figure margins, y.offset and scaling.factor.

Value

An invisibly-returned data.frame object:

• scaled.grad: scaled gradient values

• scaled.distance: cumulative distance, scaled to the interval of ⁠0.5, nrow(coords) + 0.5⁠

• distance: cumulative distance computed along gradient, e.g. transect distance

• variable: sorted gradient values

• x: x coordinates, ordered by gradient values

• y: y coordinate, ordered by gradient values

• grad.order: a vector index describing the sort order defined by gradient values

Note

This function is very much a work in progress, ideas welcome!

Author(s)

D.E. Beaudette

Examples

if(require(aqp) & 
require(sf) &
  require(soilDB)
) {
   
library(aqp)
library(soilDB)
library(sf)


# sample data
data("mineralKing", package = "soilDB")

# device options are modified locally, reset when done
op <- par(no.readonly = TRUE)

# quick overview
par(mar=c(1,1,2,1))
groupedProfilePlot(mineralKing, groups='taxonname', print.id=FALSE)

# setup point locations
s <- site(mineralKing)
xy <- st_as_sf(s, coords = c('longstddecimaldegrees', 'latstddecimaldegrees'))
st_crs(xy) <- 4326

# convert to suitable projected cRS
# projected CRS, UTM z11 NAD83 (https://epsg.io/26911)
xy <- st_transform(xy, 26911) 

# adjust margins
par(mar = c(4.5, 4, 4, 1))

# standard transect plot, profile sketches arranged along integer sequence
plotTransect(mineralKing, xy, grad.var.name = 'elev_field',
             grad.axis.title = 'Elevation (m)', label = 'upedonid', name = 'hzname')

# default behavior, attempt adjustments to prevent over-plot and preserve relative spacing
# use set.seed() to fix outcome
plotTransect(mineralKing, xy, grad.var.name = 'elev_field',
             grad.axis.title = 'Elevation (m)', label = 'upedonid',
             name = 'hzname', width = 0.15, spacing = 'relative')

# attempt relative positioning based on scaled distances, no corrections for overlap
# profiles are clustered in space and therefore over-plot
plotTransect(mineralKing, xy, grad.var.name = 'elev_field',
             grad.axis.title = 'Elevation (m)', label = 'upedonid', name = 'hzname',
             width = 0.15, spacing = 'relative', fix.relative.pos = FALSE)

# customize arguments to aqp::fixOverlap()
plotTransect(mineralKing, xy, grad.var.name = 'elev_field', crs = crs.utm,
             grad.axis.title = 'Elevation (m)', label = 'upedonid', name = 'hzname',
             width = 0.15, spacing = 'relative',
             fix.relative.pos = list(maxIter=6000, adj=0.2, thresh=0.7))

plotTransect(mineralKing, xy, grad.var.name = 'elev_field', crs = crs.utm,
             grad.axis.title = 'Elevation (m)', label = 'upedonid', name = 'hzname',
             width = 0.2, spacing = 'relative',
             fix.relative.pos = list(maxIter = 6000, adj = 0.2, thresh = 0.6),
             name.style = 'center-center')

par(op)
  
}

Visualize Monthly Water Balance

Description

This function offers one possible visualization for the results of monthlyWB(). Note that "surplus" water is stacked on top of "actual ET", and "deficit" water is stacked below "storage". Calculate actual values for "surplus" and "deficit" from the figure like this:

• surplus value = surplus - AET

• deficit value = deficit - storage

Usage

plotWB(
  WB,
  AWC = attr(WB, "AWC"),
  sw.col = "#377EB8",
  surplus.col = "#4DAF4A",
  et.col = "#E41A1C",
  deficit.col = "#FF7F00",
  pch = c(21, 21),
  pt.cex = 1,
  pt.col = par("bg"),
  pt.bg = par("fg"),
  lty = c(1, 2),
  lwd = 2,
  n.ticks = 8,
  grid.col = grey(0.65),
  month.cex = 1,
  legend.cex = 0.9,
  ylim
)

Arguments

Value

nothing, function is called to generate graphical output

Note

You may have to adjust figure margins and size to get all of the elements to "look right".

Author(s)

D.E. Beaudette and J.M. Skovlin

Examples

if(requireNamespace('hydromad')) {

## A shallow / droughty soil near Sonora CA 
# 100mm (4") AWC
AWC <- 100
PPT <- c(171, 151, 138, 71, 36, 7, 1, 2, 11, 48, 102, 145)
PET <- c(15.17, 18.26, 30.57, 42.95, 75.37, 108.05, 139.74, 128.9, 93.99, 59.84, 26.95, 14.2)

# water-year
# three years
x.wb <- monthlyWB(AWC, PPT, PET, S_init = 0, starting_month = 9, rep = 3)
x.wb[x.wb$mo == 'Sep', ]

# plot all three years
plotWB(x.wb)

# water-year / last iteration
x.wb <- monthlyWB(AWC, PPT, PET, S_init = 0, 
                  starting_month = 9, rep = 3, 
                  keep_last = TRUE
)

# plot
plotWB(x.wb)


## Drummer series (Fine-silty, mixed, superactive, mesic Typic Endoaquolls), southern IL

AWC <- 244
PPT <- c(36, 37, 54, 82, 98, 96, 92, 75, 69, 70, 65, 50)
PET <- c(0, 0, 12, 46, 90, 130, 145, 128, 88, 46, 14, 0)

# using calendar year
x.wb <- monthlyWB(AWC, PPT, PET, S_init = 0,
                  starting_month = 1, rep = 3,
                  keep_last = TRUE
)

plotWB(x.wb)

}

Visualization of a monthly water balance using lines and areas

Description

This function creates a graphical summary of a monthly water balance, typically estimated via monthlyWB().

Usage

plotWB_lines(
  WB,
  cols = c("#759CC9", "#EB6D6E", "#7FC47D"),
  line.col = "black",
  line.lty = c(1, 2, 3),
  interpolator = c("spline", "linear"),
  spline.method = c("natural", "periodic"),
  month.cex = 1,
  legend.cex = 0.9
)

Arguments

Value

nothing, function is called to generate graphical output

Author(s)

J.M. Skovlin and D.E. Beaudette

Examples

if(requireNamespace('hydromad')) {

## A shallow / droughty soil near Sonora CA 
# 100mm (4") AWC
AWC <- 100
PPT <- c(171, 151, 138, 71, 36, 7, 1, 2, 11, 48, 102, 145)
PET <- c(15.17, 18.26, 30.57, 42.95, 75.37, 108.05, 139.74, 128.9, 93.99, 59.84, 26.95, 14.2)

# calendar-year
# three year warm-up
x.wb <- monthlyWB(AWC, PPT, PET, S_init = 0, starting_month = 1, rep = 3, keep_last = TRUE)
 
# plot
plotWB_lines(x.wb)

}

Summarize Spatial Adjacency of Polygon Fabric

Description

This function utilizes the spdep and igraph packages to evaluate several measures of spatial connectivity.

Usage

polygonAdjacency(x, v = "MUSYM", ...)

Arguments

Details

Examples are presented in this tutorial.

Value

a list containing:

• commonLines: an integer vector of feature IDs, describing polygons sharing edges and values of v (map unit labels)

• adjMat: weighted adjacency matrix, suitable for visualization with plotSoilRelationGraph()

Author(s)

D.E. Beaudette

Prepare daily climate data (DAYMET) for a single point

Description

This function returns daily climate data required for a simple water balance (and more), using three packages:

• elevatr: elevation data at x

• daymetr: DAYMET data at x for years start through end

• Evapotranspiration: Makkink formulation for estimating reference crop evapotranspiration

Usage

prepareDailyClimateData(x, start, end, onlyWB = TRUE)

Arguments

Value

a data.frame

Get and prepare basic soil hydraulic parameters from SSURGO via SDA

Description

Get and prepare basic soil hydraulic parameters from SSURGO via SDA

Usage

prepare_SSURGO_hydro_data(cokeys, max.depth)

Arguments

Details

Weighted mean soil hydraulic parameters are returned over the interval of 0-max.depth, calculated by aqp::slab().

Value

a list containing:

• SPC: SoilProfileCollection

• agg: aggregate representation of hydraulic parameters, by cokey

The following soil hydraulic properties are included:

Author(s)

D.E. Beaudette

Reconcile IDs between a SPC and associated geomorphic proportion table

Description

This function can assist with linked visualizations that include soil morphology data stored in a SoilProfileCollection and geomorphic proportions stored in a data.frame, as returned by soilDB::fetchOSD().

Usage

reconcileOSDGeomorph(
  x,
  selection = c("hillpos", "geomcomp", "flats", "mtnpos", "terrace", "shape_across",
    "shape_down")
)

Arguments

Value

a list with subset SoilProfileCollection and data.frame of geomorphic proportions, selection is preserved as an attribute.

Author(s)

D.E. Beaudette

Sample a Single Polygon at a Target Density

Description

Sample a single SpatVector polygon at a target density in "samples / acre".

Usage

sample.by.poly(
  p,
  n.pts.per.ac = 1,
  min.samples = 5,
  sampling.type = "regular",
  p4s = NULL
)

Arguments

Value

SpatVector of sample points

Author(s)

D.E. Beaudette

Sample a Raster Stack

Description

Sample a raster stack by map unit polygons, at a constant density.

Usage

sampleRasterStackByMU(
  mu,
  mu.set,
  mu.col,
  raster.list,
  pts.per.acre,
  p = c(0, 0.05, 0.25, 0.5, 0.75, 0.95, 1),
  progress = TRUE,
  estimateEffectiveSampleSize = TRUE,
  polygon.id = "pID"
)

Arguments

Details

This function is used by various NRCS reports that summarize or compare concepts defined by collections of polygons using raster data sampled from within each polygon, at a constant sampling density. Even though the function name includes "RasterStack", this function doesn't actually operate on the "stack" object as defined in the raster package. The collection of raster data defined in raster.list do not have to share a common coordinate reference system, grid spacing, or extent. Point samples generated from mu are automatically converted to the CRS of each raster before extracting values. The extent of each raster in raster.list must completely contain the extent of mu.

Value

A list containing:

raster.samples

a data.frame containing samples from all rasters in the stack

area.stats

a data.frame containing area statistics for all map units in the collection

unsampled.ids

an index to rows in the original SPDF associated with polygons not sampled

raster.summary

a data.frame containing information on sampled rasters

Moran_I

a data.frame containing estimates Moran's I (index of spatial autocorrelation)

Author(s)

D.E. Beaudette

See Also

constantDensitySampling(), sample.by.poly()

Estimate Sampling Stability

Description

Stability is defined as the width of the 5th-95th percentile range, over n.reps replications of median estimates associated with sampling events. The resulting width is scaled by the population median and returned as a fraction.

Usage

samplingStability(
  mu,
  r,
  n.set = c(0.01, 0.1, 0.5, 1, 2),
  n.reps = 10,
  p.id = "pID"
)

Arguments

Value

data.frame with median stability values as percentage of population median, range: ⁠[0,1]⁠

Author(s)

D.E. Beaudette

Simple interface to the hydromad "leaky bucket" soil moisture model

Description

Simple interface to the hydromad "leaky bucket" soil moisture model.

Usage

simpleWB(
  PPT,
  PET,
  D,
  thickness,
  sat,
  fc,
  pwp,
  S_0 = 0.5,
  a.ss = 0.05,
  M = 0,
  etmult = 1
)

Arguments

Details

Adjustments for coarse fragments should be made by reducing thickness.

Value

a data.frame

References

Farmer, D., M. Sivapalan, Farmer, D. (2003). Climate, soil and vegetation controls upon the variability of water balance in temperate and semiarid landscapes: downward approach to water balance analysis. Water Resources Research 39(2), p 1035.

Bai, Y., T. Wagener, P. Reed (2009). A top-down framework for watershed model evaluation and selection under uncertainty. Environmental Modelling and Software 24(8), pp. 901-916.

site_photos_kml

Description

Generates a KML file of site locations with associated site photos and a link to a pedon description report.

Usage

site_photos_kml(data, 
filename='photos.kml', make.image.grid=FALSE, 
file.source = c('local', 'relative')
)

Arguments

Details

This function simplifies writing a kml file of site and/or sites with linked photos. Further documentation is provided in this tutorial.

Value

A KML file of of sites with embedded associated site photos.

Author(s)

Jay Skovlin, D.E. Beaudette

Table 5.2 from Hole and Campbell, 1985.

Description

An adjacency matrix describing shared soil map boundary segments from the Soil Survey of Shawnee county, KS. This is table 5.2 from Hole and Campbell, 1985.

Usage

data(table5.2)

Format

An object of class matrix (inherits from array) with 18 rows and 18 columns.

References

Hole, F.D. and J.B. Campbell. Soil Landscape Analysis. Rowman and Allanheld, 1985.

Examples

data("table5.2")

if(requireNamespace("igraph")) {
  
  # note special incantation to get the "correct" graph structure
  g <- igraph::graph_from_adjacency_matrix(table5.2, mode = 'upper', diag = FALSE, weighted = TRUE)
  
  # visualize
  op <- par(no.readonly = TRUE)
  
  par(mar = c(0,0,0,0))
  plot(g)
  
  plot(g, vertex.size = sqrt(igraph::degree(g) * 25), vertex.label.family = 'sans')
  
  # find communities
  cm <- igraph::cluster_walktrap(g)
  plot(cm, g, vertex.label.family = 'sans')
  
  par(op)
}

Annual Climate Summaries for Soil Series Data

Description

Annual climate summaries for soil series, based on latticeExtra::segplot, based on 5th, 25th, 50th, 75th, and 95th percentiles. Input data should be from soilDB::fetchOSD.

Usage

vizAnnualClimate(climate.data, IQR.cex = 1, s = NULL, s.col = "firebrick", ...)

Arguments

Details

This function was designed for use with soilDB::fetchOSD. It might be possible to use with other sources of data but your mileage may vary. See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• clust: clustering object returned by cluster::diana

Author(s)

D.E. Beaudette

See Also

vizHillslopePosition()

Visual Summary of Flat Landform Positions

Description

A unique display of landform position probability.

Usage

vizFlatsPosition(
  x,
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#2B83BA", "#ABDDA4", "#FFFFBF", "#FDAE61", "#D7191C"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette

Visual Summary of Hill Landform Positions

Description

A unique display of landform position probability.

Usage

vizGeomorphicComponent(
  x,
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#D53E4F", "#FC8D59", "#FEE08B", "#E6F598", "#99D594", "#3288BD"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette

Visual Summary of Hillslope Position

Description

A unique display of hillslope position probability.

Usage

vizHillslopePosition(
  x,
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#2B83BA", "#ABDDA4", "#FFFFBF", "#FDAE61", "#D7191C"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette

Visual Summary of Mountain Slope Positions

Description

A unique display of mountain slope position probability.

Usage

vizMountainPosition(
  x,
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#D53E4F", "#FC8D59", "#FEE08B", "#E6F598", "#99D594", "#3288BD"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette

Visual Summary of Surface Shape

Description

A unique display of surface shape (typically curvature) probability, suitable for across-slope or down-slope shape. Use the title argument to make this clear.

Usage

vizSurfaceShape(
  x,
  title = "Surface Shape",
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#2B83BA", "#FFFFBF", "#D7191C", "#808080", "darkgreen"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette

Visual Summary of Terraced Landform Positions

Description

A unique display of terraced landform position probability.

Usage

vizTerracePosition(
  x,
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  cols = c("#2B83BA", "#FDAE61"),
  ...
)

Arguments

Details

See the Soil Series Query Functions tutorial for more information.

Value

A list with the following elements:

• fig: lattice object (the figure)

• order: 1D ordering from cluster::diana

• clust: hclust object

• match.rate: fraction of series matching target hydrologic ordering, after clustering + rotation

Author(s)

D.E. Beaudette