Skip to contents

Test for Association/Correlation Between Paired Samples

z_cor_test.Rd

[Stable]

Test for association between paired samples, using one of Pearson's product moment correlation coefficient, Kendall's \(\tau\) (tau) or Spearman's \(\rho\) (rho). Unlike the stats version of cor.test, this function allows users to set the null to a value other than zero and perform equivalence testing.

Usage

z_cor_test(
  x,
  y,
  alternative = c("two.sided", "less", "greater", "equivalence", "minimal.effect"),
  method = c("pearson", "kendall", "spearman"),
  alpha = 0.05,
  null = 0,
  se_method = c("analytic", "jackknife")
)

Arguments

x, y

numeric vectors of data values. x and y must have the same length.

alternative

a character string specifying the alternative hypothesis:

  • "two.sided": correlation is not equal to null (default)

  • "greater": correlation is greater than null

  • "less": correlation is less than null

  • "equivalence": correlation is within the equivalence bounds (TOST)

  • "minimal.effect": correlation is outside the equivalence bounds (TOST)

You can specify just the initial letter.

method

a character string indicating which correlation coefficient is to be used for the test. One of "pearson", "kendall", or "spearman", can be abbreviated.

alpha

alpha level (default = 0.05)

null

a number or vector indicating the null hypothesis value(s):

  • For standard tests: a single value (default = 0)

  • For equivalence/minimal effect tests: either a single value (symmetric bounds ±value will be created) or a vector of two values representing the lower and upper bounds

se_method

a character string indicating the method for computing the standard error. One of "analytic" (default) or "jackknife". The jackknife SE is computed on the Fisher z scale using leave-one-out resampling.

Value

A list with class "htest" containing the following components:

  • p.value: the p-value of the test.

  • statistic: the value of the test statistic with a name describing it.

  • parameter: the degrees of freedom or number of observations.

  • conf.int: a confidence interval for the measure of association appropriate to the specified alternative hypothesis.

  • estimate: the estimated measure of association, with name "r", "tau", or "rho" corresponding to the method employed.

  • stderr: a named vector with z.se (standard error on the Fisher z scale, used for inference) and cor.se (delta method SE on the correlation scale, for descriptive purposes). Note that cor.se underestimates true sampling variability as |r| approaches 1.

  • null.value: the value of the association measure under the null hypothesis.

  • alternative: character string indicating the alternative hypothesis.

  • method: a character string indicating how the association was measured.

  • data.name: a character string giving the names of the data.

  • call: the matched call.

Details

This function uses Fisher's z transformation for the correlations. For Spearman's \(\rho\), the Bonett-Wright \(\rho\)-dependent SE formula \(\sqrt{(1 + r^2/2) / (n - 3)}\) is used rather than the fixed 1.06 constant. For Kendall's \(\tau\), Fieller's correction is applied.

The function supports both standard hypothesis testing and equivalence/minimal effect testing:

  • For standard tests (two.sided, less, greater), the function tests whether the correlation differs from the null value (typically 0).

  • For equivalence testing ("equivalence"), it determines whether the correlation falls within the specified bounds, which can be set asymmetrically.

  • For minimal effect testing ("minimal.effect"), it determines whether the correlation falls outside the specified bounds.

When performing equivalence or minimal effect testing:

  • If a single value is provided for null, symmetric bounds ± value will be used

  • If two values are provided for null, they will be used as the lower and upper bounds

When se_method = "jackknife", the standard error is computed via leave-one-out resampling on the Fisher z scale, which can provide better calibration for small samples or non-standard correlation methods. The jackknife SE is used for both the test statistic and the confidence interval.

See vignette("correlations") for more details.

References

Goertzen, J. R., & Cribbie, R. A. (2010). Detecting a lack of association: An equivalence testing approach. British Journal of Mathematical and Statistical Psychology, 63(3), 527-537. https://doi.org/10.1348/000711009X475853, formula page 531.

Bonett, D. G., & Wright, T. A. (2000). Sample size requirements for estimating Pearson, Kendall and Spearman correlations. Psychometrika, 65(1), 23-28.

See also

Other Correlations: boot_cor_test(), corsum_test(), plot_cor(), power_z_cor()

Examples

# Example 1: Standard significance test
x <- c(44.4, 45.9, 41.9, 53.3, 44.7, 44.1, 50.7, 45.2, 60.1)
y <- c( 2.6,  3.1,  2.5,  5.0,  3.6,  4.0,  5.2,  2.8,  3.8)
z_cor_test(x, y, method = "kendall", alternative = "t", null = 0)
#> 
#> 	Kendall's rank correlation tau with approximate SE
#> 
#> data:  x and y
#> z = 1.616, N = 9, p-value = 0.1061
#> alternative hypothesis: true tau is not equal to 0
#> 95 percent confidence interval:
#>  -0.1013291  0.7845858
#> sample estimates:
#>       tau 
#> 0.4444444 
#> 

# Example 2: Minimal effect test
# Testing if correlation is meaningfully different from ±0.2
z_cor_test(x, y, method = "kendall", alternative = "min", null = 0.2)
#> 
#> 	Kendall's rank correlation tau with approximate SE
#> 
#> data:  x and y
#> z = 0.93028, N = 9, p-value = 0.1761
#> alternative hypothesis: minimal.effect
#> null values:
#>  tau  tau 
#>  0.2 -0.2 
#> 90 percent confidence interval:
#>  -0.008520225  0.746069903
#> sample estimates:
#>       tau 
#> 0.4444444 
#> 

# Example 3: Equivalence test with Pearson correlation
# Testing if correlation is equivalent to zero within ±0.3
z_cor_test(x, y, method = "pearson", alternative = "equivalence", null = 0.3)
#> 
#> 	Pearson's product-moment correlation with approximate SE
#> 
#> data:  x and y
#> z = 0.83223, N = 9, p-value = 0.7974
#> alternative hypothesis: equivalence
#> null values:
#> correlation correlation 
#>         0.3        -0.3 
#> 90 percent confidence interval:
#>  -0.02223023  0.86697863
#> sample estimates:
#>         r 
#> 0.5711816 
#> 

# Example 4: Using asymmetric bounds
# Testing if correlation is within bounds of -0.1 and 0.4
z_cor_test(x, y, method = "spearman",
           alternative = "equivalence", null = c(-0.1, 0.4))
#> 
#> 	Spearman's rank correlation rho with approximate SE
#> 
#> data:  x and y
#> z = 0.6077, N = 9, p-value = 0.7283
#> alternative hypothesis: equivalence
#> null values:
#>  rho  rho 
#> -0.1  0.4 
#> 90 percent confidence interval:
#>  -0.03628203  0.89013847
#> sample estimates:
#> rho 
#> 0.6 
#>