Package edu.cmu.tetrad.search

Class Fci

java.lang.Object
edu.cmu.tetrad.search.Fci
All Implemented Interfaces:
IGraphSearch
public final class Fci extends Object implements IGraphSearch
The Fci class implements the Fast Causal Inference (FCI) algorithm for discovering causal structures from data. It supports various configurations and rule sets for orienting edges in a partially directed acyclic graph (PDAG) or a completed partially directed acyclic graph (CPDAG).

It provides methods for running searches, configuring the search process, and managing the independence test, variable filtering, depth settings, and other algorithm-specific options.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Fci.ColliderRule
    The ColliderRule enum defines the rules or strategies used to handle collider structures in causal inference or related algorithms.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Fci(IndependenceTest test)
    Constructs an instance of the Fci algorithm using the specified independence test.
    Fci(IndependenceTest test, List<Node> searchVars)
    Constructs an instance of the Fci algorithm using the specified independence test and a subset of variables to include in the search.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    getElapsedTime()
    Returns the elapsed time recorded by the algorithm or process.
    Knowledge
    getKnowledge()
    Retrieves the knowledge structure maintained by this instance.
    SepsetMap
    getSepsets()
    Returns the sepset map maintained by this instance of the FCI algorithm.
    IndependenceTest
    getTest()
    Retrieves the IndependenceTest instance.
    Graph
    search()
    Searches and retrieves a graph using the specified algorithm.
    Graph
    search(IFas fas)
    Executes the search process using the provided `IFas` implementation and performs various graph orientation and refinement steps based on the FCI algorithm.
    void
    setCompleteRuleSetUsed(boolean completeRuleSetUsed)
    Configures whether the complete rule set is used in the FCI algorithm during the causal discovery process.
    void
    setDepth(int depth)
    Sets the maximum depth for the algorithm's search process.
    void
    setDoPossibleDsep(boolean doPossibleDsep)
    Configures whether the possible-DSEP (Definite Separation) step is performed as part of the FCI algorithm during the causal discovery process.
    void
    setGuaranteePag(boolean guaranteePag)
    Sets the value of the guaranteePag flag.
    void
    setKnowledge(Knowledge knowledge)
    Sets the knowledge structure to be used or modified by the algorithm.
    void
    setLogMaxPTies(boolean enabled)
    Configures whether logging is enabled for ties in the MAX-P condition during the FCI algorithm's causal discovery process.
    void
    setLogStream(PrintStream out)
    Sets the log stream for capturing output messages of the algorithm's execution.
    void
    setMaxDiscriminatingPathLength(int maxDiscriminatingPathLength)
    Sets the maximum discriminating path length for the algorithm or process.
    void
    setMaxPDepthStratified(boolean enabled)
    Configures whether the depth-specific stratification of the MAX-P condition is enabled during the FCI algorithm's causal discovery process.
    void
    setMaxPGlobalOrder(boolean enabled)
    Configures whether the global MAX-P order is enabled to avoid order dependence during the causal discovery process in the FCI algorithm.
    void
    setMaxPMargin(double margin)
    Sets the maximum probability margin (max-P margin) to be used in the FCI algorithm during the causal discovery process.
    void
    setR0ColliderRule(Fci.ColliderRule rule)
    Configures the R0 collider rule to be used in the FCI algorithm.
    void
    setReplicatingGraph(boolean replicatingGraph)
    Sets the state of the replicatingGraph flag.
    void
    setStable(boolean stable)
    Sets the stability status.
    void
    setTest(IndependenceTest test)
    Sets the independence test for the current object.
    void
    setVerbose(boolean verbose)
    Sets the verbosity level for the system.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Fci

      public Fci(IndependenceTest test)
      Constructs an instance of the Fci algorithm using the specified independence test.
      Parameters:
      test - An IndependenceTest instance used to evaluate conditional independence among variables in the search. This cannot be null.
      Throws:
      NullPointerException - If the provided test is null.

    • Fci

      public Fci(IndependenceTest test, List<Node> searchVars)
      Constructs an instance of the Fci algorithm using the specified independence test and a subset of variables to include in the search.
      Parameters:
      test - An IndependenceTest instance used to evaluate conditional independence among variables in the search. This cannot be null.
      searchVars - A list of Node objects specifying the subset of variables to include in the search. Only variables from this list will be considered. Variables not in this subset are removed from the internal variable set.
      Throws:
      NullPointerException - If the provided test is null.

  • Method Details

    • setR0ColliderRule

      public void setR0ColliderRule(Fci.ColliderRule rule)
      Configures the R0 collider rule to be used in the FCI algorithm. The R0 collider rule determines how potential colliders are oriented during the causal discovery process. If the provided rule is null, the default rule ColliderRule.SEPSETS will be used.
      Parameters:
      rule - The Fci.ColliderRule option to specify the R0 collider rule. Possible values include ColliderRule.SEPSETS, ColliderRule.CONSERVATIVE, and ColliderRule.MAX_P. A null value will default to ColliderRule.SEPSETS.

    • setMaxPGlobalOrder

      public void setMaxPGlobalOrder(boolean enabled)
      Configures whether the global MAX-P order is enabled to avoid order dependence during the causal discovery process in the FCI algorithm.
      Parameters:
      enabled - A boolean value to enable or disable the global MAX-P order. If true, the global MAX-P order is enforced; otherwise, it is not.

    • setMaxPDepthStratified

      public void setMaxPDepthStratified(boolean enabled)
      Configures whether the depth-specific stratification of the MAX-P condition is enabled during the FCI algorithm's causal discovery process. This setting influences how null hypotheses are evaluated based on conditional independence at varying depths.
      Parameters:
      enabled - A boolean value indicating whether to enable the depth-specific stratification of the MAX-P condition. If true, depth-specific stratification is enforced; otherwise, it is not.

    • setMaxPMargin

      public void setMaxPMargin(double margin)
      Sets the maximum probability margin (max-P margin) to be used in the FCI algorithm during the causal discovery process. This margin determines the threshold for probability-based decisions in conditional independence evaluations. If a negative value is provided, it will be reset to 0.0.
      Parameters:
      margin - A double value representing the maximum probability margin to set. If negative, the margin will default to 0.0.

    • setLogMaxPTies

      public void setLogMaxPTies(boolean enabled)
      Configures whether logging is enabled for ties in the MAX-P condition during the FCI algorithm's causal discovery process. This setting primarily controls the output of informational logs when ties occur in conditional independence evaluations.
      Parameters:
      enabled - A boolean value indicating whether to enable or disable logging for MAX-P condition ties. If true, logging is enabled; otherwise, it is not.

    • setLogStream

      public void setLogStream(PrintStream out)
      Sets the log stream for capturing output messages of the algorithm's execution. This stream allows logging information to be directed to a specified PrintStream instance.
      Parameters:
      out - A PrintStream object representing the output stream to which logs will be written. Accepts System.out, System.err, or any other PrintStream. Can be set to null to disable logging.

    • setDepth

      public void setDepth(int depth)
      Sets the maximum depth for the algorithm's search process. The depth controls the maximum number of edges that can be traversed when determining conditional independence relations. A depth of -1 indicates no limit on the depth, while non-negative values specify explicit limitations. Attempts to set a depth less than -1 result in an IllegalArgumentException.
      Parameters:
      depth - An integer specifying the maximum depth. Must be -1 (unlimited) or a non-negative value (≥ 0).
      Throws:
      IllegalArgumentException - If the provided depth is less than -1.

    • getElapsedTime

      public long getElapsedTime()
      Returns the elapsed time recorded by the algorithm or process.
      Returns:
      A long value representing the elapsed time, typically measured in milliseconds.

    • getSepsets

      public SepsetMap getSepsets()
      Returns the sepset map maintained by this instance of the FCI algorithm. The sepset map contains information about the separating sets identified during the causal discovery process.
      Returns:
      A SepsetMap object representing the separating sets computed within the algorithm.

    • getKnowledge

      public Knowledge getKnowledge()
      Retrieves the knowledge structure maintained by this instance.
      Returns:
      A Knowledge object representing the domain knowledge used or inferred by the algorithm.

    • setKnowledge

      public void setKnowledge(Knowledge knowledge)
      Sets the knowledge structure to be used or modified by the algorithm. The knowledge structure contains domain-specific constraints and information that guide the causal discovery process.
      Parameters:
      knowledge - A Knowledge object representing the domain-specific knowledge to set. This cannot be null.
      Throws:
      NullPointerException - If the provided knowledge is null.

    • setCompleteRuleSetUsed

      public void setCompleteRuleSetUsed(boolean completeRuleSetUsed)
      Configures whether the complete rule set is used in the FCI algorithm during the causal discovery process. This setting determines if all rules in the FCI framework will be applied.
      Parameters:
      completeRuleSetUsed - A boolean value indicating whether to enable or disable the usage of the complete rule set. If true, the entire rule set is used; otherwise, a subset of the rules is applied.

    • setDoPossibleDsep

      public void setDoPossibleDsep(boolean doPossibleDsep)
      Configures whether the possible-DSEP (Definite Separation) step is performed as part of the FCI algorithm during the causal discovery process. The possible-DSEP step influences the identification of separating sets in the graph by considering potential additional conditioning sets.
      Parameters:
      doPossibleDsep - A boolean value indicating whether to enable or disable the possible-DSEP step. If true, the possible-DSEP step is performed; otherwise, it is not.

    • setMaxDiscriminatingPathLength

      public void setMaxDiscriminatingPathLength(int maxDiscriminatingPathLength)
      Sets the maximum discriminating path length for the algorithm or process. If this value is set to -1, there is no limit on the path length. A non-negative value specifies the upper limit for the path length.
      Parameters:
      maxDiscriminatingPathLength - the maximum discriminating path length to set. Must be -1 (for no limit) or a non-negative integer.
      Throws:
      IllegalArgumentException - if the specified value is less than -1.

    • setVerbose

      public void setVerbose(boolean verbose)
      Sets the verbosity level for the system. When set to true, detailed logging or additional information may be displayed or processed.
      Parameters:
      verbose - a boolean value where true enables verbose mode and false disables it.

    • setStable

      public void setStable(boolean stable)
      Sets the stability status.
      Parameters:
      stable - a boolean value indicating whether the object is stable or not

    • setGuaranteePag

      public void setGuaranteePag(boolean guaranteePag)
      Sets the value of the guaranteePag flag.
      Parameters:
      guaranteePag - the boolean value to set as the guaranteePag flag

    • search

      public Graph search() throws InterruptedException
      Searches and retrieves a graph using the specified algorithm.
      Specified by:
      search in interface IGraphSearch
      Returns:
      the resulting Graph object obtained from the search operation
      Throws:
      InterruptedException - if the thread executing the search is interrupted

    • search

      public Graph search(IFas fas) throws InterruptedException
      Executes the search process using the provided `IFas` implementation and performs various graph orientation and refinement steps based on the FCI algorithm. This includes applying initial orientations, handling possible-dsep, and finalizing the graph structure according to the defined rules.

      The method logs details of the operations performed when the verbose flag is enabled. It also ensures the resulting graph is in a valid PAG state if the guaranteePag option is set.

      Parameters:
      fas - Implementation of the `IFas` interface, providing the functionality for the Fast Adjacency Search (FAS) to find the skeleton of the graph. Must be properly configured before calling this method.
      Returns:
      A `Graph` object representing the partially oriented graph (PAG) resulting from the search and orientation rules applied.
      Throws:
      InterruptedException - If the execution of the search process is interrupted.

    • getTest

      public IndependenceTest getTest()
      Retrieves the IndependenceTest instance.
      Specified by:
      getTest in interface IGraphSearch
      Returns:
      the IndependenceTest instance

    • setTest

      public void setTest(IndependenceTest test)
      Sets the independence test for the current object. The method checks if the variables of the provided test match the variables of the existing test. If they do not match, an IllegalArgumentException will be thrown.
      Specified by:
      setTest in interface IGraphSearch
      Parameters:
      test - the new IndependenceTest to be set. Must have the same list of variables as the existing test.
      Throws:
      IllegalArgumentException - if the variables of the provided test do not match the variables of the current test.

    • setReplicatingGraph

      public void setReplicatingGraph(boolean replicatingGraph)
      Sets the state of the replicatingGraph flag.
      Parameters:
      replicatingGraph - a boolean value indicating whether the graph should be in a replicating state.