Add hc.rect.col to set the cluster-rectangle outline color

NEWS.md

@@ -31,7 +31,8 @@
 - New argument `hc.rect` to draw rectangles around the clusters of a
   hierarchically-ordered correlogram: `ggcorrplot(corr, hc.order = TRUE,
   hc.rect = 3)` frames the 3 clusters obtained by cutting the tree. Defaults to
-  `NULL` (no rectangles).
+  `NULL` (no rectangles). The rectangle outline color is set with the companion
+  argument `hc.rect.col` (default `"gray30"`, e.g. `hc.rect.col = "white"`).
 
 ## Main changes
 

R/ggcorrplot.R

@@ -55,12 +55,16 @@
 #'   using hclust function.
 #' @param hc.method the agglomeration method to be used in hclust (see ?hclust).
 #' @param hc.rect integer or \code{NULL} (default). If an integer \code{k}, draws
-#'   \code{k} rectangles (fixed style: grey outline, no fill) around the clusters
-#'   obtained by cutting the hierarchical tree, marking the cluster blocks on the
-#'   diagonal. Requires \code{hc.order = TRUE} and \code{type = "full"} (the boxes
-#'   span whole diagonal blocks). \code{NULL} (default) draws no rectangles. For a
+#'   \code{k} rectangles (no fill) around the clusters obtained by cutting the
+#'   hierarchical tree, marking the cluster blocks on the diagonal. Requires
+#'   \code{hc.order = TRUE} and \code{type = "full"} (the boxes span whole
+#'   diagonal blocks). \code{NULL} (default) draws no rectangles. For a fully
 #'   custom box style, add your own \code{annotate("rect", ...)} to the returned
 #'   plot.
+#' @param hc.rect.col the outline color of the \code{hc.rect} cluster rectangles.
+#'   Defaults to \code{"gray30"}; set it to any color that suits your palette
+#'   (e.g. \code{"black"} for a bolder box, or \code{"white"}). Only used when
+#'   \code{hc.rect} is set.
 #' @param lab logical value. If TRUE, add correlation coefficient on the plot.
 #' @param lab_col,lab_size size and color to be used for the correlation
 #'   coefficient labels. used when lab = TRUE.
@@ -253,7 +257,8 @@ ggcorrplot <- function(corr,
                        upper.method = NULL,
                        hc.rect = NULL,
                        palette = NULL,
-                       preset = NULL) {
+                       preset = NULL,
+                       hc.rect.col = "gray30") {
   type <- match.arg(type)
   method <- match.arg(method)
   # Resolve on insig[1] (not match.arg(insig)) so a caller passing the old
@@ -568,7 +573,7 @@ ggcorrplot <- function(corr,
       "rect",
       xmin = b$lo - 0.5, xmax = b$hi + 0.5,
       ymin = b$lo - 0.5, ymax = b$hi + 0.5,
-      fill = NA, colour = "gray30"
+      fill = NA, colour = hc.rect.col
     )
   }
 

tests/testthat/test-hc-rect-col.R

@@ -0,0 +1,34 @@
+# hc.rect.col: control the outline color of the hc.rect cluster rectangles.
+# Default "gray30" keeps existing output byte-identical.
+
+corr <- round(cor(mtcars), 1)
+rect_col <- function(p) {
+  i <- which(vapply(p$layers, function(l) class(l$geom)[1], "") == "GeomRect")
+  p$layers[[i]]$aes_params$colour
+}
+
+test_that("hc.rect.col defaults to gray30 (unchanged output)", {
+  p <- ggcorrplot(corr, hc.order = TRUE, hc.rect = 3)
+  expect_identical(rect_col(p), "gray30")
+  # explicit default equals the implicit default (byte-identical layer data)
+  expect_equal(
+    ggplot2::ggplot_build(ggcorrplot(corr, hc.order = TRUE, hc.rect = 3))$data,
+    ggplot2::ggplot_build(ggcorrplot(corr, hc.order = TRUE, hc.rect = 3, hc.rect.col = "gray30"))$data
+  )
+})
+
+test_that("hc.rect.col sets the rectangle outline color", {
+  expect_identical(rect_col(ggcorrplot(corr, hc.order = TRUE, hc.rect = 3, hc.rect.col = "white")), "white")
+  expect_identical(rect_col(ggcorrplot(corr, hc.order = TRUE, hc.rect = 3, hc.rect.col = "black")), "black")
+  expect_identical(rect_col(ggcorrplot(corr, hc.order = TRUE, hc.rect = 2, hc.rect.col = "#E46726")), "#E46726")
+})
+
+test_that("hc.rect.col is inert when no rectangles are drawn", {
+  # no hc.rect -> no GeomRect layer, and setting hc.rect.col changes nothing
+  p <- ggcorrplot(corr, hc.order = TRUE, hc.rect.col = "white")
+  expect_false("GeomRect" %in% vapply(p$layers, function(l) class(l$geom)[1], ""))
+  expect_equal(
+    ggplot2::ggplot_build(ggcorrplot(corr, hc.order = TRUE))$data,
+    ggplot2::ggplot_build(ggcorrplot(corr, hc.order = TRUE, hc.rect.col = "white"))$data
+  )
+})