Class Chi2RankTest

java.lang.Object
edu.cmu.tetrad.search.rlcd.Chi2RankTest
All Implemented Interfaces:
RankTester

public final class Chi2RankTest extends Object implements RankTester
The canonical-correlation chi-square rank test used by RLCD, translated from Chi2RankTest.py in the causal-learn implementation.

For column sets P and Q with canonical correlations ρ_1 ≥ ρ_2 ≥ ... ≥ ρ_m (m = min(|P|, |Q|)), the null hypothesis rank ≤ r is tested with the statistic

    T = [ N − r − (|P| + |Q| + 1)/2 + Σ_{i < r} (1/ρ_i² − 1) ] · Σ_{i ≥ r} −log(1 − ρ_i²)
referred to a chi-square distribution with (|P| − r)(|Q| − r) degrees of freedom. The multiplier is Lawley's correction to Bartlett's approximation; it differs from the plain Bartlett multiplier (N − 1 − (p + q + 1)/2) used in RankTests, so this class is kept separate to reproduce the causal-learn behavior.

The two column sets may overlap. Shared columns produce canonical correlations of exactly 1, which are clamped at 1 − 1e−15 before the logarithm, exactly as in the Python; they always fall among the first r correlations in the way RLCD calls this test, so they never contribute to the statistic.

Canonical correlations are computed from the correlation matrix as the singular values of Σ_PP^{−1/2} Σ_PQ Σ_QQ^{−1/2}, with eigenvalues of the diagonal blocks floored at a small positive value for numerical safety. Results are cached per (P, Q) pair.

Author:
josephramsey (translation)
  • Constructor Summary

    Constructors
    Constructor
    Description
    Chi2RankTest(double[][] corr, int sampleSize, double nScaling)
    Constructs the test from a correlation matrix and a sample size directly, for callers that build the matrix themselves.
    Constructs the test from a data set.
    Chi2RankTest(ICovarianceMatrix cov, double nScaling)
    Constructs the test from a covariance or correlation matrix.
  • Method Summary

    Modifier and Type
    Method
    Description
    double[]
    canonicalCorrelations(int[] pcols, int[] qcols)
    Canonical correlations between the two column sets, in descending order, min(|P|, |Q|) of them, clamped to [0, 1].
    boolean
    failToReject(int[] pcols, int[] qcols, int r, double alpha)
    Tests the null hypothesis that the cross-covariance of columns pcols and qcols has rank at most r.
    int
    Returns the sample size.
    double
    pValue(int[] pcols, int[] qcols, int r)
    The p-value of the rank ≤ r test (not used by RLCD's decision, which compares the statistic with the critical value for numerical robustness, but useful for inspection).
    double
    statistic(int[] pcols, int[] qcols, int r)
    The statistic T of the class comment for the rank ≤ r test, to be referred to a chi-square distribution with (|P| − r)(|Q| − r) degrees of freedom.
    double
    statistic(int[] pcols, int[] qcols, int r, double n)
    The statistic T of the class comment for the rank ≤ r test, with the sample size supplied by the caller in place of the one this test was built with.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • Chi2RankTest

      public Chi2RankTest(DataSet dataSet)
      Constructs the test from a data set. The data are standardized internally (the test depends only on the correlation matrix and the sample size).
      Parameters:
      dataSet - a continuous data set.
    • Chi2RankTest

      public Chi2RankTest(ICovarianceMatrix cov, double nScaling)
      Constructs the test from a covariance or correlation matrix.
      Parameters:
      cov - the matrix (it is converted to a correlation matrix).
      nScaling - a multiplier on the sample size (Python N_scaling; 1.0 is the default).
    • Chi2RankTest

      public Chi2RankTest(double[][] corr, int sampleSize, double nScaling)
      Constructs the test from a correlation matrix and a sample size directly, for callers that build the matrix themselves. TestwiseDeletionRankTest uses this to make one test per column union from the rows complete on that union; the matrix is used as given and is assumed to be a correlation matrix (unit diagonal).
      Parameters:
      corr - the correlation matrix, not copied.
      sampleSize - the number of rows the matrix was computed from.
      nScaling - a multiplier on the sample size; 1.0 is the default.
  • Method Details

    • getSampleSize

      public int getSampleSize()
      Returns the sample size.
      Returns:
      the sample size used in the statistic.
    • failToReject

      public boolean failToReject(int[] pcols, int[] qcols, int r, double alpha)
      Description copied from interface: RankTester
      Tests the null hypothesis that the cross-covariance of columns pcols and qcols has rank at most r.
      Specified by:
      failToReject in interface RankTester
      Parameters:
      pcols - column indices of the first set.
      qcols - column indices of the second set.
      r - the hypothesized maximum rank.
      alpha - the significance level.
      Returns:
      true if the null is NOT rejected (rank deficiency is consistent with the data), false if rejected.
    • statistic

      public double statistic(int[] pcols, int[] qcols, int r)
      The statistic T of the class comment for the rank ≤ r test, to be referred to a chi-square distribution with (|P| − r)(|Q| − r) degrees of freedom. The caller is responsible for those degrees of freedom being positive.
      Parameters:
      pcols - column indices of the first set.
      qcols - column indices of the second set.
      r - the hypothesized maximum rank; 0 ≤ r < min(|P|, |Q|).
      Returns:
      the statistic.
    • statistic

      public double statistic(int[] pcols, int[] qcols, int r, double n)
      The statistic T of the class comment for the rank ≤ r test, with the sample size supplied by the caller in place of the one this test was built with. For a test built on a covariance matrix estimated from incomplete data, the right N differs from query to query; EmCovarianceRankTest supplies it here.
      Parameters:
      pcols - column indices of the first set.
      qcols - column indices of the second set.
      r - the hypothesized maximum rank; 0 ≤ r < min(|P|, |Q|).
      n - the sample size to use in Lawley's multiplier (already scaled, if scaling is wanted).
      Returns:
      the statistic.
    • pValue

      public double pValue(int[] pcols, int[] qcols, int r)
      The p-value of the rank ≤ r test (not used by RLCD's decision, which compares the statistic with the critical value for numerical robustness, but useful for inspection).
      Specified by:
      pValue in interface RankTester
      Parameters:
      pcols - column indices of the first set.
      qcols - column indices of the second set.
      r - the hypothesized maximum rank.
      Returns:
      the p-value, or 0 when the degrees of freedom are not positive.
    • canonicalCorrelations

      public double[] canonicalCorrelations(int[] pcols, int[] qcols)
      Canonical correlations between the two column sets, in descending order, min(|P|, |Q|) of them, clamped to [0, 1].
      Parameters:
      pcols - column indices of the first set.
      qcols - column indices of the second set.
      Returns:
      the canonical correlations.