cor.matrix {misty}

Correlation Matrix

Description

This function computes a correlation matrix based on Pearson product-moment correlation coefficient, Spearman's rank-order correlation coefficient, Kendall's Tau-b correlation coefficient, Kendall-Stuart's Tau-c correlation coefficient, tetrachoric correlation coefficient, or polychoric correlation coefficient and computes significance values (p-values) for testing the hypothesis H0: \rho = 0 for all pairs of variables.

Usage

cor.matrix(..., data = NULL,
           method = c("pearson", "spearman", "kendall-b", "kendall-c", "tetra", "poly"),
           na.omit = FALSE, group = NULL, sig = FALSE, alpha = 0.05,
           print = c("all", "cor", "n", "stat", "df", "p"),
           tri = c("both", "lower", "upper"),
           p.adj = c("none", "bonferroni", "holm", "hochberg", "hommel",
                     "BH", "BY", "fdr"), continuity = TRUE,
           digits = 2, p.digits = 3, as.na = NULL,
           write = NULL, append = TRUE, check = TRUE, output = TRUE)

Arguments

...

a matrix or data frame. Alternatively, an expression indicating the variable names in data e.g., cor.matrix(x1, x2, x3, data = dat). Note that the operators ., +, -, ~, :, ::, and ! can also be used to select variables, see 'Details' in the df.subset function.

data

a data frame when specifying one or more variables in the argument .... Note that the argument is NULL when specifying a matrix or data frame for the argument ....

method

a character vector indicating which correlation coefficient is to be computed, i.e. "pearson" for Pearson product-moment correlation coefficient (default), "spearman" for Spearman's rank-order correlation coefficient, "kendall-b" for Kendall's Tau-b correlation coefficient, "kendall-c" for Kendall-Stuart's Tau-c correlation coefficient, "tetra" for tetrachoric correlation coefficient, and "poly" for polychoric correlation coefficient.

na.omit

logical: if TRUE, incomplete cases are removed before conducting the analysis (i.e., listwise deletion); if FALSE (default), pairwise deletion is used.

group

either a character string indicating the variable name of the grouping variable in ... or data, or a vector representing the grouping variable. Note that the grouping variable is limited to two groups.

sig

logical: if TRUE, statistically significant correlation coefficients are shown in boldface on the console. Note that this function does not provide statistical significance testing for tetrachoric or polychoric correlation coefficients.

alpha

a numeric value between 0 and 1 indicating the significance level at which correlation coefficients are printed boldface when sig = TRUE.

print

a character string or character vector indicating which results to show on the console, i.e. "all" for all results, "cor" for correlation coefficients, "n" for the sample sizes, "stat" for the test statistic, "df" for the degrees of freedom, and "p" for p-values. Note that the function does not provide p-values for tetrachoric or polychoric correlation coefficients.

tri

a character string indicating which triangular of the matrix to show on the console, i.e., both for upper and lower triangular, lower (default) for the lower triangular, and upper for the upper triangular.

p.adj

a character string indicating an adjustment method for multiple testing based on p.adjust, i.e., none , bonferroni, holm (default), hochberg, hommel, BH, BY, or fdr.

continuity

logical: if TRUE (default), continuity correction is used for testing Spearman's rank-order correlation coefficient and Kendall's Tau-b correlation.

digits

an integer value indicating the number of decimal places to be used for displaying correlation coefficients.

p.digits

an integer value indicating the number of decimal places to be used for displaying p-values.

as.na

a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis.

write

a character string naming a file for writing the output into either a text file with file extension ".txt" (e.g., "Output.txt") or Excel file with file extention ".xlsx" (e.g., "Output.xlsx"). If the file name does not contain any file extension, an Excel file will be written.

append

logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.

check

logical: if TRUE (default), argument specification is checked.

output

logical: if TRUE (default), output is shown on the console.

Details

Note that unlike the cor.test function, this function does not compute an exact p-value for Spearman's rank-order correlation coefficient or Kendall's Tau-b correlation coefficient, but uses the asymptotic t approximation.

Statistically significant correlation coefficients can be shown in boldface on the console when specifying sig = TRUE. However, this option is not supported when using R Markdown, i.e., the argument sig will switch to FALSE.

Value

Returns an object of class misty.object, which is a list with following entries:

call

function call

type

type of analysis

data

data frame used for the current analysis

args

specification of function arguments

result

list with result tables, i.e., cor for the correlation matrix, n for a matrix with the sample sizes, stat for a matrix with the test statistics, df for a matrix with the degrees of freedom, and p-value for the matrix with the significance values (p-values)

Note

This function uses the polychoric() function in the psych package by William Revelle to estimate tetrachoric and polychoric correlation coefficients.

Author(s)

Takuya Yanagida [e-mail]

References

Rasch, D., Kubinger, K. D., & Yanagida, T. (2011). Statistics in psychology - Using R and SPSS. John Wiley & Sons.

Revelle, W. (2018) psych: Procedures for personality and psychological research. Northwestern University, Evanston, Illinois, USA, https://CRAN.R-project.org/package=psych Version = 1.8.12.

See Also

write.result, cohens.d, effsize, multilevel.icc, na.auxiliary, size.cor.

Examples

# Example 1a: Pearson product-moment correlation coefficient between 'Ozone' and 'Solar.R#
cor.matrix(airquality[, c("Ozone", "Solar.R")])

# Example 1b: Alternative specification using the 'data' argument
cor.matrix(Ozone, Solar.R, data = airquality)

# Example 2a: Pearson product-moment correlation matrix using pairwise deletion
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")])

# Example 2b: Alternative specification using the 'data' argument
cor.matrix(Ozone:Wind, data = airquality)

# Example 3: Spearman's rank-order correlation matrix
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], method = "spearman")

# Example 4: Pearson product-moment correlation matrix
# highlight statistically significant result at alpha = 0.05
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], sig = TRUE)

# Example 5: Pearson product-moment correlation matrix
# highlight statistically significant result at alpha = 0.05
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], sig = TRUE, alpha = 0.10)

# Example 6: Pearson product-moment correlation matrix
# print sample size and significance values
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], print = "all")

# Example 7: Pearson product-moment correlation matrix using listwise deletion,
# print sample size and significance values
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], na.omit = TRUE, print = "all")

# Example 8: Pearson product-moment correlation matrix
# print sample size and significance values with Bonferroni correction
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], na.omit = TRUE,
           print = "all", p.adj = "bonferroni")

# Example 9a: Pearson product-moment correlation matrix for 'mpg', 'cyl', and 'disp'
# results for group "0" and "1" separately
cor.matrix(mtcars[, c("mpg", "cyl", "disp")], group = mtcars$vs)

# Example 9b: Alternative specification using the 'data' argument
cor.matrix(mpg:disp, data = mtcars, group = "vs")

## Not run: 
# Example 10a: Write results into a text file
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], print = "all", write = "Correlation.txt")

# Example 10b: Write results into an Excel file
cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], print = "all", write = "Correlation.xlsx")

result <- cor.matrix(airquality[, c("Ozone", "Solar.R", "Wind")], print = "all", output = FALSE)
write.result(result, "Correlation.xlsx")

## End(Not run)