diff --git a/NEWS.md b/NEWS.md index 73a0393..3148f5a 100644 --- a/NEWS.md +++ b/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 diff --git a/R/ggcorrplot.R b/R/ggcorrplot.R index 783f002..cd3e5b5 100644 --- a/R/ggcorrplot.R +++ b/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 ) } diff --git a/man/ggcorrplot.Rd b/man/ggcorrplot.Rd index ac9ce87..836c2c3 100644 --- a/man/ggcorrplot.Rd +++ b/man/ggcorrplot.Rd @@ -45,7 +45,8 @@ ggcorrplot( upper.method = NULL, hc.rect = NULL, palette = NULL, - preset = NULL + preset = NULL, + hc.rect.col = "gray30" ) cor_pmat(x, ..., use = c("pairwise.complete.obs", "everything")) @@ -183,10 +184,10 @@ In a mixed layout the single-method significance and label overlays not apply; show coefficients with a "number" triangle instead.} \item{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.} @@ -204,6 +205,11 @@ supply, so any argument you pass explicitly (e.g. \code{outline.color}, \code{colors}, \code{palette}) overrides the preset. Defaults to \code{NULL} (no preset), leaving existing calls unchanged.} +\item{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.} + \item{x}{numeric matrix or data frame} \item{...}{other arguments to be passed to the function cor.test.} diff --git a/tests/testthat/test-hc-rect-col.R b/tests/testthat/test-hc-rect-col.R new file mode 100644 index 0000000..f31d7f0 --- /dev/null +++ b/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 + ) +})