# ggcorrmat

##### Visualization of a correlalogram (or correlation matrix)

Visualization of a correlalogram (or correlation matrix)

##### Usage

```
ggcorrmat(data, cor.vars = NULL, cor.vars.names = 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, title = NULL, 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.l = 0, axis.text.x.margin.t = 0,
axis.text.x.margin.r = 0, axis.text.x.margin.b = 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.- 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, 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, 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`

).- title
The text for the plot title.

- 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, 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, tl.col, tl.srt
The size, the color, and the string rotation of text label (variable names, i.e.).

- axis.text.x.margin.t, axis.text.x.margin.r, axis.text.x.margin.b, 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`

and`75`

(Defaults:`0`

,`0`

,`0`

,`0`

, resp.).- messages
Decides whether messages references, notes, and warnings are to be displayed (Default:

`TRUE`

).

##### 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)
# if `cor.vars` not specified, all numeric varibles used
ggstatsplot::ggcorrmat(data = iris)
# to get the correlalogram
# note that the function will run even if the vector with variable names is
# not of same length as the number of variables
ggstatsplot::ggcorrmat(
data = ggplot2::msleep,
cor.vars = sleep_total:bodywt,
cor.vars.names = c("total sleep", "REM sleep")
) + # further modification using `ggplot2`
ggplot2::scale_y_discrete(position = "right")
# to get the correlation matrix
ggstatsplot::ggcorrmat(
data = ggplot2::msleep,
cor.vars = sleep_total:bodywt,
output = "r"
)
# setting output = "p-values" (or "p") will return the p-value matrix
ggstatsplot::ggcorrmat(
data = ggplot2::msleep,
cor.vars = sleep_total:bodywt,
corr.method = "r",
p.adjust.method = "bonferroni",
output = "p"
)
# setting `output = "ci"` will return the confidence intervals for unique
# correlation pairs
ggstatsplot::ggcorrmat(
data = ggplot2::msleep,
cor.vars = sleep_total:bodywt,
p.adjust.method = "BH",
output = "ci"
)
# modifying elements of the correlation matrix by changing function defaults
ggstatsplot::ggcorrmat(
data = datasets::iris,
cor.vars = c(Sepal.Length, Sepal.Width, Petal.Length, Petal.Width),
sig.level = 0.01,
ggtheme = ggplot2::theme_bw(),
hc.order = TRUE,
matrix.type = "lower",
outline.col = "white",
title = "Dataset: Iris"
)
# }
```

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