| Title: | Correlation Estimation for Exchangeable/Symmetrical Variables |
|---|---|
| Description: | We implement a new correlation estimator, CorSym, designed for exchangeable variables, where the ordering of the two values in the pair is arbitrary. This kind of data arises frequently in the study of assortative pairing (for example, income in a couple). The standard Pearson estimator is sensitive to such ordering and can be highly biased when the order is biased (when the first value tends to have lower or higher values than the second value). CorSym gives the same estimate deterministically for all orders within each pair, and estimates the desired correlation without bias (variables must be exchangeable). The package also includes utilities to simulate biased orders and test for order bias. Described in Kennedy and Ochoa (2026) <doi:10.64898/2026.08.22.746446>. |
| Authors: | Alejandro Ochoa [aut, cre] (ORCID: <https://orcid.org/0000-0003-4928-3403>), Gabriel Kennedy [aut] (ORCID: <https://orcid.org/0000-0003-4412-3777>) |
| Maintainer: | Alejandro Ochoa <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 1.0.1 |
| Built: | 2026-09-17 13:50:20 UTC |
| Source: | https://github.com/cran/corsym |
This function calculates CIs based on the Fisher transformation and theory originally derived for Pearson estimator, now validated empirically for CorSym. Only the mean estimates and the sample sizes are needed for these calculations.
add_cor_CI(r, n, alpha = 0.05, ci_offset = 3)add_cor_CI(r, n, alpha = 0.05, ci_offset = 3)
r |
Correlation estimates.
Can be scalar or vector, each non-NA value must be between -1 and 1, inclusive.
Cases with NA |
n |
Sample sizes.
Can be scalar or vector.
If both |
alpha |
The complement of the confidence level (default 0.05 results in 1 - 0.05 = 95% CIs). |
ci_offset |
The amount by which the sample size gets reduced in the variance conversion formula. For Normal data, Pearson should use 3 and CorSym 1.5, but different values may be better for other distributions. |
A matrix with a row for every input (single row if r and n are both scalars, as many rows as the lengths of either r or n otherwise), and three named columns: r repeats the input, and CIL and CIU are the lower and upper CIs.
corsym() and pearson() use this function internally.
# make up values for example # a vector of pre-calculated correlation estimates rs <- c( 0.3, 0.5, 0.9 ) # and sample sizes ns <- c( 10, 100, 1000 ) # calculate CIs for these three cases: out <- add_cor_CI( rs, ns )# make up values for example # a vector of pre-calculated correlation estimates rs <- c( 0.3, 0.5, 0.9 ) # and sample sizes ns <- c( 10, 100, 1000 ) # calculate CIs for these three cases: out <- add_cor_CI( rs, ns )
This function estimates the correlation of two exchangeable variables without bias. The output is deterministic, the same for all orders within individual pairs. Pairs with any missingness are automatically ignored.
corsym(x, y = NULL, alpha = 0.05, ci_offset = 1.5)corsym(x, y = NULL, alpha = 0.05, ci_offset = 1.5)
x |
First vector of variables, or a 2-column matrix with the variables of interest |
y |
Second vector of variables |
alpha |
The complement of the confidence level (default 0.05 results in 1 - 0.05 = 95% CIs). |
ci_offset |
The amount by which the sample size gets reduced in the variance conversion formula. For Normal data, Pearson should use 3 and CorSym 1.5, but different values may be better for other distributions. |
A vector with three values: the CorSym correlation estimate between x and y, and the lower and upper CIs.
# generate some random independent data, just for example n <- 53 x <- rnorm( n ) y <- rnorm( n ) # calculate CorSym correlation with CIs corsym( x, y )# generate some random independent data, just for example n <- 53 x <- rnorm( n ) y <- rnorm( n ) # calculate CorSym correlation with CIs corsym( x, y )
This function performs a test for whether data is appearing in a biased order or not.
The test calculates a two-sided Binomial p-value under the null hypothesis that the true frequency of the counted order is f0 (0.5 by default).
order_bias_test(data, f0 = 0.5)order_bias_test(data, f0 = 0.5)
data |
A data.frame (including tibble) with at least two columns: |
f0 |
The expected frequency of pairs in the given order, under the null hypothesis. |
The input data frame with two more columns: f is the sample order frequency (equal to x/n), and pval the two-sided Binomial p-value.
# toy data used in the test data <- data.frame( n = c( 30, 50, 100 ), x = c( 12, 20, 13 ) ) # add frequencies and p-values! data <- order_bias_test( data )# toy data used in the test data <- data.frame( n = c( 30, 50, 100 ), x = c( 12, 20, 13 ) ) # add frequencies and p-values! data <- order_bias_test( data )
This function reorders a proportion of rows so values appear in increasing order.
partial_order(X, q = 1)partial_order(X, q = 1)
X |
Matrix of data. |
q |
Proportion of rows to force to have extreme order (sorted in increasing order). |
The input matrix with a random proportion q of rows sorted in increasing order, the rest equals the input data.
# dummy independent data in random order X <- matrix( rnorm( 20 ), nrow = 10, ncol = 2 ) # same data but in extreme order by default X_extreme <- partial_order( X ) # apply a partial ordering X_partial <- partial_order( X, 0.5 )# dummy independent data in random order X <- matrix( rnorm( 20 ), nrow = 10, ncol = 2 ) # same data but in extreme order by default X_extreme <- partial_order( X ) # apply a partial ordering X_partial <- partial_order( X, 0.5 )
This function is a simple wrapper around stats::cor() with the same interface and missingness handling of corsym(), particularly it adds CIs to the estimates.
Pairs with any missingness are automatically ignored (matching stats::cor() with non-default option use = 'complete.obs').
Also, unlike stats::cor(), this function accepts only two variables as inputs and does not calculate correlation matrices, just the correlation between the two variables.
Pearson is included in this package to contrast to corsym() in handling exchangeable variables.
pearson(x, y = NULL, alpha = 0.05, ci_offset = 3)pearson(x, y = NULL, alpha = 0.05, ci_offset = 3)
x |
First vector of variables, or a 2-column matrix with the variables of interest |
y |
Second vector of variables |
alpha |
The complement of the confidence level (default 0.05 results in 1 - 0.05 = 95% CIs). |
ci_offset |
The amount by which the sample size gets reduced in the variance conversion formula. For Normal data, Pearson should use 3 and CorSym 1.5, but different values may be better for other distributions. |
A vector with three values: the Pearson correlation estimate between x and y, and the lower and upper CIs.
# generate some random independent data, just for example n <- 53 x <- rnorm( n ) y <- rnorm( n ) # calculate Pearson correlation with CIs pearson( x, y )# generate some random independent data, just for example n <- 53 x <- rnorm( n ) y <- rnorm( n ) # calculate Pearson correlation with CIs pearson( x, y )
This function shuffles the values in each row, so they appear in a random order.
randomize_order(X)randomize_order(X)
X |
Matrix of data. |
The matrix with randomized rows.
# dummy data in order X <- matrix( 1:20, nrow = 10, ncol = 2, byrow = TRUE ) # same data but with each row in random order X_randomized <- randomize_order( X )# dummy data in order X <- matrix( 1:20, nrow = 10, ncol = 2, byrow = TRUE ) # same data but with each row in random order X_randomized <- randomize_order( X )