% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/colorVariation.R
\name{colorVariation}
\alias{colorVariation}
\title{Quantitative Description of Color Variation}
\usage{
colorVariation(
  m,
  method = c("frequency", "centroid", "L1", "reference"),
  ref = NULL
)
}
\arguments{
\item{m}{character vector of colors, described using the Munsell system e.g. \code{c('10YR 3/3', '5YR 4/6')}}

\item{method}{character, one of \code{c('frequency', 'centroid', 'reference')}, see Details}

\item{ref}{character, a reference color specified in the Munsell system when \code{method = 'reference'}}
}
\value{
numeric, dE00 summary of color variation along with group centroid for \code{method = c('frequency', 'centroid', 'L1')}
}
\description{
This function computes several measures of "color variation", typically associated with soil colors described in the Munsell system, using the CIE2000 dE (dE00) color contrast metric. The resulting dE00 summaries map closely to color differences as perceived by "average human vision".
}
\details{
dE00 values are computed according to \code{method}:
\itemize{
\item 'frequency': relative to most frequent color in \code{m}
\item 'centroid': relative to centroid (CIELAB coordinates) of colors specified in \code{m}
\item 'L1': relative to L1-median (geometric median) CIELAB coordinates of colors specified in \code{m}, via \code{Gmedian::Gmedian()}
\item 'reference': relative to color specified in \code{ref}
}

The \code{L1} method is more robust to outliers in \code{m} as compared to other methods.
}
\examples{

# some brownish colors with a wild outlier
m <- c('10YR 3/3', '10YR 4/4', '10YR 4/4', '5GY 6/8')

# useful when there may be a lot of duplicates
# error when there is not a single, most-frequent color
colorVariation(m, method = 'frequency')

# statistical "centroid" of colors, not robust to outliers
# result may not match any color in `m`
colorVariation(m, method = 'centroid')

# deviation from a known reference
colorVariation(m, method = 'reference', ref = '10YR 2/1')

# L1-median (requires Gmedian package) like 'centroid'
# more robust to outliers
# result will usually be very close to a color in `m`
if(requireNamespace('Gmedian')) {
  colorVariation(m, method = 'L1')
}


# compare methods using a range of colors on a 
# single hue page
x <- expand.grid(
  hue = '10YR', 
  value = 2:7, 
  chroma = 2:7
)

x$m <- sprintf("\%s \%s/\%s", x$hue, x$value, x$chroma)

colorChart(x$m)

(v <- colorVariation(x$m, method = 'centroid'))
contrastChart(attr(v, 'centroid'), hues = x$hue[1], thresh = v)

if(requireNamespace('Gmedian')) {
  (v <- colorVariation(x$m, method = 'L1'))
  contrastChart(attr(v, 'L1'), hues = x$hue[1], thresh = v)
}


# attempt to simulate colors from a group centroid
\dontrun{
v <- colorVariation(x$m, method = 'centroid')

s <- simulateColor(
method = 'dE00', 
n = 200, 
parameters = list(m = attr(v, 'centroid'), thresh = v * 1.96, hues = x$hue[1])
)
colorChart(s[[1]])
}


}
