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

\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 geomorphic position proportions, 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.

Example geomorphic position data:\tabular{lrrrr}{
   series \tab Tread \tab Riser \tab n \tab shannon_entropy \cr
   CAPSHAW \tab 0.974 \tab 0.026 \tab 39 \tab 0.172 \cr
   GUTHRIE \tab 1.000 \tab 0.000 \tab 86 \tab 0.000 \cr
   LEE \tab 1.000 \tab 0.000 \tab 42 \tab 0.000 \cr
   LOBELVILLE \tab 1.000 \tab 0.000 \tab 26 \tab 0.000 \cr
   TAFT \tab 1.000 \tab 0.000 \tab 90 \tab 0.000 \cr
   TARKLIN \tab 0.660 \tab 0.340 \tab 53 \tab 0.924 \cr
   TRACE \tab 1.000 \tab 0.000 \tab 12 \tab 0.000 \cr
}
}
\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('Shuksan2')}. Original colors: \code{c("#2B83BA", "#FDAE61")}
}
\author{
D.E. Beaudette
}
