Class TrekSeparationBlocksIndependence

java.lang.Object
edu.cmu.tetrad.search.test.TrekSeparationBlocksIndependence
All Implemented Interfaces:
BlockTest, IndependenceTest, EffectiveSampleSizeSettable

public class TrekSeparationBlocksIndependence extends Object implements IndependenceTest, EffectiveSampleSizeSettable, BlockTest
A block-level conditional independence test based on trek separation, operating under linear latent factor measurement models. This class implements the Trek Separation Blocks Independence (TSBI) test, elaborating on the IndTestTrekSep class of Adam Brodie and Peter Spirtes.

Setting

Variables are organized into blocks, where each block corresponds to a set of observed indicator variables that measure a common latent factor. The independence test operates at the block level: X, Y, and the conditioning set Z = {Z1, ..., Zk} are each a block (latent factor), and the test assesses whether the latent factor behind X is independent of the latent factor behind Y given the latent factors behind Z1, ..., Zk.

Test logic

The test is based on the rank of the cross-covariance matrix between two constructed variable sets L and R:
  1. Each conditioning block Zi is split into two nearly equal halves ZiA and ZiB.
  2. The left side is formed as L = cols(X) ∪ cols(Z1A) ∪ ... ∪ cols(ZkA).
  3. The right side is formed as R = cols(Y) ∪ cols(Z1B) ∪ ... ∪ cols(ZkB).
  4. The rank of the cross-covariance submatrix Σ_{L,R} is estimated via RankTests.estimateWilksRank(SimpleMatrix, int[], int[], int, double).
Under a linear measurement model with k conditioning latent factors, trek separation implies that X ⊥ Y | Z1,...,Zk if and only if:
  rank(Σ_{L,R}) = sum of ranks(Zi)
where the rank of each Zi block is specified externally via BlockSpec.ranks(). The test declares independence when the estimated rank equals this target sum. The p-value reported with each result is that of the hypothesis that the rank is at most the target, so that callers choosing among conditioning sets by p-value (max-p) can do so.

Rank engines

By default the rank is estimated from the correlation matrix of the block specification's data set by RankTests.estimateWilksRank(SimpleMatrix, int[], int[], int, double) (Bartlett's chi-square approximation to Wilks' lambda) at the effective sample size. Alternatively a RankTester may be supplied, in which case the rank is the smallest r whose test of rank at most r is not rejected at alpha, and the p-value comes from the tester. This is how the test is pooled over multiple imputations of one data set: TrekSeparationBlocksIndependence(BlockSpec, List) builds a PooledRankTest, which computes the rank statistic on every imputation and combines them by the rule of Li, Meng, Raghunathan, and Rubin (1991), so that disagreement among the imputations counts against rejecting. The effective sample size is not used by a supplied tester, which has its own.

Splitting strategy

Each conditioning block Zi is split either deterministically or randomly:
  • When randomizeSplits=false, the same fixed split (determined by splitSeed) is used for every query.
  • When randomizeSplits=true (default), each trial uses a different seed derived from splitSeed + trialIndex, allowing the minimum rank over multiple trials to be taken. This reduces sensitivity to unlucky splits for odd-sized blocks.
When a block has an odd number of indicators, the leftGetsSmallerHalfWhenOdd flag controls whether the left or right side receives the extra column.

Multiple trials

When numTrials > 1 and randomizeSplits=true, the test runs the full rank estimation procedure numTrials times with different random splits and takes the minimum estimated rank. This provides a more conservative (less likely to falsely declare dependence) result when block sizes are small.

Caching

Rank estimates are cached in a thread-safe LRU cache keyed by the left and right column sets together with all hyperparameters that affect the rank estimate (sample size, alpha, seed, randomize flag, and number of trials). The cache holds up to 400000 entries.

P-values

This test does not produce p-values. All IndependenceResult objects returned carry NaN for both the p-value and the alpha-minus-p fields. The independence decision is made purely by comparing the estimated rank to the target rank.
See Also:
  • Constructor Details

    • TrekSeparationBlocksIndependence

      public TrekSeparationBlocksIndependence(BlockSpec blockSpec)
      Constructs an instance of IndTestBlocksTs using the provided block specification. Validates the input and initializes various internal properties required for the block-based independence test, including correlation matrix computation, variable mapping, and block configuration. Throws an exception if invalid configurations are detected.
      Parameters:
      blockSpec - the block specification used for setting up the test. Contains information about the data set, variables, and blocks. Must not be null.
      Throws:
      IllegalArgumentException - if blockSpec is null or contains invalid configurations such as duplicate nodes, null variables, or invalid block column references.
    • TrekSeparationBlocksIndependence

      public TrekSeparationBlocksIndependence(BlockSpec blockSpec, List<DataSet> imputations)
      Constructs the test pooled over several imputations of one data set. The block specification's data set gives the variables and blocks; the rank statistic of each query is computed on every imputation and combined (see the class description).
      Parameters:
      blockSpec - the block specification; its data set must have the same variables as the imputations.
      imputations - the imputed data sets, at least one.
    • TrekSeparationBlocksIndependence

      public TrekSeparationBlocksIndependence(BlockSpec blockSpec, RankTester rankTester)
      Constructs the test with a supplied rank engine.
      Parameters:
      blockSpec - the block specification.
      rankTester - the rank test over the columns of the block specification's data set, or null for the default engine (Bartlett's Wilks test on the correlation matrix at the effective sample size).
  • Method Details

    • getVariables

      public List<Node> getVariables()
      Retrieves the list of variable nodes associated with this instance.
      Specified by:
      getVariables in interface IndependenceTest
      Returns:
      a new list containing the variable nodes.
    • getData

      public DataModel getData()
      Retrieves the data model associated with the current block specification.
      Specified by:
      getData in interface IndependenceTest
      Returns:
      the DataModel instance representing the data set associated with this block specification
    • isVerbose

      public boolean isVerbose()
      Indicates whether verbose mode is enabled.
      Specified by:
      isVerbose in interface IndependenceTest
      Returns:
      true if verbose mode is enabled; false otherwise
    • setVerbose

      public void setVerbose(boolean verbose)
      Sets the verbose mode for this instance.
      Specified by:
      setVerbose in interface IndependenceTest
      Parameters:
      verbose - True, if so.
    • getAlpha

      public double getAlpha()
      Retrieves the significance level (alpha) for the independence test.
      Specified by:
      getAlpha in interface IndependenceTest
      Returns:
      the significance level (alpha) for the independence test
    • setAlpha

      public void setAlpha(double alpha)
      Sets the significance level (alpha) for the independence test.
      Specified by:
      setAlpha in interface IndependenceTest
      Parameters:
      alpha - This level.
    • getEffectiveSampleSize

      public int getEffectiveSampleSize()
      Retrieves the effective sample size for the independence test.
      Specified by:
      getEffectiveSampleSize in interface EffectiveSampleSizeSettable
      Returns:
      the effective sample size for the independence test
    • setEffectiveSampleSize

      public void setEffectiveSampleSize(int effectiveSampleSize)
      Sets the effective sample size for the independence test.
      Specified by:
      setEffectiveSampleSize in interface EffectiveSampleSizeSettable
      Parameters:
      effectiveSampleSize - the effective sample size
    • setRandomizeSplits

      public void setRandomizeSplits(boolean randomize, long seed)
      Sets whether to randomize the splits and specifies a seed for randomization.
      Parameters:
      randomize - a boolean indicating whether the splits should be randomized.
      seed - a long value specifying the seed for randomization.
    • setNumTrials

      public void setNumTrials(int t)
      Sets the number of trials for the independence test.
      Parameters:
      t - the number of trials
    • setLeftGetsSmallerHalfWhenOdd

      public void setLeftGetsSmallerHalfWhenOdd(boolean flag)
      If true and |Zi| is odd, left gets floor(|Zi|/2); otherwise left gets ceil(|Zi|/2).
      Parameters:
      flag - a boolean indicating whether to use the smaller half when |Zi| is odd
    • getBlockSpec

      public BlockSpec getBlockSpec()
      Retrieves the block specification associated with this instance.
      Specified by:
      getBlockSpec in interface BlockTest
      Returns:
      the BlockSpec instance representing the current block specification.
    • getRankTester

      public RankTester getRankTester()
      Returns the rank engine supplied to this test, if any.
      Returns:
      the supplied rank engine, or null when the default engine is in use.
    • checkIndependence

      public IndependenceResult checkIndependence(Node x, Node y, Set<Node> z)
      Evaluates whether two nodes (variables) are independent given a set of conditioning nodes using a block-based conditional independence test. The method uses ranks to determine independence, with the process involving random splits and trials to enhance reliability.
      Specified by:
      checkIndependence in interface IndependenceTest
      Parameters:
      x - the first node being tested for independence
      y - the second node being tested for independence
      z - the set of conditioning nodes
      Returns:
      an IndependenceResult object containing the outcome of the independence test, including whether the two nodes are independent given the conditioning set