Skip to contents

Correlation analyses

Source: R/corr-test.R
corr_test.Rd

Parametric, non-parametric, robust, and Bayesian correlation test.

Usage

corr_test(
  data,
  x,
  y,
  type = "parametric",
  digits = 2L,
  conf.level = 0.95,
  tr = 0.2,
  bf.prior = 0.707,
  ...
)

Arguments

data

A data frame (or a tibble) from which variables specified are to be taken. Other data types (e.g., matrix,table, array, etc.) will not be accepted. Additionally, grouped data frames from {dplyr} should be ungrouped before they are entered as data.

x

The column in data containing the explanatory variable to be plotted on the x-axis.

y

The column in data containing the response (outcome) variable to be plotted on the y-axis.

type

A character specifying the type of statistical approach:

  • "parametric"

  • "nonparametric"

  • "robust"

  • "bayes"

You can specify just the initial letter.

digits

Number of digits for rounding or significant figures. May also be "signif" to return significant figures or "scientific" to return scientific notation. Control the number of digits by adding the value as suffix, e.g. digits = "scientific4" to have scientific notation with 4 decimal places, or digits = "signif5" for 5 significant figures (see also signif()).

conf.level

Scalar between 0 and 1 (default: 95% confidence/credible intervals, 0.95). If NULL, no confidence intervals will be computed.

tr

Trim level for the mean when carrying out robust tests. In case of an error, try reducing the value of tr, which is by default set to 0.2. Lowering the value might help.

bf.prior

A number between 0.5 and 2 (default 0.707), the prior width to use in calculating Bayes factors and posterior estimates. In addition to numeric arguments, several named values are also recognized: "medium", "wide", and "ultrawide", corresponding to r scale values of 1/2, sqrt(2)/2, and 1, respectively. In case of an ANOVA, this value corresponds to scale for fixed effects.

...

Additional arguments (currently ignored).

Value

The returned object is a tibble data frame with the additional class "statsExpressions". The exact set of columns depends on the test and, for functions that accept a type argument, on the chosen analysis (parametric, non-parametric, robust, or Bayesian). Any given call therefore returns some (not all) of the columns below.

Hypothesis testing

  • statistic: the numeric value of a statistic

  • df: the numeric value of a parameter being modeled (often degrees of freedom for the test)

  • df.error and df: relevant only if the statistic in question has two degrees of freedom (e.g. anova)

  • p.value: the two-sided p-value associated with the observed statistic

  • method: the name of the inferential statistical test

Effect size estimation

  • effectsize: the name of the effect size

  • estimate: estimated value of the effect size

  • conf.level: the coverage level of the confidence/credible interval (e.g. 0.95); the interval itself spans conf.low to conf.high

  • conf.low: lower bound for the effect size estimate

  • conf.high: upper bound for the effect size estimate

  • conf.method: method used to compute the confidence/credible interval

  • conf.distribution: statistical distribution for the effect

Bayesian analysis (only when type = "bayes")

  • bf10: Bayes factor for the alternative hypothesis relative to the null

  • log_e_bf10: natural logarithm of the Bayes factor (present for most, but not all, Bayesian analyses)

  • prior.distribution, prior.scale, prior.location: prior specification used to compute the Bayes factor and posterior estimates

Pairwise comparisons (for pairwise_comparisons() and pairwise_contingency_table())

  • group1, group2: the two levels being compared

  • p.adjust.method: the adjustment method used for multiple comparisons

  • p.value.adj: the adjusted p-value; returned by pairwise_contingency_table(). Note that pairwise_comparisons() instead folds the adjusted value into p.value (and does not return a separate p.value.adj column)

Common columns

  • n.obs: number of observations

  • expression: a list-column of pre-formatted plotmath expressions; each element is a language object (not a character string) containing the statistical details, ready to be used in {ggplot2} (e.g. in labs() or annotate())

For a per-function, column-by-column breakdown of the output (and an explanation of the internal add_expression_col() engine that builds the expression column), see the Return value schema article. For more examples, see the data frame output vignette.

Correlation analyses

The table below provides summary about:

  • statistical test carried out for inferential statistics

  • type of effect size estimate and a measure of uncertainty for this estimate

  • functions used internally to compute these details

Hypothesis testing and Effect size estimation

TypeTestCI available?Function used
ParametricPearson's correlation coefficientYescorrelation::correlation()
Non-parametricSpearman's rank correlation coefficientYescorrelation::correlation()
RobustWinsorized Pearson's correlation coefficientYescorrelation::correlation()
BayesianBayesian Pearson's correlation coefficientYescorrelation::correlation()

Citation

Patil, I., (2021). statsExpressions: R Package for Tidy Dataframes and Expressions with Statistical Details. Journal of Open Source Software, 6(61), 3236, https://doi.org/10.21105/joss.03236

Examples

# for reproducibility
set.seed(123)

# ----------------------- parametric -----------------------

corr_test(mtcars, wt, mpg, type = "parametric")
#> # A tibble: 1 × 14
#>   parameter1 parameter2 effectsize          estimate conf.level conf.low
#>   <chr>      <chr>      <chr>                  <dbl>      <dbl>    <dbl>
#> 1 wt         mpg        Pearson correlation   -0.868       0.95   -0.934
#>   conf.high statistic df.error  p.value method              n.obs conf.method
#>       <dbl>     <dbl>    <int>    <dbl> <chr>               <int> <chr>      
#> 1    -0.744     -9.56       30 1.29e-10 Pearson correlation    32 normal     
#>   expression
#>   <list>    
#> 1 <language>

# ----------------------- non-parametric -------------------

corr_test(mtcars, wt, mpg, type = "nonparametric")
#> # A tibble: 1 × 13
#>   parameter1 parameter2 effectsize           estimate conf.level conf.low
#>   <chr>      <chr>      <chr>                   <dbl>      <dbl>    <dbl>
#> 1 wt         mpg        Spearman correlation   -0.886       0.95   -0.945
#>   conf.high statistic  p.value method               n.obs conf.method expression
#>       <dbl>     <dbl>    <dbl> <chr>                <int> <chr>       <list>    
#> 1    -0.774    10292. 1.49e-11 Spearman correlation    32 normal      <language>

# ----------------------- robust ---------------------------

corr_test(mtcars, wt, mpg, type = "robust")
#> # A tibble: 1 × 14
#>   parameter1 parameter2 effectsize                     estimate conf.level
#>   <chr>      <chr>      <chr>                             <dbl>      <dbl>
#> 1 wt         mpg        Winsorized Pearson correlation   -0.864       0.95
#>   conf.low conf.high statistic df.error  p.value method                        
#>      <dbl>     <dbl>     <dbl>    <int>    <dbl> <chr>                         
#> 1   -0.932    -0.738     -9.41       30 1.84e-10 Winsorized Pearson correlation
#>   n.obs conf.method expression
#>   <int> <chr>       <list>    
#> 1    32 normal      <language>

# ----------------------- Bayesian -------------------------

corr_test(mtcars, wt, mpg, type = "bayes")
#> # A tibble: 1 × 17
#>   parameter1 parameter2 effectsize                   estimate conf.level
#>   <chr>      <chr>      <chr>                           <dbl>      <dbl>
#> 1 wt         mpg        Bayesian Pearson correlation   -0.843       0.95
#>   conf.low conf.high    pd rope.percentage prior.distribution prior.location
#>      <dbl>     <dbl> <dbl>           <dbl> <chr>                       <dbl>
#> 1   -0.934    -0.734     1               0 beta                         1.41
#>   prior.scale      bf10 method                       n.obs conf.method
#>         <dbl>     <dbl> <chr>                        <int> <chr>      
#> 1        1.41 56223033. Bayesian Pearson correlation    32 HDI        
#>   expression
#>   <list>    
#> 1 <language>