This function performs a correlation test between two variables.
cor_test( data, x, y, method = "pearson", ci = 0.95, bayesian = FALSE, bayesian_prior = "medium", bayesian_ci_method = "hdi", bayesian_test = c("pd", "rope", "bf"), include_factors = FALSE, partial = FALSE, partial_bayesian = FALSE, multilevel = FALSE, robust = FALSE, ... )
data | A data frame. |
---|---|
x, y | Names of two variables present in the data. |
method | A character string indicating which correlation coefficient is to be used for the test. One of "pearson" (default), "kendall", or "spearman", "biserial", "polychoric", "tetrachoric", "biweight", "distance", "percentage" (for percentage bend correlation), "blomqvist" (for Blomqvist's coefficient), "hoeffding" (for Hoeffding's D), "gamma", "gaussian" (for Gaussian Rank correlation) or "shepherd" (for Shepherd's Pi correlation). Setting "auto" will attempt at selecting the most relevant method (polychoric when ordinal factors involved, tetrachoric when dichotomous factors involved, point-biserial if one dichotomous and one continuous and pearson otherwise). |
ci | Confidence/Credible Interval level. If "default", then it is set to 0.95 (95% CI). |
bayesian, partial_bayesian | If TRUE, will run the correlations under a Bayesian framework. Note that for partial correlations, you will also need to set |
bayesian_prior | For the prior argument, several named values are recognized: "medium.narrow", "medium", "wide", and "ultrawide". These correspond to scale values of 1/sqrt(27), 1/3, 1/sqrt(3) and 1, respectively. See the |
bayesian_ci_method, bayesian_test | See arguments in |
include_factors | If |
partial | Can be TRUE or "semi" for partial and semi-partial correlations, respectively. |
multilevel | If |
robust | If TRUE, will rank-transform the variables prior to estimating the correlation. Note that, for instance, a Pearson's correlation on rank-transformed data is equivalent to a Spearman's rank correlation. Thus, using |
... | Arguments passed to or from other methods. |
Pearson's correlation: This is the most common correlation method. It corresponds to the covariance of the two variables normalized (i.e., divided) by the product of their standard deviations.
Spearman's rank correlation: A non-parametric measure of rank correlation (statistical dependence between the rankings of two variables). The Spearman correlation between two variables is equal to the Pearson correlation between the rank values of those two variables; while Pearson's correlation assesses linear relationships, Spearman's correlation assesses monotonic relationships (whether linear or not). Confidence Intervals (CI) for Spearman's correlations are computed using the Fieller et al. (1957) correction (see Bishara and Hittner, 2017).
Kendall's rank correlation: In the normal case, the Kendall correlation is preferred than the Spearman correlation because of a smaller gross error sensitivity (GES) and a smaller asymptotic variance (AV), making it more robust and more efficient. However, the interpretation of Kendall's tau is less direct than that of Spearman's rho, in the sense that it quantifies the difference between the % of concordant and discordant pairs among all possible pairwise events. Confidence Intervals (CI) for Kendall's correlations are computed using the Fieller et al. (1957) correction (see Bishara and Hittner, 2017).
Biweight midcorrelation: A measure of similarity that is median-based, instead of the traditional mean-based, thus being less sensitive to outliers. It can be used as a robust alternative to other similarity metrics, such as Pearson correlation (Langfelder \& Horvath, 2012).
Distance correlation: Distance correlation measures both linear and non-linear association between two random variables or random vectors. This is in contrast to Pearson's correlation, which can only detect linear association between two random variables.
Percentage bend correlation: Introduced by Wilcox (1994), it is based on a down-weight of a specified percentage of marginal observations deviating from the median (by default, 20%).
Shepherd's Pi correlation: Equivalent to a Spearman's rank correlation after outliers removal (by means of bootstrapped Mahalanobis distance).
Blomqvist’s coefficient: The Blomqvist’s coefficient (also referred to as Blomqvist's Beta or medial correlation; Blomqvist, 1950) is a median-based non-parametric correlation that has some advantages over measures such as Spearman's or Kendall's estimates (see Shmid and Schimdt, 2006).
Hoeffding’s D: The Hoeffding’s D statisticis a non-parametric rank based measure of association that detects more general departures from independence (Hoeffding 1948), including non-linear associations. Hoeffding’s D varies between -0.5 and 1 (if there are no tied ranks, otherwise it can have lower values), with larger values indicating a stronger relationship between the variables.
Point-Biserial and biserial correlation: Correlation coefficient used when one variable is continuous and the other is dichotomous (binary). Point-Biserial is equivalent to a Pearson's correlation, while Biserial should be used when the binary variable is assumed to have an underlying continuity. For example, anxiety level can be measured on a continuous scale, but can be classified dichotomously as high/low.
Gamma correlation: The Goodman-Kruskal gamma statistic is similar to Kendall's Tau coefficient. It is relatively robust to outliers and deals well with data that have many ties.
Gaussian rank Correlation: The Gaussian rank correlation estimator is a simple and well-performing alternative for robust rank correlations (Boudt et al., 2012). It is based on the Gaussian quantiles of the ranks.
Polychoric correlation: Correlation between two theorised normally distributed continuous latent variables, from two observed ordinal variables.
Tetrachoric correlation: Special case of the polychoric correlation applicable when both observed variables are dichotomous.
Partial correlations are estimated as the correlation between two variables after adjusting for the (linear) effect of one or more other variable.
The correlation test is then run after having partialized the dataset, independently from it. In other words, it considers partialization as an independent step generating a different dataset, rather than belonging to the same model.
This is why some discrepancies are to be expected for the t- and p-values, CIs, BFs etc (but not the correlation coefficient) compared to other implementations (e.g., ppcor
).
(The size of these discrepancies depends on the number of covariates partialled-out and the strength of the linear association between all variables.)
Such partial correlations can be represented as Gaussian Graphical Models (GGM), an increasingly popular tool in psychology. A GGM traditionally include a set of variables depicted as circles ("nodes"), and a set of lines that visualize relationships between them, which thickness represents the strength of association (see Bhushan et al., 2019).
Multilevel correlations are a special case of partial correlations where the variable to be adjusted for is a factor and is included as a random effect in a mixed model.
Kendall and Spearman correlations when bayesian=TRUE
: These are technically Pearson Bayesian correlations of rank transformed data, rather than pure Bayesian rank correlations (which have different priors).
#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------ #> Sepal.Length | Sepal.Width | -0.12 | [-0.27, 0.04] | -1.44 | 148 | 0.152 | Pearson | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "spearman")#> Parameter1 | Parameter2 | rho | 95% CI | S | p | Method | n_Obs #> ----------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.17 | [-0.32, -0.01] | 6.56e+05 | 0.041 | Spearman | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "kendall")#> Parameter1 | Parameter2 | 95% CI | tau | z | p | Method | n_Obs #> ------------------------------------------------------------------------------------ #> Sepal.Length | Sepal.Width | [-0.23, 0.08] | -0.08 | -1.33 | 0.183 | Kendall | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "biweight")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.13 | [-0.29, 0.03] | -1.65 | 148 | 0.101 | Biweight | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "distance")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | 0.08 | [-0.08, 0.24] | 8.43 | 11024 | < .001 | Distance (Bias Corrected) | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "percentage")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> --------------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.19 | [-0.34, -0.03] | -2.39 | 148 | 0.018 | Percentage Bend | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "blomqvist")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> --------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.23 | [-0.37, -0.07] | -2.82 | 148 | 0.005 | Blomqvist | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "hoeffding")#> Parameter1 | Parameter2 | r | df | p | Method | n_Obs #> ------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | 0.01 | 148 | 0.011 | Hoeffding | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "gamma")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ----------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.08 | [-0.24, 0.08] | -0.99 | 148 | 0.325 | Gamma | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "gaussian")#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------------ #> Sepal.Length | Sepal.Width | -0.10 | [-0.26, 0.06] | -1.21 | 148 | 0.229 | Gaussian rank | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "shepherd")#> Parameter1 | Parameter2 | rho | 95% CI | S | p | Method | n_Obs #> ---------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.23 | [-0.38, -0.07] | 6.02e+05 | 0.005 | Shepherd's Pi | 150cor_test(iris, "Sepal.Length", "Sepal.Width", bayesian = TRUE)#>#> Parameter1 | Parameter2 | rho | 95% CI | pd | % in ROPE | BF | Prior | Method | n_Obs #> ------------------------------------------------------------------------------------------------------------------------------ #> Sepal.Length | Sepal.Width | -0.11 | [-0.24, 0.01] | 91.15% | 42.33% | 0.51 | Cauchy (0 +- 0.33) | Bayesian Pearson | 150# Tetrachoric data <- iris data$Sepal.Width_binary <- ifelse(data$Sepal.Width > 3, 1, 0) data$Petal.Width_binary <- ifelse(data$Petal.Width > 1.2, 1, 0) cor_test(data, "Sepal.Width_binary", "Petal.Width_binary", method = "tetrachoric")#> Parameter1 | Parameter2 | rho | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------------------------- #> Sepal.Width_binary | Petal.Width_binary | -0.53 | [-0.63, -0.40] | -7.49 | 148 | < .001 | Tetrachoric | 150# Biserial cor_test(data, "Sepal.Width", "Petal.Width_binary", method = "biserial")#> Parameter1 | Parameter2 | rho | 95% CI | t | df | p | Method | n_Obs #> --------------------------------------------------------------------------------------------------- #> Sepal.Width | Petal.Width_binary | -0.40 | [-0.53, -0.26] | -5.34 | 148 | < .001 | Biserial | 150# Polychoric data$Petal.Width_ordinal <- as.factor(round(data$Petal.Width)) data$Sepal.Length_ordinal <- as.factor(round(data$Sepal.Length)) cor_test(data, "Petal.Width_ordinal", "Sepal.Length_ordinal", method = "polychoric")#> Warning: 1 cells were adjusted for 0 values using the correction for continuity. Examine your data carefully.#> Parameter1 | Parameter2 | rho | 95% CI | t | df | p | Method | n_Obs #> ----------------------------------------------------------------------------------------------------------- #> Petal.Width_ordinal | Sepal.Length_ordinal | 0.53 | [0.40, 0.63] | 7.53 | 148 | < .001 | Polychoric | 150# When one variable is continuous, will run 'polyserial' correlation cor_test(data, "Sepal.Width", "Sepal.Length_ordinal", method = "polychoric")#> Parameter1 | Parameter2 | rho | 95% CI | t | df | p | Method | n_Obs #> ----------------------------------------------------------------------------------------------------- #> Sepal.Width | Sepal.Length_ordinal | -0.14 | [-0.30, 0.02] | -1.76 | 148 | 0.080 | Polyserial | 150# Robust (these two are equivalent) cor_test(iris, "Sepal.Length", "Sepal.Width", method = "pearson", robust = TRUE)#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ------------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.17 | [-0.32, -0.01] | -2.06 | 148 | 0.041 | Pearson | 150cor_test(iris, "Sepal.Length", "Sepal.Width", method = "spearman", robust = FALSE)#> Parameter1 | Parameter2 | rho | 95% CI | S | p | Method | n_Obs #> ----------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | -0.17 | [-0.32, -0.01] | 6.56e+05 | 0.041 | Spearman | 150# Partial cor_test(iris, "Sepal.Length", "Sepal.Width", partial = TRUE)#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ---------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | 0.43 | [0.29, 0.55] | 5.84 | 148 | < .001 | Pearson | 150cor_test(iris, "Sepal.Length", "Sepal.Width", multilevel = TRUE)#>#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ---------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | 0.43 | [0.29, 0.55] | 5.85 | 148 | < .001 | Pearson | 150# \donttest{ cor_test(iris, "Sepal.Length", "Sepal.Width", partial_bayesian = TRUE)#>#> Parameter1 | Parameter2 | r | 95% CI | t | df | p | Method | n_Obs #> ---------------------------------------------------------------------------------------- #> Sepal.Length | Sepal.Width | 0.43 | [0.29, 0.55] | 5.84 | 148 | < .001 | Pearson | 150# }