# 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 from`data`

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`

). If`NULL`

, the variable name entered for`grouping.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 if`output`

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 if`output`

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 than`sig.level`

, then the corresponding correlation coefficient is regarded as insignificant and flagged as such in the plot. This argument is relevant only when`output = "plot"`

.- p.adjust.method
What adjustment for multiple tests should be used? (

`"holm"`

,`"hochberg"`

,`"hommel"`

,`"bonferroni"`

,`"BH"`

,`"BY"`

,`"fdr"`

,`"none"`

). See`stats::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 using`hclust`

function (Default is`FALSE`

).- 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 specified`palette`

from`package`

will be selected.- outline.color
The outline color of square or circle. Default value is

`"gray"`

.- ggtheme
A function,

`ggplot2`

theme name. Default value is`ggplot2::theme_bw()`

. Any of the`ggplot2`

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 selected`ggtheme`

(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 is`pch = 4`

.- pch.col
The color and the cex (size) of

`pch`

(only valid when`insig = "pch"`

). Defaults are`pch.col = "#F0E442"`

and`pch.cex = 10`

.- pch.cex
The color and the cex (size) of

`pch`

(only valid when`insig = "pch"`

). Defaults are`pch.col = "#F0E442"`

and`pch.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`

and`75`

(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`

and`75`

(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`

and`75`

(Defaults:`0`

,`0`

,`0`

,`0`

, resp.).- axis.text.x.margin.l
`45`

and`75`

(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 on`y`

).`0`

= baseline at`y`

,`1`

= ascender at`y`

.- title.hjust
Horizontal justification for title. Default =

`0.5`

(centered on`x`

).`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"
)
# }
```

*Documentation reproduced from package ggstatsplot, version 0.0.11, License: GPL-3 | file LICENSE*