Class StratifiedPermutationRankTest

java.lang.Object

edu.cmu.tetrad.util.StratifiedPermutationRankTest

public final class StratifiedPermutationRankTest
extends Object

The permutation form of the stratified (domain-pooled) rank test, after Theorem 5 of Dong, Dai, Ng, Spirtes, and Zhang (ICML 2026). Unlike the likelihood-ratio form in StratifiedRankTests, whose chi-square reference assumes joint Gaussianity within each domain, this test estimates the null distribution of the pooled statistic by permutation, within each domain separately, and so does not assume Gaussianity.

The scheme, for the null that the cross-covariance of X and Y given Z has rank at most r within every domain: within each domain, X and Y are first residualized on Z; the canonical variates of the residuals are computed once; under the null the trailing variates (those past the first r) of the two sides share no sources and are asymptotically independent within the domain, so permuting the rows of one side's trailing block resamples the null. The pooled statistic -- the Bartlett term summed over domains -- is recomputed under random permutations, drawn independently per domain, and the p-value is the fraction of permuted statistics at least as large as the observed one, with the usual add-one correction.

The exchangeability of the trailing variates is an asymptotic property (Dong et al. prove it for their model class under rank faithfulness), so this is an asymptotically valid test, not an exact finite-sample one. Domains too small to discriminate are skipped from both the observed and the permuted sums. If no domain is usable the p-value is NaN. Each call costs roughly the number of permutations times the cost of the likelihood-ratio test, so inside a search this test is slow; it is a robustness check for badly non-Gaussian data, not a routine default.

Author:

josephramsey

Constructor Summary

Constructors

Constructor	Description
StratifiedPermutationRankTest(List<DataSet> dataSets)	Constructs the test from one continuous data set per domain, all with the same variables in the same order.

Method Summary

Modifier and Type	Method	Description
double	pValueRankLe(int[] xRaw, int[] yRaw, int[] z, int r, int numPermutations)	The permutation p-value for the null that the cross-covariance of X and Y given Z has rank at most r within every domain.
void	setSeed(long seed)	Sets the seed for the permutation stream.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

StratifiedPermutationRankTest

public StratifiedPermutationRankTest(List<DataSet> dataSets)

Constructs the test from one continuous data set per domain, all with the same variables in the same order.

Parameters:

dataSets - one continuous data set per domain.

Method Details

setSeed

public void setSeed(long seed)

Sets the seed for the permutation stream.

Parameters:

seed - the seed.

pValueRankLe

public double pValueRankLe(int[] xRaw,
 int[] yRaw,
 int[] z,
 int r,
 int numPermutations)

The permutation p-value for the null that the cross-covariance of X and Y given Z has rank at most r within every domain. Z is removed from X and Y first.

Parameters:

xRaw - column indices of the first set.

yRaw - column indices of the second set.

z - column indices of the conditioning set; may be empty.

r - the rank bound under the null, with 0 ≤ r < min(|x|, |y|) after removal of Z.

numPermutations - the number of permutations; 99 or 199 are reasonable choices.

Returns:

the p-value, or NaN if no domain is large enough to contribute, or 1.0 if either set is empty after removal of Z.