Class BfciScoreCheck

java.lang.Object
edu.cmu.tetrad.search.BfciScoreCheck
All Implemented Interfaces:
IGraphSearch
public final class BfciScoreCheck extends Object implements IGraphSearch
EXPERIMENTAL: BFCI with a per-removal SCORE CHECK ("tests propose, scores dispose").

This is a self-contained variant of Bfci / StarFci: BOSS supplies the Markov CPDAG, the *-FCI extra-edge-removal machinery runs with per-removal legality gating exactly as in StarFci, and IN ADDITION every gated structural commitment (each single-edge removal in the adjacency-subset and possible-D-SEP passes, and each joint batch in the saturating step) must not decrease a global model score: the BIC of the Gaussian MAG implied by the candidate PAG, with the MAG likelihood maximized by RICF (RicfEjml, Drton & Richardson 2004).

MOTIVATION. In test-driven LV edge removal, an edge is deleted as soon as ANY candidate conditioning set yields non-rejection; the removal decision is a minimum over many tests, so for attenuated latent-path dependencies the probability of harvesting a spurious independence grows with the number of candidate sets, and each false removal feeds sepset-based collider orientation whose errors the FCI rules then propagate. Here a test outcome is demoted to a PROPOSAL: a removal is committed only if the fitted MAG model of the resulting PAG is at least as good, by BIC, as the fitted MAG model of the current graph. A single spurious independence then no longer suffices to delete an edge; the likelihood must agree that the edge is dispensable. Since Markov-equivalent Gaussian MAGs parameterize the same covariance sets, the score is invariant to the arbitrary orientation choices made by GraphTransforms.zhangMagFromPag(Graph), so scoring the Zhang MAG scores the equivalence class.

THE SCORE. bic(G) = 2 * logLik(RICF fit of zhangMagFromPag(G)) - penaltyDiscount * k * ln(n), where k = p (error variances) + #directed + #bidirected edges of the MAG (one parameter per edge), higher is better. A candidate is accepted iff legal (the StarFci certificate, modulo knowledge) AND bic(candidate) >= bic(current). With penaltyDiscount = 1 this acceptance rule is the classical BIC test: a removal that deletes one edge is accepted iff twice the log-likelihood drop is at most ln(n), i.e., iff the data do not insist on the edge.

FAIL-SOFT CONTRACT. The score check requires a covariance matrix (taken from the test, the data, or setCovarianceMatrix(ICovarianceMatrix)) and a MAG with only directed and bidirected edges (RICF does not fit undirected/selection blocks). Whenever the score cannot be computed (no covariance, undirected edges present, RICF failure or non-finite likelihood), the check DEGRADES TO A PASS and the decision falls back to legality alone, i.e., to exact StarFci behavior; this is logged when verbose. The score check applies only on the gated path (doLegalityGating == true, the default): on the ungated path removals are not individually re-oriented, so no per-step implied MAG exists to score, and this class behaves exactly like Bfci there.

All non-score machinery (knowledge handling, the modulo-knowledge legality certificate, the saturating step, the sepset bookkeeping) is copied verbatim from StarFci; the score-check insertions are marked with "SCORE CHECK" comments. This duplication is deliberate: the base class's gate internals are private, and this class is an experimental fork meant to be diffed against it, not a maintained parallel implementation.

Author:
josephramsey, bryanandrews
See Also:

  • Constructor Details

    • BfciScoreCheck

      public BfciScoreCheck(IndependenceTest test, Score score)
      Constructor. The test and score should be for the same data.
      Parameters:
      test - The test to use.
      score - The score to use (for BOSS).
      See Also:

  • Method Details

    • getMarkovDag

      public Graph getMarkovDag(boolean verbose) throws InterruptedException
      Runs BOSS to obtain the Markov CPDAG (as in Bfci).
      Parameters:
      verbose - whether to print progress.
      Returns:
      the Markov CPDAG.
      Throws:
      InterruptedException - if interrupted.

    • sepsetSubsetOfAdjxOrAdjy

      public Set<Node> sepsetSubsetOfAdjxOrAdjy(Graph graph, Node x, Node y, Set<Node> containing, IndependenceTest test, int depth, boolean useMaxP) throws InterruptedException
      Finds a separating set that is a subset of the adjacency of nodes x or y in the input graph. (Verbatim from StarFci.)
      Parameters:
      graph - The graph being analyzed.
      x - The first node between which independence is checked.
      y - The second node between which independence is checked.
      containing - A set of nodes that must be included in the separating set.
      test - The independence test used to evaluate separation.
      depth - The maximum size of subsets to be tested for independence.
      useMaxP - True if the maxP method should be used.
      Returns:
      A separating set (if found), or null.
      Throws:
      InterruptedException - if interrupted.

    • search

      public Graph search() throws InterruptedException
      Runs the search and returns the PAG. Structure identical to StarFci.search(), with the score check applied inside the gated commitments.
      Specified by:
      search in interface IGraphSearch
      Returns:
      This PAG.
      Throws:
      InterruptedException - if any

    • getKnowledge

      public Knowledge getKnowledge()
      Returns the knowledge used in search.
      Returns:
      This knowledge

    • setKnowledge

      public void setKnowledge(Knowledge knowledge)
      Sets the knowledge to use in search.
      Parameters:
      knowledge - This knowledge.

    • setCompleteRuleSetUsed

      public void setCompleteRuleSetUsed(boolean completeRuleSetUsed)
      Sets whether Zhang's complete rules are used.
      Parameters:
      completeRuleSetUsed - set to true if Zhang's complete rule set should be used, false if only R1-R4 (the rule set of the original FCI) should be used. True by default.

    • setMaxDiscriminatingPathLength

      public void setMaxDiscriminatingPathLength(int maxDiscriminatingPathLength)
      Sets the maximum length of any discriminating path.
      Parameters:
      maxDiscriminatingPathLength - the maximum length of any discriminating path, or -1 if unlimited.

    • isVerbose

      public boolean isVerbose()
      Indicates whether verbose output is enabled.
      Returns:
      true if verbose output is enabled, false otherwise.

    • setVerbose

      public void setVerbose(boolean verbose)
      Sets whether verbose output should be printed.
      Parameters:
      verbose - True, if so.

    • getIndependenceTest

      public IndependenceTest getIndependenceTest()
      Returns the independence test used in search.
      Returns:
      This test.

    • setDepth

      public void setDepth(int depth)
      Sets the depth of the search for the possible m-sep search.
      Parameters:
      depth - This depth.

    • setExcludeSelectionBias

      public void setExcludeSelectionBias(boolean excludeSelectionBias)
      Sets whether selection bias should be excluded during the search process.
      Parameters:
      excludeSelectionBias - A boolean indicating whether to exclude selection bias (true) or not (false).

    • setDoLegalityGating

      public void setDoLegalityGating(boolean doLegalityGating)
      Sets whether each candidate removal is gated on per-step PAG legality (true, the default) or handled by the original greedy *-FCI machinery with a post-hoc repair (false). The score check applies only when gating is on.
      Parameters:
      doLegalityGating - Whether to gate each removal.

    • setUsePossibleDsep

      public void setUsePossibleDsep(boolean usePossibleDsep)
      Whether to do the possible d-sep step.
      Parameters:
      usePossibleDsep - Whether to use the possible d-sep step.

    • setLvHeuristicOnly

      public void setLvHeuristicOnly(boolean lvHeuristicOnly)
      A flag indicating whether the LV-Heuristic results should be returned. If false, edges will be removed via further independence testing.
      Parameters:
      lvHeuristicOnly - Whether to return the LV-Heuristic results.

    • setMaxPossibleDsepPathLength

      public void setMaxPossibleDsepPathLength(int maxPossibleDsepPathLength)
      Maximum path length for possible d-sep.
      Parameters:
      maxPossibleDsepPathLength - Maximum path length for possible d-sep.

    • setParallelized

      public void setParallelized(boolean parallelized)
      Sets the parallel processing mode.
      Parameters:
      parallelized - a boolean value indicating whether to enable (true) or disable (false) parallel processing.

    • setUseMaxP

      public void setUseMaxP(boolean useMaxP)
      Sets whether to use the maxP criterion during the sepset search.
      Parameters:
      useMaxP - A boolean indicating whether the maxP criterion should be applied (true) or not (false).

    • setNumStarts

      public void setNumStarts(int numStarts)
      Sets the number of times to restart the BOSS search.
      Parameters:
      numStarts - The number of times to restart the search.

    • setBossUseBes

      public void setBossUseBes(boolean useBes)
      Sets whether the BES should be used in BOSS.
      Parameters:
      useBes - True if the BES should be used, false otherwise.

    • setNumThreads

      public void setNumThreads(int numThreads)
      Sets the number of threads to use in BOSS.
      Parameters:
      numThreads - The number of threads to use. Must be at least 1.

    • setUseScoreCheck

      public void setUseScoreCheck(boolean useScoreCheck)
      Sets whether the RICF-BIC score check is applied to gated commitments. When false this class reduces exactly to Bfci, which is useful for A/B comparisons within the same wrapper. Default true.
      Parameters:
      useScoreCheck - Whether to apply the score check.

    • setScoreCheckPenaltyDiscount

      public void setScoreCheckPenaltyDiscount(double scoreCheckPenaltyDiscount)
      Sets the penalty discount c in the MAG BIC, bic = 2 * logLik - c * k * ln(n). Default 1 (classical BIC). Larger values make the gate MORE willing to remove edges (the parameter saving of a removal counts for more); smaller values make it more conservative.
      Parameters:
      scoreCheckPenaltyDiscount - the penalty discount; must be positive.

    • setCovarianceMatrix

      public void setCovarianceMatrix(ICovarianceMatrix covarianceMatrix)
      Sets the covariance matrix used by the RICF score check. If not set, the covariance is resolved from the independence test (its covariance if it exposes one, else a covariance computed from its continuous data set).
      Parameters:
      covarianceMatrix - the covariance matrix; may be null to force resolution from the test.