% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggcorrplot.R
\name{ggcorrplot}
\alias{ggcorrplot}
\alias{cor_pmat}
\title{Visualization of a correlation matrix using ggplot2}
\usage{
ggcorrplot(
  corr,
  method = c("square", "circle"),
  type = c("full", "lower", "upper"),
  ggtheme = ggplot2::theme_minimal,
  title = "",
  show.legend = TRUE,
  legend.title = "Corr",
  show.diag = NULL,
  colors = c("blue", "white", "red"),
  outline.color = "gray",
  hc.order = FALSE,
  hc.method = "complete",
  lab = FALSE,
  lab_col = "black",
  lab_size = 4,
  lab_fontface = "plain",
  sig.stars = FALSE,
  p.mat = NULL,
  sig.level = 0.05,
  insig = c("pch", "blank"),
  pch = 4,
  pch.col = "black",
  pch.cex = 5,
  tl.cex = 12,
  tl.col = NULL,
  tl.srt = 45,
  tl.vjust = 1,
  tl.hjust = 1,
  digits = 2,
  as.is = FALSE,
  nsmall = 0L,
  leading.zero = TRUE,
  legend.limit = c(-1, 1),
  circle.scale = 1,
  coord.fixed = TRUE
)

cor_pmat(x, ..., use = c("pairwise.complete.obs", "everything"))
}
\arguments{
\item{corr}{the correlation matrix to visualize}

\item{method}{character, the visualization method of correlation matrix to be
used. Allowed values are "square" (default), "circle".}

\item{type}{character, "full" (default), "lower" or "upper" display.}

\item{ggtheme}{ggplot2 function or theme object. Default value is
`theme_minimal`. Allowed values are the official ggplot2 themes including
theme_gray, theme_bw, theme_minimal, theme_classic, theme_void, .... Theme
objects are also allowed (e.g., `theme_classic()`).}

\item{title}{character, title of the graph.}

\item{show.legend}{logical, if TRUE the legend is displayed.}

\item{legend.title}{a character string for the legend title. lower
triangular, upper triangular or full matrix.}

\item{show.diag}{NULL or logical, whether display the correlation
coefficients on the principal diagonal. If \code{NULL}, the default is to
show diagonal correlation for \code{type = "full"} and to remove it when
\code{type} is one of "upper" or "lower".}

\item{colors}{a vector of colors for the fill gradient. The default is a
length-3 vector for the low, mid and high correlation values (mapped with
\code{\link[ggplot2]{scale_fill_gradient2}}). A vector of any other length
(\code{>= 2}) is spread evenly across the scale with
\code{\link[ggplot2]{scale_fill_gradientn}}, so an n-color palette (e.g.
\code{RColorBrewer::brewer.pal(11, "RdBu")}) can be passed directly.}

\item{outline.color}{the outline color of square or circle. Default value is
"gray".}

\item{hc.order}{logical value. If TRUE, correlation matrix will be hc.ordered
using hclust function.}

\item{hc.method}{the agglomeration method to be used in hclust (see ?hclust).}

\item{lab}{logical value. If TRUE, add correlation coefficient on the plot.}

\item{lab_col, lab_size}{size and color to be used for the correlation
coefficient labels. used when lab = TRUE.}

\item{lab_fontface}{the font face (\code{"plain"}, \code{"bold"},
\code{"italic"}, \code{"bold.italic"}) for the correlation coefficient
labels. Default is \code{"plain"}. Used when \code{lab = TRUE}.}

\item{sig.stars}{logical value. If \code{TRUE} and a \code{p.mat} is
supplied, significance stars are appended to the coefficient labels
(\code{***} for p < 0.001, \code{**} for p < 0.01, \code{*} for p < 0.05),
e.g. \code{"-0.85**"}. Only used when \code{lab = TRUE}. Default is
\code{FALSE}. When \code{TRUE}, significance is shown by the stars and the
\code{insig = "pch"} markers are not drawn.}

\item{p.mat}{matrix of p-value. If NULL, arguments sig.level, insig, pch,
pch.col, pch.cex is invalid.}

\item{sig.level}{significant level, if the p-value in p-mat is bigger than
sig.level, then the corresponding correlation coefficient is regarded as
insignificant.}

\item{insig}{character, specialized insignificant correlation coefficients,
"pch" (default), "blank". If "blank", wipe away the corresponding glyphs;
if "pch", add characters (see pch for details) on corresponding glyphs.}

\item{pch}{add character on the glyphs of insignificant correlation
coefficients (only valid when insig is "pch"). Default value is 4.}

\item{pch.col, pch.cex}{the color and the cex (size) of pch (only valid when
insig is "pch").}

\item{tl.cex, tl.col, tl.srt}{the size, the color and the string rotation of
text label (variable names). \code{tl.col} defaults to \code{NULL}, which
inherits the color from the theme.}

\item{tl.vjust, tl.hjust}{the vertical and horizontal justification of the
x-axis text labels, passed to \code{\link[ggplot2]{element_text}}. Both
default to \code{1}; adjust them to reposition the variable-name labels.}

\item{digits}{Decides the number of decimal digits to be displayed (Default:
`2`).}

\item{as.is}{A logical passed to \code{\link[reshape2]{melt.array}}. If
\code{TRUE}, dimnames will be left as strings instead of being converted
using \code{\link[utils]{type.convert}}.}

\item{nsmall}{the minimum number of digits to the right of the decimal point
in the coefficient labels, passed to \code{\link[base]{format}}. Default is
\code{0} (no minimum, current behavior). Set e.g. \code{nsmall = 2} to keep
trailing zeros (such as 0.70). Only used when \code{lab = TRUE}.}

\item{leading.zero}{logical. If \code{TRUE} (default), coefficient labels keep
the leading zero (e.g. \code{0.23}, \code{-0.67}). Set to \code{FALSE} to
drop it (\code{.23}, \code{-.67}), which is common for correlation tables.
Only used when \code{lab = TRUE}.}

\item{legend.limit}{a length-2 numeric vector giving the limits of the fill
color scale. Default \code{c(-1, 1)} (suitable for a correlation matrix); set
to \code{NULL} to use the data range instead, e.g. for a covariance matrix.}

\item{circle.scale}{a scaling factor for the circle sizes when
\code{method = "circle"}. Default is \code{1}; increase it (e.g.
\code{circle.scale = 2}) for larger circles or decrease it for smaller ones,
which is useful when the output device size makes the default circles too
small or too large. Has no effect when \code{method = "square"}.}

\item{coord.fixed}{logical value. If \code{TRUE} (default), the plot uses
\code{\link[ggplot2]{coord_fixed}} so the cells are square. Set to
\code{FALSE} to let the cells fill the plotting area (a non 1:1 aspect
ratio), which can look better with many long variable names.}

\item{x}{numeric matrix or data frame}

\item{...}{other arguments to be passed to the function cor.test.}

\item{use}{character, how to treat pairs involving missing values when
deciding which cells are \code{NA}. Either \code{"pairwise.complete.obs"}
(default; test every pair that has enough overlapping observations) or
\code{"everything"} (set a pair to \code{NA} as soon as either variable has
a missing value, matching \code{\link[stats]{cor}}'s default). Mirrors the
corresponding values of \code{\link[stats]{cor}}'s \code{use} argument.}
}
\value{
\itemize{ \item ggcorrplot(): Returns a ggplot2 \item cor_pmat():
Returns a matrix containing the p-values of correlations }
}
\details{
\code{cor_pmat()} tests each pair of columns with
\code{\link[stats]{cor.test}}. A pair with fewer than three overlapping
non-missing observations (which \code{\link[stats]{cor.test}} cannot test,
e.g. two variables that never co-occur) yields \code{NA} for that cell
rather than aborting the whole computation. Pairs that can be tested are
computed as before, and errors they raise are passed through.

The \code{use} argument controls which pairs are returned as \code{NA} so
the p-value matrix can be aligned with a correlation matrix built the same
way. With the default \code{"pairwise.complete.obs"} every pair that has
enough overlapping observations is tested (the previous behavior). With
\code{"everything"} a pair is set to \code{NA} whenever either variable has
any missing value, so the \code{NA} pattern matches
\code{\link[stats]{cor}(x)} with its default \code{use = "everything"}.
}
\description{
\itemize{ \item ggcorrplot(): A graphical display of a
  correlation matrix using ggplot2. \item cor_pmat(): Compute a correlation
  matrix p-values. }
}
\examples{
# Compute a correlation matrix
data(mtcars)
corr <- round(cor(mtcars), 1)
corr

# Compute a matrix of correlation p-values
p.mat <- cor_pmat(mtcars)
p.mat

# Visualize the correlation matrix
# --------------------------------
# method = "square" or "circle"
ggcorrplot(corr)
ggcorrplot(corr, method = "circle")

# Reordering the correlation matrix
# --------------------------------
# using hierarchical clustering
ggcorrplot(corr, hc.order = TRUE, outline.color = "white")

# Types of correlogram layout
# --------------------------------
# Get the lower triangle
ggcorrplot(corr,
  hc.order = TRUE, type = "lower",
  outline.color = "white"
)
# Get the upeper triangle
ggcorrplot(corr,
  hc.order = TRUE, type = "upper",
  outline.color = "white"
)

# Change colors and theme
# --------------------------------
# Argument colors
ggcorrplot(corr,
  hc.order = TRUE, type = "lower",
  outline.color = "white",
  ggtheme = ggplot2::theme_gray,
  colors = c("#6D9EC1", "white", "#E46726")
)

# Add correlation coefficients
# --------------------------------
# argument lab = TRUE
ggcorrplot(corr,
  hc.order = TRUE, type = "lower",
  lab = TRUE,
  ggtheme = ggplot2::theme_dark(),
)

# Add correlation significance level
# --------------------------------
# Argument p.mat
# Barring the no significant coefficient
ggcorrplot(corr,
  hc.order = TRUE,
  type = "lower", p.mat = p.mat
)
# Leave blank on no significant coefficient
ggcorrplot(corr,
  p.mat = p.mat, hc.order = TRUE,
  type = "lower", insig = "blank"
)

# Changing number of digits for correlation coeffcient
# --------------------------------
ggcorrplot(cor(mtcars),
  type = "lower",
  insig = "blank",
  lab = TRUE,
  digits = 3
)
}
