% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vizSurfaceShape.R
\name{vizSurfaceShape}
\alias{vizSurfaceShape}
\title{Visual Summary of Surface Shape}
\usage{
vizSurfaceShape(
  x,
  title = "Surface Shape",
  s = NULL,
  annotations = TRUE,
  annotation.cex = 0.75,
  clust = TRUE,
  dend.size = 5,
  dend.type = c("rectangle", "triangle"),
  cols = c("#3D8399", "#E9D772", "#CF4F3F", "#808080", "#226222"),
  ...
)
}
\arguments{
\item{x}{\code{data.frame} as created by \code{soilDB::fetchOSD(..., extended = TRUE)}, see details}

\item{title}{a reasonable title for the figure}

\item{s}{an optional soil series name, highlighted in the figure}

\item{annotations}{logical, add number of record and normalized Shannon entropy values}

\item{annotation.cex}{annotation label scaling factor}

\item{clust}{logical, order rows using divisive hierarchical clustering and include dendrogram?}

\item{dend.size}{numeric, space reserved for dendrogram when \code{clust = TRUE}: values between 3-10 are about right}

\item{dend.type}{character, one of 'rectangle' or 'triangle', when \code{clust = TRUE}}

\item{cols}{vector of colors}

\item{\dots}{additional arguments to \code{\link[=iterateHydOrder]{iterateHydOrder()}}: \verb{target = 0.9, maxIter = 20, j.amount = 0.001, verbose = FALSE}}
}
\value{
A \code{list} with the following elements:
\itemize{
\item \code{fig}: lattice object (the figure)
\item \code{order}: 1D ordering from \code{cluster::diana}
\item \code{clust}: \code{hclust} object
\item \code{match.rate}: fraction of series matching target hydrologic ordering, after clustering + rotation
}
}
\description{
This function creates a graphical summary of surface shape (also described as surface curvature, across or down-slope), as returned by \code{soilDB::fetchOSD(..., extended = TRUE)}. Stacked barplots are arranged according to an expected hydrologic gradient from "higher" to "lower" relative positions in a theoretical landscape.
}
\details{
See the \href{http://ncss-tech.github.io/AQP/soilDB/soil-series-query-functions.html}{Soil Series Query Functions} tutorial for more information. In the presence of ties within \code{x}, a small amount of jittering is applied to proportions to assist with the hydrologic ordering step (only when \code{clust = TRUE}).
}
\note{
Default colors are from \code{PNWColors::pnw_palette('Bay')}. Original colors: \code{c("#2B83BA", "#FFFFBF", "#D7191C", "#808080", "darkgreen")}.
}
\author{
D.E. Beaudette
}
