CRAN release

NEWS.md

@@ -1,4 +1,4 @@
-# aqp 2.0 (2023-08-07)
+# aqp 2.0 (2023-08-28)
 This is a major update to aqp that may create some issues for code depending on specific inputs/outputs in aqp < 1.42, particularly those relying on `slice()`, `slab()`, and `profile_compare()`. `slice()` and `profile_compare()` are now deprecated, but will continue to work for the rest of calendar year 2023. There are no plans to maintain these functions beyond aqp 2.0. The new version of `slab()` is a drop-in replacement for the previous version of the function.
 
 Notable changes include:

R/colorContrast.R

@@ -1,6 +1,3 @@
-# compute metrics of color contrast: delta-Hue, Value, Chroma and delta-E00
-# m1: vector of Munsell colors ('10YR 3/3')
-# m2: vector of Munsell colors ('10YR 3/4')
 
 #' @title Metrics of Contrast Suitable for Comparing Soil Colors
 #'
@@ -14,25 +11,20 @@
 #' 
 #' The most meaningful representation of color contrast is the CIE2000 (dE00) metric.
 #'
-#' @return
-#' A `data.frame` with the following columns:
+#' @return `data.frame` with the following columns:
 #'
-#' \itemize{
-#' \item{m1: }{Munsell color 1}
-#' \item{m2: }{Munsell color 2}
-#' \item{dH: }{delta-hue, as computed by \code{huePosition}}
-#' \item{dV: }{delta-value, absolute value of difference in Munsell value (m1 vs. m2)}
-#' \item{dc: }{delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2)}
-#' \item{dE00: }{delta-E00, e.g. the [CIE delta-E as refined in 2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000)}
-#' \item{cc: }{soil color contrast class, as specified in Soil Survey Technical Note 2 [wayback machine URL](https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569)}
-#' }
+#'   * m1: Munsell color 1
+#'   * m2: Munsell color 2
+#'   * dH: delta-hue, as computed by `huePosition`
+#'   * dV: delta-value, absolute value of difference in Munsell value (m1 vs. m2)
+#'   * dc: delta-chroma, absolute value of difference in Munsell chroma (m1 vs. m2)
+#'   * dE00: delta-E00, e.g. the [CIE delta-E as refined in 2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000)
+#'   * cc: soil color contrast class, as specified in Soil Survey Technical Note 2.
 #'
 #' @references
 #'
 #'  1. https://en.wikipedia.org/wiki/Color_difference
 #'
-#'  2. Soil Survey Technical Note 2 [wayback machine URL](https://web.archive.org/web/20220704214918/https://www.nrcs.usda.gov/wps/portal/nrcs/detail/soils/ref/?cid=nrcs142p2_053569)
-#'
 #' @author D.E. Beaudette
 #'
 #' @note delta-E00 is computed by the \href{https://CRAN.R-project.org/package=farver}{farver package}.

R/colorContrastPlot.R

@@ -1,22 +1,13 @@
 
-## quickly display two sets of colors and soil color contrast metrics
-# m1: munsell colors
-# m2: munsell colors
-# col.cex: scaling for color labels
-# col.font: font for color labels
-# d.cex: scaling for contrast metric labels
-# cc.font: font for contrast class
-# dE00.font: font for delta-E00 label
-# labels: vector of labels for colors being compared
-# printMetrics: add contrast metrics
-# \dots{}: further arguments passed to colorspace::swatchplot
-#' Color Contrast Plot
+
 #'
-#' A simple display of two sets of colors, NCSS color contrast class and CIE
-#' delta-E00.
+#' @title Color Contrast Plot
 #'
-#' This function requires the \code{farver} package for calculation of CIE
-#' delta-E00
+#' @description A simple display of two sets of colors, NCSS color contrast class and CIE
+#' delta-E00.
+#' 
+#' @note This function requires the `farver` package for calculation of CIE
+#' delta-E00.
 #'
 #' @param m1 first set of Munsell colors for comparison (e.g. '5YR 3/2')
 #' @param m2 second set of Munsell colors for comparison
@@ -29,9 +20,9 @@
 #' @param label.cex scaling factor for labels
 #' @param label.font font for labels
 #' @param printMetrics logical, print metrics between color swatches
-#' @param \dots further arguments to \code{colorspace::swatchplot}
+#' @param \dots further arguments to `colorspace::swatchplot`
 #' @author D.E. Beaudette
-#' @seealso \code{\link{colorContrast}}
+#' @seealso [colorContrast()]
 #' @keywords hplots
 #' @export
 #' @examples

R/mixMunsell.R

@@ -153,6 +153,8 @@
 #'
 #'
 #' @details
+#' See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for examples.
+#' 
 #' An accurate simulation of pigment mixtures ("subtractive" color mixtures) is incredibly complex due to factors that aren't easily measured or controlled: pigment solubility, pigment particle size distribution, water content, substrate composition, and physical obstruction to name a few. That said, it is possible to simulate reasonable, subtractive color mixtures given a reference spectra library (350-800nm) and some assumptions about pigment qualities and lighting. For the purposes of estimating a mixture of soil colors (these are pigments after all) we can relax these assumptions and assume a standard light source. The only missing piece is the spectral library for all Munsell chips in our color books.
 #' 
 #' Thankfully, [Scott Burns has outlined the entire process](https://arxiv.org/ftp/arxiv/papers/1710/1710.06364.pdf), and Paul Centore has provided a Munsell color chip [reflectance spectra library](https://www.munsellcolourscienceforpainters.com). The estimation of a subtractive mixture of soil colors can proceed as follows:
@@ -190,26 +192,6 @@
 #'
 #' @seealso [munsell.spectra]
 #' @export
-#' @examples 
-#' 
-#' # keep examples from using more than 2 cores
-#' data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2)) 
-#' 
-#' # try a couple different methods
-#' cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4')
-#' if(requireNamespace("gower")) {
-#' mixMunsell(cols, mixingMethod = 'reference')
-#' }
-#' mixMunsell(cols, mixingMethod = 'exact')
-#' mixMunsell(cols, mixingMethod = 'estimate')
-#' 
-#' # 2.5 values
-#' cols <- c('10YR 2.5/2', '5YR 5/6')
-#' if(requireNamespace("gower")) {
-#' mixMunsell(cols, mixingMethod = 'reference')
-#' }
-#' mixMunsell(cols, mixingMethod = 'exact')
-#' mixMunsell(cols, mixingMethod = 'estimate')
 #' 
 mixMunsell <- function(x, w = rep(1, times = length(x)) / length(x), mixingMethod = c('exact', 'reference', 'estimate', 'adaptive'), n = 1, keepMixedSpec = FALSE, distThreshold = 0.025, ...) {
 

R/plotColorMixture.R

@@ -3,7 +3,7 @@
 #' 
 #' @description Lattice visualization demonstrating subtractive mixtures of colors in Munsell notation and associated spectra.
 #' 
-#' @details If present, `names` attribute of `x` is used for the figure legend.
+#' @details If present, `names` attribute of `x` is used for the figure legend. See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for examples.
 #' 
 #' @author D.E. Beaudette
 #' 
@@ -32,37 +32,6 @@
 #' @seealso [mixMunsell()]
 #' @export
 #' 
-#' @examples 
-#' 
-#' # keep examples from using more than 2 cores
-#' data.table::setDTthreads(Sys.getenv("OMP_THREAD_LIMIT", unset = 2))
-#' 
-#' # color chips
-#' chips <- c('5B 5/10', '5Y 8/8')
-#' names(chips) <- chips
-#' 
-#' # weights
-#' wt <- c(1, 1)
-#' 
-#' if(requireNamespace("gower")) {
-#' plotColorMixture(
-#' x = chips, 
-#' w = wt, 
-#' label.cex = 0.65, 
-#' showMixedSpec = TRUE, 
-#' mixingMethod = 'reference'
-#' )
-#'
-#'}
-#'
-#' 
-#' plotColorMixture(
-#'   x = chips, 
-#'   w = wt, 
-#'   label.cex = 0.65, 
-#'   mixingMethod = 'exact'
-#' )
-#' 
 plotColorMixture <- function(x, w = rep(1, times = length(x)) / length(x), mixingMethod = c('exact', 'reference'), n = 1, swatch.cex = 1.5, label.cex = 0.85, showMixedSpec = FALSE, overlapFix = TRUE) {
 
   # TODO plot will be incorrect if duplicate Munsell chips are specified

R/spec2Munsell.R

@@ -7,6 +7,9 @@
 ## TODO: allow for more flexibility in spectra min/max/res wavelength
 
 #' @title Convert reflectance spectra to closest Munsell chip
+#' 
+#' @details See the [expanded tutorial](https://ncss-tech.github.io/AQP/aqp/mix-colors.html) for additional examples.
+#' 
 #' @param x reflectance spectra, must range from 380nm to 730nm with resolution specified in `res`
 #' 
 #' @param res spectra resolution in nm, typically 5nm or 10nm
@@ -61,6 +64,7 @@
 #'   labels = c('original', 'spectral\ninterpretation')
 #' )
 #' 
+#' \dontrun{
 #' if(requireNamespace("gower")) {
 #' # mix colors, return spectra, convert to color
 #' cols <- c('10YR 6/2', '5YR 5/6', '10B 4/4')
@@ -71,6 +75,7 @@
 #' spec2Munsell(res$spec)
 #' 
 #' }
+#' }
 #' 
 spec2Munsell <- function(x, res = 10, convert = TRUE, SO = c('CIE1931', 'CIE1964'), illuminant = c('D65', 'F2'), ...) {