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:- Each conditioning block Zi is split into two nearly equal halves ZiA and ZiB.
- The left side is formed as L = cols(X) ∪ cols(Z1A) ∪ ... ∪ cols(ZkA).
- The right side is formed as R = cols(Y) ∪ cols(Z1B) ∪ ... ∪ cols(ZkB).
- The rank of the cross-covariance submatrix Σ_{L,R} is estimated via
RankTests.estimateWilksRank(SimpleMatrix, int[], int[], int, double).
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 byRankTests.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 bysplitSeed) is used for every query. - When
randomizeSplits=true(default), each trial uses a different seed derived fromsplitSeed + trialIndex, allowing the minimum rank over multiple trials to be taken. This reduces sensitivity to unlucky splits for odd-sized blocks.
leftGetsSmallerHalfWhenOdd
flag controls whether the left or right side receives the extra column.
Multiple trials
WhennumTrials > 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. AllIndependenceResult 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 Summary
ConstructorsConstructorDescriptionTrekSeparationBlocksIndependence(BlockSpec blockSpec) Constructs an instance of IndTestBlocksTs using the provided block specification.TrekSeparationBlocksIndependence(BlockSpec blockSpec, RankTester rankTester) Constructs the test with a supplied rank engine.TrekSeparationBlocksIndependence(BlockSpec blockSpec, List<DataSet> imputations) Constructs the test pooled over several imputations of one data set. -
Method Summary
Modifier and TypeMethodDescriptioncheckIndependence(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.doublegetAlpha()Retrieves the significance level (alpha) for the independence test.Retrieves the block specification associated with this instance.getData()Retrieves the data model associated with the current block specification.intRetrieves the effective sample size for the independence test.Returns the rank engine supplied to this test, if any.Retrieves the list of variable nodes associated with this instance.booleanIndicates whether verbose mode is enabled.voidsetAlpha(double alpha) Sets the significance level (alpha) for the independence test.voidsetEffectiveSampleSize(int effectiveSampleSize) Sets the effective sample size for the independence test.voidsetLeftGetsSmallerHalfWhenOdd(boolean flag) If true and |Zi| is odd, left gets floor(|Zi|/2); otherwise left gets ceil(|Zi|/2).voidsetNumTrials(int t) Sets the number of trials for the independence test.voidsetRandomizeSplits(boolean randomize, long seed) Sets whether to randomize the splits and specifies a seed for randomization.voidsetVerbose(boolean verbose) Sets the verbose mode for this instance.Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface IndependenceTest
canBeSubsampled, checkIndependence, determines, getCov, getDataSets, getMissingValueSupport, getSampleSize, getVariable, getVariableNames, indTestSubset, isPValueAProbability, toString
-
Constructor Details
-
TrekSeparationBlocksIndependence
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
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
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
Retrieves the list of variable nodes associated with this instance.- Specified by:
getVariablesin interfaceIndependenceTest- Returns:
- a new list containing the variable nodes.
-
getData
Retrieves the data model associated with the current block specification.- Specified by:
getDatain interfaceIndependenceTest- 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:
isVerbosein interfaceIndependenceTest- Returns:
- true if verbose mode is enabled; false otherwise
-
setVerbose
public void setVerbose(boolean verbose) Sets the verbose mode for this instance.- Specified by:
setVerbosein interfaceIndependenceTest- Parameters:
verbose- True, if so.
-
getAlpha
public double getAlpha()Retrieves the significance level (alpha) for the independence test.- Specified by:
getAlphain interfaceIndependenceTest- 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:
setAlphain interfaceIndependenceTest- Parameters:
alpha- This level.
-
getEffectiveSampleSize
public int getEffectiveSampleSize()Retrieves the effective sample size for the independence test.- Specified by:
getEffectiveSampleSizein interfaceEffectiveSampleSizeSettable- 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:
setEffectiveSampleSizein interfaceEffectiveSampleSizeSettable- 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
Retrieves the block specification associated with this instance.- Specified by:
getBlockSpecin interfaceBlockTest- Returns:
- the BlockSpec instance representing the current block specification.
-
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
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:
checkIndependencein interfaceIndependenceTest- Parameters:
x- the first node being tested for independencey- the second node being tested for independencez- the set of conditioning nodes- Returns:
- an
IndependenceResultobject containing the outcome of the independence test, including whether the two nodes are independent given the conditioning set
-