Package {ggcorrplot}

the correlation matrix to visualize

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

character, "full" (default), "lower" or "upper" display. A mixed layout (see lower.method/upper.method) always uses the full matrix.

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()'). A mixed "number" region reads the background from this argument, resolved against the default theme in force when ggcorrplot() is called, to decide how dark to draw the coefficient text (see lower.method/upper.method). So a dark theme belongs here rather than added to the returned plot with +, and a theme_set issued after the call is not seen.

character, title of the graph.

logical, if TRUE the legend is displayed.

a character string for the legend title. lower triangular, upper triangular or full matrix.

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

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 scale_fill_gradient2). A vector of any other length (>= 2) is spread evenly across the scale with scale_fill_gradientn, so an n-color palette (e.g. RColorBrewer::brewer.pal(11, "RdBu")) can be passed directly.

the outline color of square or circle. Default value is "gray".

logical value. If TRUE, correlation matrix will be hc.ordered using hclust function.

the agglomeration method to be used in hclust (see ?hclust).

logical value. If TRUE, add correlation coefficient on the plot.

size and color to be used for the correlation coefficient labels. used when lab = TRUE.

the font face ("plain", "bold", "italic", "bold.italic") for the correlation coefficient labels. Default is "plain". Used when lab = TRUE.

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

matrix of p-value. If NULL, arguments sig.level, insig, pch, pch.col, pch.cex is invalid.

significant level, if the p-value in p-mat is bigger than sig.level, then the corresponding correlation coefficient is regarded as insignificant. This governs which cells insig = "pch" marks and insig = "blank" wipes; the star thresholds used by insig = "stars" and sig.stars are fixed (see those arguments) and do not follow sig.level.

character, how to convey significance from p.mat: "pch" (default), "blank" or "stars". "pch" adds a character (see pch) on the glyphs of the insignificant cells; "blank" wipes those glyphs away; "stars" instead marks the SIGNIFICANT cells with significance stars (***/**/* for p <= 0.001/0.01/0.05 – fixed thresholds, not sig.level). With the default lab = FALSE the stars are drawn on their own (in pch.col, sized by lab_size) as a standalone significance map; with lab = TRUE they are appended to the coefficient labels (e.g. "-0.85***", as with sig.stars) so the two do not overprint.

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

the color and the cex (size) of pch (only valid when insig is "pch").

the size, the color and the string rotation of text label (variable names). tl.col defaults to NULL, which inherits the color from the theme.

the vertical and horizontal justification of the x-axis text labels, passed to element_text. Both default to 1; adjust them to reposition the variable-name labels.

Decides the number of decimal digits to be displayed (Default: '2').

retained for backward compatibility; no longer affects the plot. The axis is now always drawn in the matrix (row/column) order, so the variable-name handling this argument used to control is done internally.

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

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

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

a scaling factor for the circle sizes when method = "circle". Default is 1; increase it (e.g. 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 method = "square".

logical value. If TRUE (default), the plot uses coord_fixed so the cells are square. Set to FALSE to let the cells fill the plotting area (a non 1:1 aspect ratio), which can look better with many long variable names.

character, an optional per-triangle glyph for a mixed layout: one of "square", "circle" or "number" (the coefficient drawn as text, colored by its value on the fill ramp). When either is set, the plot switches to a mixed layout where the lower and upper triangles are drawn separately and the variable names are drawn on the diagonal; a triangle left NULL uses method. Both default to NULL (single-method plot, unchanged). In a mixed layout the single-method significance and label overlays (lab, sig.stars, p.mat, insig, pch*) do not apply; show coefficients with a "number" triangle instead.

Over a light background the "number" text is drawn on a darkened copy of the ramp – same hues, so warm still reads as positive and cool as negative, but dark enough that a coefficient near zero stays readable instead of washing out. Over a dark background the ramp is used as given, its pale middle being what reads there. The background is taken from ggtheme; a theme added to the returned plot with + arrives too late to be seen.

integer or NULL (default). If an integer k, draws k rectangles (no fill) around the clusters obtained by cutting the hierarchical tree, marking the cluster blocks on the diagonal. Requires hc.order = TRUE and type = "full" (the boxes span whole diagonal blocks). NULL (default) draws no rectangles. For a fully custom box style, add your own annotate("rect", ...) to the returned plot.

optional name of a built-in colorblind-safe diverging palette for the fill gradient: "RdBu" or "PuOr". A convenience shortcut for colors: when set it supplies the gradient (an 11-stop ramp, white at zero, cool = negative / warm = positive) and takes precedence over colors. Defaults to NULL (use colors), so existing calls are unchanged.

optional name of a bundle of publication-grade defaults. The only value, "publication", sets white cell outlines and the colorblind-safe "RdBu" palette in one token. It fills only the arguments you did not supply, so any argument you pass explicitly (e.g. outline.color, colors, palette) overrides the preset. Defaults to NULL (no preset), leaving existing calls unchanged.

the outline color of the hc.rect cluster rectangles. Defaults to "gray30"; set it to any color that suits your palette (e.g. "black" for a bolder box, or "white"). Only used when hc.rect is set.

logical. If TRUE and method = "square", the squares are sized by the absolute correlation (larger square = stronger correlation), in addition to the fill color – the classic corrplot size-scaled square look. Defaults to FALSE (constant full-cell squares, the current behavior). Has no effect for method = "circle" (circles are always sized). Uses circle.scale to tune the size range. As with method = "circle", coefficient labels (lab = TRUE) are drawn at full size and may overflow the smallest squares.

logical. If TRUE, draw a light rectangle around every cell (behind the glyphs) and remove the through-center gridlines, so the sized glyphs (method = "circle" or scale.square = TRUE) sit inside boxed cells – the corrplot boxed-cell look. Defaults to FALSE (the current behavior). Has no effect on a full-tile square heatmap (method = "square" without scale.square), whose tiles already carry a cell border (outline.color).

the color of the cell.grid cell borders. Defaults to "grey90". Only used when cell.grid = TRUE.

numeric matrix or data frame

other arguments to be passed to the function cor.test.

character, how to treat pairs involving missing values when deciding which cells are NA. Either "pairwise.complete.obs" (default; test every pair that has enough overlapping observations) or "everything" (set a pair to NA as soon as either variable has a missing value, matching cor's default). Mirrors the corresponding values of cor's use argument.