corr_heat: Visualize a correlation matrix
In m-clark/visibly: Functions and palettes related to visual enhancement

Description Usage Arguments Details Value Note See Also Examples

Visualize a correlation matrix

corr_heat(
  cormat,
  n_factors = NULL,
  psych_opts = NULL,
  ordering = c("fa", "raw", "absolute", "first", "polar"),
  three_d = FALSE,
  diagonal = 1,
  dir = -1,
  pal = "vik",
  plot_only = FALSE
)

`cormat`	A correlation matrix
`n_factors`	The number of factors for the factor analysis. Default is NULL.
`psych_opts`	a list of arguments to pass to `psych::fa`.
`ordering`	Order of the result. See details
`three_d`	Return a surface plot.
`diagonal`	Value for the diagonal. Must be 1 (default), 0, or NA.
`dir`	Passed to scico.
`pal`	Passed to scico.
`plot_only`	Don't run the factor analysis and just return the heatmap. Default is FALSE.

Correlation matrices are typically better visualized rather than parsed numerically, and while one can do so with various packages at this point, they either don't reorder the data, don't show the actual values, or only order based on cluster analysis, and one often may not want the cluster based approach to ordering if dealing with a correlation matrix, which may be too small column-wise to be useful for a cluster analysis, or may be a specific type of data more amenable to a measurement error approach (e.g. items from a particular scale).

The default corrheat visualization produces a color-coded heatmap in which Blue represents positive, and Red, negative correlations (the 'vik' palette), and fades to white the smaller the values are. It is interactive, such that one can hover over the image to obtain the correlation value.

The ordering is based on the results of a factor analysis from the psych package (which is required). It can be based on fa.sort (default), max raw ("raw") loading, absolute ("absolute") values of the loadings, loadings of the first factor only ('first'), or polar coordinates (see polar ) across all factors.

By default, the number of factors is chosen to more likely 'just work' for visualization purposes. If the number of columns is three or fewer, it will force only one factor, otherwise it will be floor(sqrt(ncol(x)))). While you may supply the number of factors, as well as other options to the fa function via psych_opts, if you want to explore a factor analysis you should you probably do that separately. In addition, factor analysis can't fix a poorly conditioned correlation matrix, and errors in the analysis may result in the plot failing.

There are two options regarding the palette, the name of the scico palette and the direction, in case you want to flip the color scheme. Typically, you'll want to use a diverging palette such as vik or cork. If you have all positive (or rarely, negative), you might consider the sequential ones like bilbao or oslo. The lower or upper limit of the color bar will change accordingly.

I'm normally against 3-d images as they really don't apply in many cases where they are used, but I think it can actually assist in seeing factor structure here.

A plotly object

This function essentially assumes a complete correlation matrix like that returned from cor, and one which should have row/column names. With plot_only = TRUE, you may potentially supply any matrix, as the factor analysis will not be done.

scico, plotly, fa

## Not run: 
# not run due to package dependencies noted above. make sure to install them.
library(visibly)
data('bfi')
corr_heat(cor(bfi, use='pair'), diagonal = NA, pal = 'broc')
corr_heat(cor(bfi, use='pair'), diagonal = NA, pal = 'broc', dir=1)
corr_heat(psych::Harman23.cor$cov, n_factors = 2, pal = 'oslo')
corr_heat(cormat = cor(mtcars))
corr_heat(cormat = cor(mtcars), ordering = 'polar', three_d=TRUE)

## End(Not run)