grouped_ggcorrmat
Visualization of a correlalogram (or correlation matrix) for all levels of a grouping variable
Helper function for ggstatsplot::ggcorrmat
to apply this
function across multiple levels of a given factor and combining the
resulting plots using ggstatsplot::combine_plots
.
Usage
grouped_ggcorrmat(data, cor.vars = NULL, cor.vars.names = NULL,
grouping.var, title.prefix = NULL, output = "plot",
matrix.type = "full", method = "square", corr.method = "pearson",
type = NULL, exact = FALSE, continuity = TRUE, beta = 0.1,
digits = 2, k = NULL, sig.level = 0.05, p.adjust.method = "none",
hc.order = FALSE, hc.method = "complete", lab = TRUE,
package = "RColorBrewer", palette = "Dark2", direction = 1,
colors = c("#E69F00", "white", "#009E73"), outline.color = "black",
ggtheme = ggplot2::theme_bw(), ggstatsplot.layer = TRUE,
subtitle = NULL, caption = NULL, caption.default = TRUE,
lab.col = "black", lab.size = 5, insig = "pch", pch = 4,
pch.col = "black", pch.cex = 11, tl.cex = 12, tl.col = "black",
tl.srt = 45, axis.text.x.margin.t = 0, axis.text.x.margin.r = 0,
axis.text.x.margin.b = 0, axis.text.x.margin.l = 0,
messages = TRUE, ...)
Arguments
- data
Dataframe from which variables specified are preferentially to be taken.
- cor.vars
List of variables for which the correlation matrix is to be computed and visualized. If
NULL
(default), all numeric variables fromdata
will be used.- cor.vars.names
Optional list of names to be used for
cor.vars
. The names should be entered in the same order.- grouping.var
A single grouping variable (can be entered either as a bare name
x
or as a string"x"
).- title.prefix
Character string specifying the prefix text for the fixed plot title (name of each factor level) (Default:
NULL
). IfNULL
, the variable name entered forgrouping.var
will be used.- output
Character that decides expected output from this function:
"plot"
(for visualization matrix) or"correlations"
(or"corr"
or"r"
; for correlation matrix) or"p-values"
(or"p.values"
or"p"
; for a matrix of p-values) or"ci"
(for a tibble with confidence intervals for unique correlation pairs; not available for robust correlation) or"n"
(or"sample.size"
for a tibble with sample sizes for each correlation pair).- matrix.type
Character,
"full"
(default),"upper"
or"lower"
, display full matrix, lower triangular or upper triangular matrix.- method
Character argument that decides the visualization method of correlation matrix to be used. Allowed values are
"square"
(default),"circle"
- corr.method
A character string indicating which correlation coefficient is to be computed (
"pearson"
(default) or"kendall"
or"spearman"
)."robust"
can also be entered but only ifoutput
argument is set to either"correlations"
or"p-values"
. The robust correlation used is percentage bend correlation (see?WRS2::pball
). Abbreviations will also work:"p"
(for parametric/Pearson's r),"np"
(nonparametric/Spearman's rho),"r"
(robust).- type
A character string indicating which correlation coefficient is to be computed (
"pearson"
(default) or"kendall"
or"spearman"
)."robust"
can also be entered but only ifoutput
argument is set to either"correlations"
or"p-values"
. The robust correlation used is percentage bend correlation (see?WRS2::pball
). Abbreviations will also work:"p"
(for parametric/Pearson's r),"np"
(nonparametric/Spearman's rho),"r"
(robust).- exact
A logical indicating whether an exact p-value should be computed. Used for Kendall's tau and Spearman's rho. For more details, see
?stats::cor.test
.- continuity
A logical. If
TRUE
, a continuity correction is used for Kendall's tau and Spearman's rho when not computed exactly (Default:TRUE
).- beta
A numeric bending constant for robust correlation coefficient (Default:
0.1
).- digits
Decides the number of decimal digits to be displayed (Default:
2
).- k
Decides the number of decimal digits to be displayed (Default:
2
).- sig.level
Significance level (Default:
0.05
). If the p-value in p-value matrix is bigger thansig.level
, then the corresponding correlation coefficient is regarded as insignificant and flagged as such in the plot. This argument is relevant only whenoutput = "plot"
.- p.adjust.method
What adjustment for multiple tests should be used? (
"holm"
,"hochberg"
,"hommel"
,"bonferroni"
,"BH"
,"BY"
,"fdr"
,"none"
). Seestats::p.adjust
for details about why to use"holm"
rather than"bonferroni"
). Default is"none"
. If adjusted p-values are displayed in the visualization of correlation matrix, the adjusted p-values will be used for the upper triangle, while unadjusted p-values will be used for the lower triangle of the matrix.- hc.order
Logical value. If
TRUE
, correlation matrix will be hc.ordered usinghclust
function (Default isFALSE
).- hc.method
The agglomeration method to be used in
hclust
(see?hclust
).- lab
Logical value. If
TRUE
, correlation coefficient values will be displayed in the plot.- package
Name of package from which the palette is desired as string or symbol.
- palette
Name of palette as string or symbol.
- direction
Either
1
or-1
. If-1
the palette will be reversed.- colors
A vector of 3 colors for low, mid, and high correlation values. If set to
NULL
, manual specification of colors will be turned off and 3 colors from the specifiedpalette
frompackage
will be selected.- outline.color
The outline color of square or circle. Default value is
"gray"
.- ggtheme
A function,
ggplot2
theme name. Default value isggplot2::theme_bw()
. Any of theggplot2
themes, or themes from extension packages are allowed (e.g.,ggthemes::theme_fivethirtyeight()
,hrbrthemes::theme_ipsum_ps()
, etc.).- ggstatsplot.layer
Logical that decides whether
theme_ggstatsplot
theme elements are to be displayed along with the selectedggtheme
(Default:TRUE
).- subtitle
The text for the plot subtitle.
- caption
The text for the plot caption. If not specified (if it is
NULL
, i.e.), a default caption will be shown.- caption.default
Logical decides whether the default caption should be shown.
- lab.col
Color to be used for the correlation coefficient labels (applicable only when
lab = TRUE
).- lab.size
Size to be used for the correlation coefficient labels (applicable only when
lab = TRUE
).- insig
Character used to show specialized insignificant correlation coefficients (
"pch"
(default) or"blank"
). If"blank"
, the corresponding glyphs will be removed; if "pch" is used, characters (see?pch
for details) will be added on the corresponding glyphs.- pch
Decides the glyphs (read point shapes) to be used for insignificant correlation coefficients (only valid when
insig = "pch"
). Default value ispch = 4
.- pch.col
The color and the cex (size) of
pch
(only valid wheninsig = "pch"
). Defaults arepch.col = "#F0E442"
andpch.cex = 10
.- pch.cex
The color and the cex (size) of
pch
(only valid wheninsig = "pch"
). Defaults arepch.col = "#F0E442"
andpch.cex = 10
.- tl.cex
The size, the color, and the string rotation of text label (variable names, i.e.).
- tl.col
The size, the color, and the string rotation of text label (variable names, i.e.).
- tl.srt
The size, the color, and the string rotation of text label (variable names, i.e.).
- axis.text.x.margin.t
Margins between x-axis and the variable name texts (t: top, r: right, b: bottom, l:left), especially useful in case the names are slanted, i.e. when the tl.srt is between
45
and75
(Defaults:0
,0
,0
,0
, resp.).- axis.text.x.margin.r
Margins between x-axis and the variable name texts (t: top, r: right, b: bottom, l:left), especially useful in case the names are slanted, i.e. when the tl.srt is between
45
and75
(Defaults:0
,0
,0
,0
, resp.).- axis.text.x.margin.b
Margins between x-axis and the variable name texts (t: top, r: right, b: bottom, l:left), especially useful in case the names are slanted, i.e. when the tl.srt is between
45
and75
(Defaults:0
,0
,0
,0
, resp.).- axis.text.x.margin.l
Margins between x-axis and the variable name texts (t: top, r: right, b: bottom, l:left), especially useful in case the names are slanted, i.e. when the tl.srt is between
45
and75
(Defaults:0
,0
,0
,0
, resp.).- messages
Decides whether messages references, notes, and warnings are to be displayed (Default:
TRUE
).- ...
Arguments passed on to
combine_plots
- title.text
String or plotmath expression to be drawn as title for the combined plot.
- title.color
Text color for title.
- title.size
Point size of title text.
- title.vjust
Vertical justification for title. Default =
0.5
(centered ony
).0
= baseline aty
,1
= ascender aty
.- title.hjust
Horizontal justification for title. Default =
0.5
(centered onx
).0
= flush-left at x,1
= flush-right.- title.fontface
The font face (
"plain"
,"bold"
(default),"italic"
,"bold.italic"
) for title.- caption.text
String or plotmath expression to be drawn as the caption for the combined plot.
- caption.color
Text color for caption.
- caption.size
Point size of title text.
- caption.vjust
Vertical justification for caption. Default =
0.5
(centered on y).0
= baseline at y,1
= ascender at y.- caption.hjust
Horizontal justification for caption. Default =
0.5
(centered on x).0
= flush-left at x,1
= flush-right.- caption.fontface
The font face (
"plain"
(default),"bold"
,"italic"
,"bold.italic"
) for caption.- sub.text
The label with which the combined plot should be annotated. Can be a plotmath expression.
- sub.color
Text color for annotation label (Default:
"black"
).- sub.size
Point size of annotation text (Default:
12
).- sub.x
The x position of annotation label (Default:
0.5
).- sub.y
The y position of annotation label (Default:
0.5
).- sub.hjust
Horizontal justification for annotation label (Default:
0.5
).- sub.vjust
Vertical justification for annotation label (Default:
0.5
).- sub.vpadding
Vertical padding. The total vertical space added to the label, given in grid units. By default, this is added equally above and below the label. However, by changing the y and vjust parameters, this can be changed (Default:
grid::unit(1, "lines")
).- sub.fontface
The font face (
"plain"
(default),"bold"
,"italic"
,"bold.italic"
) for the annotation label.- sub.angle
Angle at which annotation label is to be drawn (Default:
0
).- sub.lineheight
Line height of annotation label.
- title.caption.rel.heights
Numerical vector of relative columns heights while combining (title, plot, caption).
- title.rel.heights
Numerical vector of relative columns heights while combining (title, plot).
- caption.rel.heights
Numerical vector of relative columns heights while combining (plot, caption).
Value
Correlation matrix plot or correlation coefficient matrix or matrix of p-values.
References
https://indrajeetpatil.github.io/ggstatsplot/articles/web_only/ggcorrmat.html
See Also
Examples
# NOT RUN {
# for reproducibility
set.seed(123)
# for plot
# (without specifiying needed variables; all numeric variables will be used)
ggstatsplot::grouped_ggcorrmat(
data = ggplot2::msleep,
grouping.var = vore
)
# for getting plot
ggstatsplot::grouped_ggcorrmat(
data = ggplot2::msleep,
grouping.var = vore,
cor.vars = sleep_total:bodywt,
corr.method = "r",
p.adjust.method = "holm",
colors = NULL,
package = "wesanderson",
palette = "BottleRocket2",
nrow = 2
)
# for getting correlations
ggstatsplot::grouped_ggcorrmat(
data = ggplot2::msleep,
grouping.var = vore,
cor.vars = sleep_total:bodywt,
output = "correlations"
)
# for getting confidence intervals
# confidence intervals are not available for **robust** correlation
ggstatsplot::grouped_ggcorrmat(
data = datasets::iris,
grouping.var = Species,
corr.method = "r",
p.adjust.method = "holm",
cor.vars = Sepal.Length:Petal.Width,
output = "ci"
)
# }