cor_test {correlation}R Documentation

Correlation test

Description

This function performs a correlation test between two variables. You can easily visualize the result using plot() (see examples here).

Usage

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,
  ranktransform = FALSE,
  winsorize = FALSE,
  verbose = TRUE,
  ...
)

Arguments

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", "spearman" (but see also the robust argument), "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). See below the details section for a description of these indices.

ci

Confidence/Credible Interval level. If "default", then it is set to 0.95 (⁠95%⁠ CI).

bayesian

If TRUE, will run the correlations under a Bayesian framework.

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 BayesFactor::correlationBF function.

bayesian_ci_method, bayesian_test

See arguments in model_parameters() for BayesFactor tests.

include_factors

If TRUE, the factors are kept and eventually converted to numeric or used as random effects (depending of multilevel). If FALSE, factors are removed upfront.

partial

Can be TRUE or "semi" for partial and semi-partial correlations, respectively.

partial_bayesian

If partial correlations under a Bayesian framework are needed, you will also need to set partial_bayesian to TRUE to obtain "full" Bayesian partial correlations. Otherwise, you will obtain pseudo-Bayesian partial correlations (i.e., Bayesian correlation based on frequentist partialization).

multilevel

If TRUE, the factors are included as random factors. Else, if FALSE (default), they are included as fixed effects in the simple regression model.

ranktransform

If TRUE, will rank-transform the variables prior to estimating the correlation, which is one way of making the analysis more resistant to extreme values (outliers). Note that, for instance, a Pearson's correlation on rank-transformed data is equivalent to a Spearman's rank correlation. Thus, using robust=TRUE and method="spearman" is redundant. Nonetheless, it is an easy option to increase the robustness of the correlation as well as flexible way to obtain Bayesian or multilevel Spearman-like rank correlations.

winsorize

Another way of making the correlation more "robust" (i.e., limiting the impact of extreme values). Can be either FALSE or a number between 0 and 1 (e.g., 0.2) that corresponds to the desired threshold. See the winsorize() function for more details.

verbose

Toggle warnings.

...

Additional arguments (e.g., alternative) to be passed to other methods. See stats::cor.test for further details.

Details

Correlation Types

Partial Correlation

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 (note that the remaining continuous variables of the dataset will still be included as fixed effects, similarly to regular partial correlations). The model is a random intercept model, i.e. the multilevel correlation is adjusted for (1 | groupfactor).That said, there is an important difference between using cor_test() and correlation(): If you set multilevel=TRUE in correlation() but partial is set to FALSE (as per default), then a back-transformation from partial to non-partial correlation will be attempted (through pcor_to_cor()). However, this is not possible when using cor_test() so that if you set multilevel=TRUE in it, the resulting correlations are partial one. Note that for Bayesian multilevel correlations, if partial = FALSE, the back transformation will also recompute p-values based on the new r scores, and will drop the Bayes factors (as they are not relevant anymore). To keep Bayesian scores, set partial = TRUE.

Notes

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).

Examples

library(correlation)

cor_test(iris, "Sepal.Length", "Sepal.Width")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "spearman")
## Not run: 
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "kendall")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "biweight")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "distance")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "percentage")

if (require("wdm", quietly = TRUE)) {
  cor_test(iris, "Sepal.Length", "Sepal.Width", method = "blomqvist")
}

if (require("Hmisc", quietly = TRUE)) {
  cor_test(iris, "Sepal.Length", "Sepal.Width", method = "hoeffding")
}
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "gamma")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "gaussian")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "shepherd")
if (require("BayesFactor", quietly = TRUE)) {
  cor_test(iris, "Sepal.Length", "Sepal.Width", bayesian = TRUE)
}

# Robust (these two are equivalent)
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "spearman")
cor_test(iris, "Sepal.Length", "Sepal.Width", method = "pearson", ranktransform = TRUE)

# Winsorized
cor_test(iris, "Sepal.Length", "Sepal.Width", winsorize = 0.2)

# Tetrachoric
if (require("psych", quietly = TRUE) && require("rstanarm", quietly = TRUE)) {
  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")

  # Biserial
  cor_test(data, "Sepal.Width", "Petal.Width_binary", method = "biserial")

  # 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")

  # When one variable is continuous, will run 'polyserial' correlation
  cor_test(data, "Sepal.Width", "Sepal.Length_ordinal", method = "polychoric")
}

# Partial
cor_test(iris, "Sepal.Length", "Sepal.Width", partial = TRUE)
cor_test(iris, "Sepal.Length", "Sepal.Width", multilevel = TRUE)
cor_test(iris, "Sepal.Length", "Sepal.Width", partial_bayesian = TRUE)

## End(Not run)

[Package correlation version 0.8.4 Index]