corrplot {corrplot}R Documentation

A visualization of a correlation matrix.

Description

A graphical display of a correlation matrix, confidence interval. The details are paid great attention to. It can also visualize a general matrix by setting is.corr = FALSE.

Usage

corrplot(corr, method = c("circle", "square", "ellipse", "number", "shade",

 "color", "pie"), type = c("full", "lower", "upper"), add = FALSE,

 col = NULL, bg = "white", title = "", is.corr = TRUE, diag = TRUE,

 outline = FALSE, mar = c(0, 0, 0, 0), addgrid.col = NULL,

 addCoef.col = NULL, addCoefasPercent = FALSE, order = c("original",

 "AOE", "FPC", "hclust", "alphabet"), hclust.method = c("complete", "ward",

 "ward.D", "ward.D2", "single", "average", "mcquitty", "median", "centroid"),

 addrect = NULL, rect.col = "black", rect.lwd = 2, tl.pos = NULL,

 tl.cex = 1, tl.col = "red", tl.offset = 0.4, tl.srt = 90,

 cl.pos = NULL, cl.lim = NULL, cl.length = NULL, cl.cex = 0.8,

 cl.ratio = 0.15, cl.align.text = "c", cl.offset = 0.5, number.cex = 1,

 number.font = 2, number.digits = NULL, addshade = c("negative",

 "positive", "all"), shade.lwd = 1, shade.col = "white", p.mat = NULL,

 sig.level = 0.05, insig = c("pch", "p-value", "blank", "n"), pch = 4,

 pch.col = "black", pch.cex = 3, plotCI = c("n", "square", "circle",

 "rect"), lowCI.mat = NULL, uppCI.mat = NULL, na.label = "?",

 na.label.col = "black", ...)

Arguments

corr

The correlation matrix to visualize, must be square if order is not "original". For general matrix, please using is.corr = FALSE to convert.

method

Character, the visualization method of correlation matrix to be used. Currently, it supports seven methods, named "circle" (default), "square", "ellipse", "number", "pie", "shade" and "color". See examples for details.

The areas of circles or squares show the absolute value of corresponding correlation coefficients. Method "pie" and "shade" came from Michael Friendly's job (with some adjustment about the shade added on), and "ellipse" came from D.J. Murdoch and E.D. Chow's job, see in section References.

type

Character, "full" (default), "upper" or "lower", display full matrix, lower triangular or upper triangular matrix.

add

Logical, if TRUE, the graph is added to an existing plot, otherwise a new plot is created.

col

Vector, the color of glyphs. It is distributed uniformly in cl.lim. If NULL, col will be colorRampPalette(col2)(200), see example about col2.

bg

The background color.

title

Character, title of the graph.

is.corr

Logical, whether the input matrix is a correlation matrix or not. We can visualize the non-correlation matrix by setting is.corr = FALSE.

diag

Logical, whether display the correlation coefficients on the principal diagonal.

outline

Logical or character, whether plot outline of circles, square and ellipse, or the color of these glyphs. If outline is TRUE, the default value is "black".

mar

See par.

addgrid.col

The color of the grid. If NA, don't add grid. If NULL the default value is chosen. The default value depends on method, if method is color or shade, the color of the grid is NA, that is, not draw grid; otherwise "grey".

addCoef.col

Color of coefficients added on the graph. If NULL (default), add no coefficients.

addCoefasPercent

Logic, whether translate coefficients into percentage style for spacesaving.

order

Character, the ordering method of the correlation matrix.

"original" for original order (default).

"AOE" for the angular order of the eigenvectors.

"FPC" for the first principal component order.

"hclust" for the hierarchical clustering order.

"alphabet" for alphabetical order.

See function corrMatOrder for details.

hclust.method

Character, the agglomeration method to be used when order is hclust. This should be one of "ward", "ward.D", "ward.D2", "single", "complete", "average", "mcquitty", "median" or "centroid".

addrect

Integer, the number of rectangles draws on the graph according to the hierarchical cluster, only valid when order is hclust. If NULL (default), then add no rectangles.

rect.col

Color for rectangle border(s), only valid when addrect is equal or greater than 1.

rect.lwd

Numeric, line width for borders for rectangle border(s), only valid when addrect is equal or greater than 1.

tl.pos

Character or logical, position of text labels. If character, it must be one of "lt", "ld", "td", "d" or "n". "lt"(default if type=="full") means left and top, "ld"(default if type=="lower") means left and diagonal, "td"(default if type=="upper") means top and diagonal(near), "d" means diagonal, "n" means don't add textlabel.

tl.cex

Numeric, for the size of text label (variable names).

tl.col

The color of text label.

tl.offset

Numeric, for text label, see text.

tl.srt

Numeric, for text label string rotation in degrees, see text.

cl.pos

Character or logical, position of color labels; If character, it must be one of "r" (default if type=="upper" or "full"), "b" (default if type=="lower") or "n", "n" means don't draw colorlabel.

cl.lim

The limits (x1, x2) in the colorlabel.

cl.length

Integer, the number of number-text in colorlabel, passed to colorlegend. If NULL, cl.length is length(col) + 1 when length(col) <=20; cl.length is 11 when length(col) > 20

cl.cex

Numeric, cex of number-label in colorlabel, passed to colorlegend.

cl.ratio

Numeric, to justify the width of colorlabel, 0.1~0.2 is suggested.

cl.align.text

Character, "l", "c" (default) or "r", for number-label in colorlabel, "l" means left, "c" means center, and "r" means right.

cl.offset

Numeric, for number-label in colorlabel, see text.

number.cex

The cex parameter to send to the call to text when writing the correlation coefficients into the plot.

number.font

the font parameter to send to the call to text when writing the correlation coefficients into the plot.

number.digits

indicating the number of decimal digits to be added into the plot. Non-negative integer or NULL, default NULL.

addshade

Character for shade style, "negative", "positive" or "all", only valid when method is "shade". If "all", all correlation coefficients' glyph will be shaded; if "positive", only the positive will be shaded; if "negative", only the negative will be shaded. Note: the angle of shade line is different, 45 degrees for positive and 135 degrees for negative.

shade.lwd

Numeric, the line width of shade.

shade.col

The color of shade line.

p.mat

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

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.

insig

Character, specialized insignificant correlation coefficients, "pch" (default), "p-value", "blank" or "n". If "blank", wipe away the corresponding glyphs; if "p-value", add p-values the corresponding glyphs; if "pch", add characters (see pch for details) on corresponding glyphs; if "n", don't take any measures.

pch

Add character on the glyphs of insignificant correlation coefficients(only valid when insig is "pch"). See par.

pch.col

The color of pch (only valid when insig is "pch").

pch.cex

The cex of pch (only valid when insig is "pch").

plotCI

Character, method of ploting confidence interval. If "n", don't plot confidence interval. If "rect", plot rectangles whose upper side means upper bound and lower side means lower bound, respectively, and meanwhile correlation coefficients are also added on the rectangles. If "circle", first plot a circle with the bigger absolute bound, and then plot the smaller. Warning: if the two bounds are the same sign, the smaller circle will be wiped away, thus forming a ring. Method "square" is similar to "circle".

lowCI.mat

Matrix of the lower bound of confidence interval.

uppCI.mat

Matrix of the upper bound of confidence interval.

na.label

Label to be used for rendering NA cells. Default is "?". If "square", then the cell is rendered as a square with the na.label.col color.

na.label.col

Color used for rendering NA cells. Default is "black".

...

Additional arguments passing to function text for drawing text lable.

Details

corrplot function offers flexible ways to visualize correlation matrix, lower and upper bound of confidence interval matrix.

Value

(Invisibly) returns a reordered correlation matrix.

Note

Cairo and cairoDevice packages is strongly recommended to produce high-quality PNG, JPEG, TIFF bitmap files, especially for that method circle, ellipse.

Author(s)

Taiyun Wei (weitaiyun@gmail.com)

Viliam Simko (viliam.simko@gmail.com)

References

Michael Friendly (2002). Corrgrams: Exploratory displays for correlation matrices. The American Statistician, 56, 316–324.

D.J. Murdoch, E.D. Chow (1996). A graphical display of large correlation matrices. The American Statistician, 50, 178–180.

See Also

Function plotcorr in the ellipse package and corrgram in the corrgram package have some similarities.

Package seriation offered more methods to reorder matrices, such as ARSA, BBURCG, BBWRCG, MDS, TSP, Chen and so forth.

Examples

data(mtcars)

M <- cor(mtcars)

##  different color series

col1 <- colorRampPalette(c("#7F0000","red","#FF7F00","yellow","white",

                          "cyan", "#007FFF", "blue","#00007F"))

col2 <- colorRampPalette(c("#67001F", "#B2182B", "#D6604D", "#F4A582", "#FDDBC7",

                          "#FFFFFF", "#D1E5F0", "#92C5DE", "#4393C3", "#2166AC", "#053061"))

col3 <- colorRampPalette(c("red", "white", "blue"))

col4 <- colorRampPalette(c("#7F0000","red","#FF7F00","yellow","#7FFF7F",

                          "cyan", "#007FFF", "blue","#00007F"))

wb <- c("white","black")

par(ask = TRUE)

## different color scale and methods to display corr-matrix

corrplot(M, method = "number", col = "black", cl.pos = "n")

corrplot(M, method = "number")

corrplot(M)

corrplot(M, order = "AOE")

corrplot(M, order = "AOE", addCoef.col = "grey")

corrplot(M, order = "AOE", col = col1(20), cl.length = 21, addCoef.col = "grey")

corrplot(M, order = "AOE", col = col1(10), addCoef.col = "grey")

corrplot(M, order = "AOE", col = col2(200))

corrplot(M, order = "AOE", col = col2(200), addCoef.col = "grey")

corrplot(M, order = "AOE", col = col2(20), cl.length = 21, addCoef.col = "grey")

corrplot(M, order = "AOE", col = col2(10), addCoef.col = "grey")

corrplot(M, order = "AOE", col = col3(100))

corrplot(M, order = "AOE", col = col3(10))

corrplot(M, method="color", col=col1(20), cl.length=21,order = "AOE", addCoef.col="grey")

corrplot(M, method="square", col=col2(200),order = "AOE")

corrplot(M, method="ellipse", col=col1(200),order = "AOE")

corrplot(M, method="shade", col=col3(20),order = "AOE")

corrplot(M, method="pie", order = "AOE")

## col=wb

corrplot(M, col = wb, order="AOE", outline=TRUE, cl.pos="n")

## like Chinese wiqi, suit for either on screen or white-black print.

corrplot(M, col = wb, bg="gold2",  order="AOE", cl.pos="n")

## mixed methods: It's more efficient if using function "corrplot.mixed"

## circle + ellipse

corrplot(M,order="AOE",type="upper",tl.pos="d")

corrplot(M,add=TRUE, type="lower", method="ell",order="AOE",

        diag=FALSE,tl.pos="n", cl.pos="n")

## circle + square

corrplot(M,order="AOE",type="upper",tl.pos="d")

corrplot(M,add=TRUE, type="lower", method="square",order="AOE",

        diag=FALSE,tl.pos="n", cl.pos="n")

## circle + colorful number

corrplot(M,order="AOE",type="upper",tl.pos="d")

corrplot(M,add=TRUE, type="lower", method="number",order="AOE",

        diag=FALSE,tl.pos="n", cl.pos="n")

## circle + black number

corrplot(M,order="AOE",type="upper",tl.pos="tp")

corrplot(M,add=TRUE, type="lower", method="number",order="AOE", col="black",

        diag=FALSE,tl.pos="n", cl.pos="n")

## order is hclust and draw rectangles

corrplot(M, order="hclust")

corrplot(M, order="hclust", addrect = 2)

corrplot(M, order="hclust", addrect = 3, rect.col = "red")

corrplot(M, order="hclust", addrect = 4, rect.col = "blue")

corrplot(M, order="hclust", hclust.method="ward", addrect = 4)

## visualize a  matrix in [0, 1]

corrplot(abs(M),order="AOE", cl.lim=c(0,1))

corrplot(abs(M),order="AOE", col=col1(20), cl.lim=c(0,1))

corrplot(abs(M),order="AOE", col=col3(200), cl.lim=c(0,1))

## visualize a  matrix in [-100, 100]

ran <- round(matrix(runif(225, -100,100), 15))

corrplot(ran, is.corr=FALSE)

corrplot(ran, is.corr=FALSE, cl.lim=c(-100, 100))

## text-labels and plot type

corrplot(M, order="AOE", tl.srt=45)

corrplot(M, order="AOE", tl.srt=60)

corrplot(M, order="AOE", tl.pos="d",cl.pos="n")

corrplot(M, order="AOE", diag=FALSE, tl.pos="d")

corrplot(M, order="AOE", type="upper")

corrplot(M, order="AOE", type="upper", diag=FALSE)

corrplot(M, order="AOE", type="lower", cl.pos="b")

corrplot(M, order="AOE", type="lower", cl.pos="b", diag=FALSE)

#### color-legend

corrplot(M, order="AOE", cl.ratio=0.2, cl.align="l")

corrplot(M, order="AOE", cl.ratio=0.2, cl.align="c")

corrplot(M, order="AOE", cl.ratio=0.2, cl.align="r")

corrplot(M, order="AOE", cl.pos="b")

corrplot(M, order="AOE", cl.pos="b", tl.pos="d")

corrplot(M, order="AOE", cl.pos="n")

## deal with missing Values

M2 <- M

diag(M2) = NA

corrplot(M2)

corrplot(M2, na.label = "o")

corrplot(M2, na.label = "NA")

##the input matrix is not square

corrplot(M[1:8,])

corrplot(M[,1:8])

cor.mtest <- function(mat, conf.level = 0.95){

 mat <- as.matrix(mat)

 n <- ncol(mat)

 p.mat <- lowCI.mat <- uppCI.mat <- matrix(NA, n, n)

 diag(p.mat) <- 0

 diag(lowCI.mat) <- diag(uppCI.mat) <- 1

 for(i in 1:(n-1)){

   for(j in (i+1):n){

     tmp <- cor.test(mat[,i], mat[,j], conf.level = conf.level)

     p.mat[i,j] <- p.mat[j,i] <- tmp$p.value

     lowCI.mat[i,j] <- lowCI.mat[j,i] <- tmp$conf.int[1]

     uppCI.mat[i,j] <- uppCI.mat[j,i] <- tmp$conf.int[2]

   }

 }

 return(list(p.mat, lowCI.mat, uppCI.mat))

}

res1 <- cor.mtest(mtcars,0.95)

res2 <- cor.mtest(mtcars,0.99)

## specialized the insignificant value according to the significant level

corrplot(M, p.mat = res1[[1]], sig.level=0.2)

corrplot(M, p.mat = res1[[1]], sig.level=0.05)

corrplot(M, p.mat = res1[[1]], sig.level=0.01)

corrplot(M, p.mat = res1[[1]], insig = "blank")

corrplot(M, p.mat = res1[[1]], insig = "p-value")

corrplot(M, p.mat = res1[[1]], insig = "p-value", sig.level=-1) ## add all p-values

corrplot(M, p.mat = res1[[1]], order="hclust", insig = "blank", addrect=3)

corrplot(M, p.mat = res1[[1]], order="hclust", insig = "pch", addrect=3)

## plot confidence interval(0.95), "square" method

corrplot(M,low=res1[[2]], upp=res1[[3]],

        plotC="circle", addg="grey20",cl.pos="n")

corrplot(M, p.mat = res1[[1]],low=res1[[2]], upp=res1[[3]],

        plotC="circle", addg="grey20",cl.pos="n")

corrplot(M, low=res1[[2]], upp=res1[[3]],

        col=c("white","black"),bg="gold2",order="AOE",

        plotCI="circle",cl.pos="n",pch.col="red")

corrplot(M, p.mat = res1[[1]], low=res1[[2]], upp=res1[[3]],

        col=c("white","black"),bg="gold2",order="AOE",

        plotCI="circle",cl.pos="n",pch.col="red")

## plot confidence interval(0.95), "square" method

corrplot(M, low=res1[[2]], upp=res1[[3]],

        col=c("white","black"),bg="gold2", order="AOE",

        plotCI="square",addg=NULL,cl.pos="n")

corrplot(M, p.mat = res1[[1]],low=res1[[2]], upp=res1[[3]],

        col=c("white","black"),bg="gold2",order="AOE",pch.col="red",

        plotC="square", addg=NULL,cl.pos="n")

## plot confidence interval(0.95, 0.95, 0.99), "rect" method

corrplot(M, low=res1[[2]], upp=res1[[3]], order="hclust",

        rect.col="navy", plotC="rect",cl.pos="n")

corrplot(M, p.mat = res1[[1]], low=res1[[2]], upp=res1[[3]], order="hclust",

        pch.col="red", sig.level = 0.05, addrect=3, rect.col="navy",

        plotC="rect",cl.pos="n")

corrplot(M, p.mat = res2[[1]], low=res2[[2]], upp=res2[[3]], order="hclust",

        pch.col="red", sig.level = 0.01, addrect=3, rect.col="navy",

        plotC="rect",cl.pos="n")

## an animation of changing confidence interval in different significance level

## begin.animaton

par(ask=FALSE)

for(i in seq(0.1, 0, -0.005)){

 tmp <- cor.mtest(mtcars,1-i)

 corrplot(M, p.mat = tmp[[1]], low=tmp[[2]], upp=tmp[[3]], order="hclust",

          pch.col="red", sig.level = i, plotC="rect", cl.pos="n",

          mar=c(0,0,1,0),

          title=substitute(alpha == x,list(x=format(i,digits=3,nsmall=3))))

 Sys.sleep(0.15)

}

## end.animaton