*! version 2.0.0 19may2026
[Community-contributed] xicor -- Chatterjee's rank correlation

Syntax

xicor
varlist
[if] [in]
[, options]

Description

xicor
estimates Chatterjee's (2021) rank correlation coefficient xi
for all pairs of variables in varlist.

The estimated correlation matrix is not symmetric.
The rows of the matrix represent Xs
and the columns of the matrix represent Ys.
Thus, the correlation coefficient xi(Xi,Yj)
is found in the ith row and jth column.

Ties in the values of varlist are broken randomly.
To reproduce results, set the random-number seed;
see [R] seed.

options

pvalue compute asymptotic two-sided p-values

normalize display normalized xi correlation matrix

symmetric display symmetric xi correlation matrix

rseed(#) set random-number seed to #

format(%fmt) display format; default is format(%8.4f)

Options

pvalue
computes asymptotic two-sided p-values
for testing the xi correlation coefficients against independence.
pvalue
may not be combined with
normalize
or
symmetric.

normalize
displays the normalized xi correlation matrix
proposed by Dalitz et al. (2024).
Each xi correlation coefficient xi(X,Y)
is divided by its upper bound xi(Y,Y).
Normalization generally reduces finite sample bias
but may increase the mean squared error, especially for small xi.
normalize
may not be combined with
pvalue.

symmetric
displays a symmetric xi correlation matrix.
For each pair of variables X and Y,
the reported coefficient is the maximum of xi(X,Y) and xi(Y,X),
where xi() is the xi coefficient.
If
normalize
is also specified,
the normalization is applied before the symmetrization step.
symmetric
may not be combined with
pvalue.

rseed(#)
sets the random-number seed.
rseed(#)
is equivalent to typing

. set seed #

prior to calling xicor; see [R] seed.

format(%fmt)
specifies the format for displaying the individual elements of the matrix.
The default is format(%8.4f).

Example

Setup (see correlate)

. webuse census13

Estimate xi correlation matrix

. xicor mrgrate dvcrate medage

Stored results

xicor stores the following in r():

Scalars

r(N) number of observations

r(xi_coef) raw xi correlation coefficient (last two variables)

Macros

r(rngstate) random-number state used

Matrices

r(xi) xi correlation matrix

r(xi_normalized) normalized xi correlation matrix (normalize only)

r(xi[_normalized]_sym) symmetric (normalized) xi correlation matrix (symmetric only)

r(pvalue) asymptotic two-sided p-values (pvalue only)

r(z) z statistics (pvalue only)

Acknowledgements

R code from
Chatterjee & Holmes (2023)
was helpful for clarifying some details in Chatterjee (2021).

Part of the code is adapted from StataCorp
uniqrows().

A request from Eric Melse on
Statalist
led to this package.

References

Chatterjee, S. (2021). A new coefficient of correlation. Journal of the American Statistical Association, 116(536), 2009--2022. https://doi.org/10.1080/01621459.2020.1758115

Chatterjee, S., & Holmes, S. (2023). XICOR: Robust and generalized correlation coefficients.
https://github.com/spholmes/XICOR, https://CRAN.R-project.org/package=XICOR

Dalitz, C., Arning, J., & Goebbels, S. A. (2024). Simple bias reduction for Chatterjee's correlation. Journal of Statistical Theory and Practice, 18(51), 1--19.
https://doi.org/10.1007/s42519-024-00399-y

Support

Daniel Klein

klein.daniel.81@gmail.com