Allow to highlight supplementary qualitative variables

NEWS.md

@@ -2,6 +2,9 @@
 ## Bugfixes & changes
 * The default number of labeled points can now be changed in `viz_individuals()`, `viz_row()`, `viz_variables()` and `viz_columns()`.
 
+## Enhancements
+* Allow to highlight supplementary qualitative variables in `viz_individuals()`, `viz_row()`, `viz_variables()` and `viz_columns()`.
+
 # dimensio 0.6.0
 ## New classes and methods
 * Add `predict()` method for MCA.

R/AllGenerics.R

@@ -699,7 +699,8 @@ setGeneric(
 #'  indicates variables/columns.
 #' @param axes A length-two [`numeric`] vector giving the dimensions
 #'  for which to compute results.
-#' @param group A vector specifying the group an observation belongs to.
+#' @param group A vector specifying the group an observation belongs to, or a
+#'  single `character` string giving the name of a categorical variable.
 #' @param level A [`numeric`] vector specifying the confidence/tolerance level.
 #' @param ... Currently not used.
 #' @return
@@ -738,21 +739,13 @@ setGeneric(
 
 #' Plot Envelopes
 #'
-#' @param x An object from which to wrap observations (a [`CA-class`],
-#'  [`MCA-class`] or [`PCA-class`] object).
-#' @param margin A length-one [`numeric`] vector giving the subscript which the
-#'  data will be returned: `1` indicates individuals/rows (the default), `2`
-#'  indicates variables/columns.
-#' @param axes A length-two [`numeric`] vector giving the dimensions
-#'  for which to compute results.
-#' @param group A vector specifying the group an observation belongs to.
-#' @param level A [`numeric`] vector specifying the confidence/tolerance level.
+#' @inheritParams wrap
 #' @param ... Further [graphical parameters][graphics::par] to be passed to
 #'  [graphics::polygon()].
 #' @return
 #'  `viz_*()`is called for its side-effects: it results in a graphic being
 #'  displayed. Invisibly returns `x`.
-#' @example inst/examples/ex-wrap.R
+#' @example inst/examples/ex-envelopes.R
 #' @author N. Frerebeau
 #' @docType methods
 #' @family plot methods

R/dimensio-internal.R

@@ -119,9 +119,9 @@ drop_variable <- function(x, f, negate = FALSE, sup = NULL, extra = NULL,
 #'  plotted?
 #' @param highlight A vector specifying the information to be highlighted.
 #'  If `NULL` (the default), no highlighting is applied. If a single `character`
-#'  string is passed, it must be one of "`observation`", "`mass`", "`sum`",
-#'  "`contribution`" or "`cos2`" (see [`augment()`]). Any unambiguous substring
-#'  can be given.
+#'  string is passed, it must be the name of a categorical variable, or one of
+#'  "`observation`", "`mass`", "`sum`", "`contribution`" or "`cos2`"
+#'  (see [`augment()`]).
 #  It will only be mapped if at least one [graphical parameters][graphics::par]
 #  is explicitly specified (see examples).
 #' @param col The colors for lines and points.
@@ -164,9 +164,16 @@ prepare <- function(x, margin, ..., axes = c(1, 2), active = TRUE,
   data$observation <- "active"
   data$observation[data$supplementary] <- "suppl."
   if (length(highlight) == 1) {
-    choices <- c("mass", "sum", "contribution", "cos2", "observation")
-    highlight <- match.arg(highlight, choices = choices, several.ok = FALSE)
-    highlight <- data[[highlight]]
+    high <- NULL
+    if (has_extra(x)) {
+      high <- get_extra(x)[[highlight]] %||% data[[highlight]]
+    }
+    if (is.null(high)) {
+      choices <- c("mass", "sum", "contribution", "cos2", "observation")
+      highlight <- match.arg(highlight, choices = choices, several.ok = FALSE)
+      high <- data[[highlight]]
+    }
+    highlight <- high
   }
   if (length(highlight) > 1) arkhe::assert_length(highlight, n)
 

R/mutators.R

@@ -22,7 +22,11 @@ get_order <- function(x, margin = 1) {
   ord
 }
 get_extra <- function(x) {
-  x@extra
+  as.data.frame(x@extra)
+}
+has_extra <- function(x) {
+  extra <- get_extra(x)
+  NROW(extra) > 0 && NCOL(extra) > 0
 }
 `set_extra<-` <- function(x, value) {
   x@extra <- value

R/viz_ellipse.R

@@ -68,10 +68,10 @@ setMethod(
   n <- length(ell)
 
   ## Graphical parameters
-  if (length(border) != n) border <- rep(border, length.out = n)
-  if (length(col) != n) col <- rep(col, length.out = n)
-  if (length(lty) != n) lty <- rep(lty, length.out = n)
-  if (length(lwd) != n) lwd <- rep(lwd, length.out = n)
+  if (length(border) == 1) border <- rep(border, length.out = n)
+  if (length(col) == 1) col <- rep(col, length.out = n)
+  if (length(lty) == 1) lty <- rep(lty, length.out = n)
+  if (length(lwd) == 1) lwd <- rep(lwd, length.out = n)
 
   for (i in seq_along(ell)) {
     lvl <- ell[[i]]

R/viz_hull.R

@@ -17,10 +17,10 @@ setMethod(
     col <- list(...)$col %||% NA
     lty <- list(...)$lty %||% graphics::par("lty")
     lwd <- list(...)$lwd %||% graphics::par("lwd")
-    if (length(border) != n) border <- rep(border, length.out = n)
-    if (length(col) != n) col <- rep(col, length.out = n)
-    if (length(lty) != n) lty <- rep(lty, length.out = n)
-    if (length(lwd) != n) lwd <- rep(lwd, length.out = n)
+    if (length(border) == 1) border <- rep(border, length.out = n)
+    if (length(col) == 1) col <- rep(col, length.out = n)
+    if (length(lty) == 1) lty <- rep(lty, length.out = n)
+    if (length(lwd) == 1) lwd <- rep(lwd, length.out = n)
 
     for (i in seq_along(hull)) {
       graphics::polygon(x = hull[[i]], border = border[i],

R/wrap_ellipses.R

@@ -17,15 +17,15 @@ setMethod(
 
     ## Add groups, if any
     k <- get_order(x, margin = margin)
-    if (!is.null(group)) {
+    if (length(group) == 1) group <- get_extra(x)[[group]]
+    if (length(group) > 0) {
       arkhe::assert_length(group, nrow(data))
       group <- group[k]
     } else if (has_groups(x, margin = margin)) {
       group <- get_groups(x, margin = margin)
     } else {
       group <- rep("", length(k))
     }
-    group <- as.character(group)
 
     ## Compute ellipse
     data <- split(data, f = group)
@@ -57,7 +57,8 @@ setMethod(
 
     ## Add groups, if any
     k <- get_order(x, margin = margin)
-    if (!is.null(group)) {
+    if (length(group) == 1) group <- get_extra(x)[[group]]
+    if (length(group) > 0) {
       arkhe::assert_length(group, nrow(data))
       group <- group[k]
     } else if (has_groups(x, margin = margin)) {

R/wrap_hull.R

@@ -15,7 +15,8 @@ setMethod(
 
     ## Add groups, if any
     k <- get_order(x, margin = margin)
-    if (!is.null(group)) {
+    if (length(group) == 1) group <- get_extra(x)[[group]]
+    if (length(group) > 0) {
       arkhe::assert_length(group, nrow(data))
       group <- group[k]
     } else if (has_groups(x, margin = margin)) {

inst/examples/ex-envelopes.R

@@ -0,0 +1,15 @@
+## Load data
+data("iris")
+
+## Compute principal components analysis
+X <- pca(iris, scale = TRUE, sup_quali = "Species")
+
+## Plot with convex hulls
+col <- c("#004488", "#DDAA33", "#BB5566")
+viz_rows(X, highlight = "Species", col = col)
+viz_hull(X, group = "Species", border = col)
+
+## Plot with tolerance ellipses
+col <- c("#004488", "#DDAA33", "#BB5566")
+viz_rows(X, highlight = "Species", col = col)
+viz_tolerance(X, group = "Species", border = col)

inst/examples/ex-wrap.R

@@ -2,19 +2,13 @@
 data("iris")
 
 ## Compute principal components analysis
-X <- pca(iris, scale = TRUE)
-
-## Convex hull coordinates
-hulls <- wrap_hull(X, margin = 1, group = iris$Species)
+X <- pca(iris, scale = TRUE, sup_quali = "Species")
 
 ## Confidence ellipse coordinates
-conf <- wrap_confidence(X, margin = 1, group = iris$Species,
-                        level = c(0.68, 0.95))
+conf <- wrap_confidence(X, margin = 1, group = "Species", level = c(0.68, 0.95))
 
 ## Tolerance ellipse coordinates
-conf <- wrap_confidence(X, margin = 1, group = iris$Species, level = 0.95)
+conf <- wrap_confidence(X, margin = 1, group = "Species", level = 0.95)
 
-## Plot with convex hulls
-col <- c("#004488", "#DDAA33", "#BB5566")
-viz_rows(X, highlight = iris$Species, col = col)
-viz_hull(X, group = iris$Species, border = col)
+## Convex hull coordinates
+hulls <- wrap_hull(X, margin = 1, group = "Species")