Package edu.cmu.tetrad.search.work_in_progress

Class IsBicScore

java.lang.Object
edu.cmu.tetrad.search.work_in_progress.IsBicScore
All Implemented Interfaces:
IsScore
public class IsBicScore extends Object implements IsScore
Instance-Specific BIC (IS-BIC) score for discrete data.

This score adapts the standard Bayesian Information Criterion (BIC) to the instance-specific setting. As with the population version, the likelihood term is based on empirical counts, and the penalty term is proportional to the number of free parameters in the local conditional distribution:

   BIC = log-likelihood – 0.5 * penaltyDiscount * (numParams) * log(N)

where numParams = r_p * (K – 1), with r_p equal to the product of category counts of the parent set and K the number of categories of the child variable.

The instance-specific contribution does not alter the likelihood computation itself. Instead, it is incorporated through a structure prior that rewards or penalizes local modifications (addition, removal, or reversal of parents) relative to the baseline population model. In this way, IS-BIC balances population-wide fit with adjustments that highlight edges most relevant to the chosen test case.

This score is intended for use by search algorithms such as IS-FGES and IS-GFCI, providing a lightweight alternative to IS-BDeu when a BIC-style criterion is preferred.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IsBicScore(DataSet dataSet, DataSet testCase)
    Constructs an instance of ISBicScore, which evaluates an instance-specific Bayes Information Criterion (BIC) score, based on a provided training dataset and a single-row test case dataset.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    determines(List<Node> z, Node y)
    Determines whether the given list of nodes has a specific relationship with the specified node.
    DataSet
    getDataSet()
    Retrieves the dataset used in the scoring calculations.
    double
    getKAddition()
    Retrieves the addition modifier (k_addition) used in the scoring calculations.
    double
    getKDeletion()
    Retrieves the deletion modifier (k_deletion) used in the scoring calculations.
    double
    getKReorientation()
    Retrieves the reorientation modifier (k_reorient) used in the scoring calculations.
    int
    getMaxDegree()
    Retrieves the maximum allowable degree for nodes in the current scoring context.
    int[]
    getParentValuesForCombination(int rowIndex, int[] dims)
    Computes the values of parent variables in a specific combination given a row index in a multi-dimensional array and the dimensions of the array.
    double
    getPenaltyDiscount()
    Retrieves the penalty discount value associated with the scoring function.
    double
    getSamplePrior()
    Retrieves the prior probability assigned to the sample.
    int
    getSampleSize()
    Returns the sample size used for scoring.
    double
    getStructurePrior()
    Retrieves the prior value assigned to the structure.
    Node
    getVariable(String targetName)
    Retrieves a variable node by its target name.
    List<Node>
    getVariables()
    Retrieves the list of variable nodes associated with this instance.
    boolean
    isEffectEdge(double bump)
    Determines whether the edge has a significant effect based on the given bump value.
    double
    localScore(int node, int[] parents_is, int[] parents_pop, int[] children_pop)
    Calculates the local score for a given node using an instance-specific BIC (Bayesian Information Criterion) approach.
    double
    localScore1(int node, int[] parents_is, int[] parents_pop, int[] children_pop)
    Calculates the local score for a given node in the context of its parent nodes and children population, without using structure prior.
    double
    localScoreDiff(int x, int y, int[] z, int[] z_pop, int[] child_pop)
    Computes the local score difference for a variable when adding a candidate variable `x` to its instance-specific parent set.
    void
    setPenaltyDiscount(double penaltyDiscount)
    Sets the penalty discount value used for the scoring function.
    void
    setSamplePrior(double samplePrior)
    Sets the prior probability value assigned to the sample.
    void
    setStructurePrior(double structurePrior)
    Sets the prior value assigned to the structure.
    void
    setVariables(List<Node> variables)
    Sets the list of variable nodes for this instance, ensuring that the names of the input list match the names of the existing variables in order and size.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • IsBicScore

      public IsBicScore(DataSet dataSet, DataSet testCase)
      Constructs an instance of ISBicScore, which evaluates an instance-specific Bayes Information Criterion (BIC) score, based on a provided training dataset and a single-row test case dataset.
      Parameters:
      dataSet - the training dataset; must not be null and must contain discrete variables for proper analysis. If the data is contained within a BoxDataSet, it must utilize a VerticalIntDataBox to represent discrete data.
      testCase - the test dataset; must consist of exactly one row and have the same number of variables as the training dataset. If the test case is represented within a BoxDataSet, it should conform to VerticalIntDataBox format, or it will be coerced into such a format.
      Throws:
      NullPointerException - if either the training dataset or the test case dataset is null.
      IllegalArgumentException - if the training dataset contains non-discrete variables, if the test case variable count does not match the training dataset variable count, or if the test case does not contain a single row.

  • Method Details

    • localScore

      public double localScore(int node, int[] parents_is, int[] parents_pop, int[] children_pop)
      Calculates the local score for a given node using an instance-specific BIC (Bayesian Information Criterion) approach. This method evaluates the likelihood and structure penalties with respect to the given dataset and parameters.
      Specified by:
      localScore in interface IsScore
      Parameters:
      node - the index of the target node for which the score is being computed; the node must correspond to a discrete variable.
      parents_is - the indices of instance-specific parents of the node; all indices must correspond to discrete variables.
      parents_pop - the indices of population-level parents of the node; all indices must correspond to discrete variables.
      children_pop - the indices of population-level children of the node; used for structural prior calculations.
      Returns:
      the calculated local score for the node based on the specified BIC components, structure penalties, and priors.
      Throws:
      IllegalArgumentException - if the node or any of its parents in parents_is or parents_pop is not a discrete variable.

    • localScoreDiff

      public double localScoreDiff(int x, int y, int[] z, int[] z_pop, int[] child_pop)
      Computes the local score difference for a variable when adding a candidate variable `x` to its instance-specific parent set. The score difference is calculated as the score with the variable added minus the score without the variable.
      Specified by:
      localScoreDiff in interface IsScore
      Parameters:
      x - the index of the candidate variable to be added; must correspond to a discrete variable.
      y - the index of the target variable for which the score difference is being computed; must correspond to a discrete variable.
      z - the indices of the current instance-specific parents of the target variable; all indices must correspond to discrete variables.
      z_pop - the indices of population-level parents of the target variable; all indices must correspond to discrete variables.
      child_pop - the indices of population-level children of the target variable; used for structural prior calculations.
      Returns:
      the computed score difference resulting from adding the variable `x` to the instance-specific parent set of `y`.

    • getVariables

      public List<Node> getVariables()
      Retrieves the list of variable nodes associated with this instance.
      Specified by:
      getVariables in interface IsScore
      Returns:
      a list of nodes representing the variables.

    • setVariables

      public void setVariables(List<Node> variables)
      Sets the list of variable nodes for this instance, ensuring that the names of the input list match the names of the existing variables in order and size.
      Parameters:
      variables - the list of nodes representing variables to be set; each node must have the same name and remain in the same order as the existing variables.
      Throws:
      IllegalArgumentException - if there is a mismatch in variable names or if the size of the input list differs from the existing variables list.

    • getSampleSize

      public int getSampleSize()
      Returns the sample size used for scoring.
      Specified by:
      getSampleSize in interface IsScore
      Returns:
      the sample size used for scoring

    • isEffectEdge

      public boolean isEffectEdge(double bump)
      Description copied from interface: IsScore
      Determines whether the edge has a significant effect based on the given bump value.
      Specified by:
      isEffectEdge in interface IsScore
      Parameters:
      bump - The threshold value to evaluate the significance of the effect on the edge.
      Returns:
      true if the edge has a significant effect; false otherwise.

    • getDataSet

      public DataSet getDataSet()
      Description copied from interface: IsScore
      Retrieves the dataset used in the scoring calculations.
      Specified by:
      getDataSet in interface IsScore
      Returns:
      the dataset used in the scoring calculations.

    • getStructurePrior

      public double getStructurePrior()
      Description copied from interface: IsScore
      Retrieves the prior value assigned to the structure.
      Specified by:
      getStructurePrior in interface IsScore
      Returns:
      the structure prior value as a double.

    • setStructurePrior

      public void setStructurePrior(double structurePrior)
      Description copied from interface: IsScore
      Sets the prior value assigned to the structure.
      Specified by:
      setStructurePrior in interface IsScore
      Parameters:
      structurePrior - the structure prior value to be set as a double.

    • getSamplePrior

      public double getSamplePrior()
      Description copied from interface: IsScore
      Retrieves the prior probability assigned to the sample.
      Specified by:
      getSamplePrior in interface IsScore
      Returns:
      the sample prior value as a double.

    • setSamplePrior

      public void setSamplePrior(double samplePrior)
      Description copied from interface: IsScore
      Sets the prior probability value assigned to the sample.
      Specified by:
      setSamplePrior in interface IsScore
      Parameters:
      samplePrior - the sample prior value to be set as a double.

    • getVariable

      public Node getVariable(String targetName)
      Description copied from interface: IsScore
      Retrieves a variable node by its target name.
      Specified by:
      getVariable in interface IsScore
      Parameters:
      targetName - the name of the target variable to retrieve
      Returns:
      the node representing the variable with the specified target name

    • getMaxDegree

      public int getMaxDegree()
      Description copied from interface: IsScore
      Retrieves the maximum allowable degree for nodes in the current scoring context.
      Specified by:
      getMaxDegree in interface IsScore
      Returns:
      The maximum degree a node can have.

    • determines

      public boolean determines(List<Node> z, Node y)
      Description copied from interface: IsScore
      Determines whether the given list of nodes has a specific relationship with the specified node.
      Specified by:
      determines in interface IsScore
      Parameters:
      z - the list of nodes to be evaluated.
      y - the node to be checked against the list.
      Returns:
      true if the list of nodes determines the specified node; false otherwise.

    • localScore1

      public double localScore1(int node, int[] parents_is, int[] parents_pop, int[] children_pop)
      Description copied from interface: IsScore
      Calculates the local score for a given node in the context of its parent nodes and children population, without using structure prior.

      same as localSCire but this one doesn't use structure prior

      Specified by:
      localScore1 in interface IsScore
      Parameters:
      node - The index of the node for which the score is being calculated.
      parents_is - An array representing the indices of the parent nodes.
      parents_pop - An array representing the population of the parent nodes.
      children_pop - An array representing the population of the children nodes.
      Returns:
      The local score for the specified node.

    • getPenaltyDiscount

      public double getPenaltyDiscount()
      Retrieves the penalty discount value associated with the scoring function. The penalty discount is applied to adjust the penalty term in the score calculation, influencing regularization or model complexity considerations.
      Returns:
      the current penalty discount value as a double

    • setPenaltyDiscount

      public void setPenaltyDiscount(double penaltyDiscount)
      Sets the penalty discount value used for the scoring function. The penalty discount adjusts the penalty term in the score calculation to influence regularization or considerations of model complexity.
      Parameters:
      penaltyDiscount - the penalty discount value to set; must be a non-negative double

    • getKAddition

      public double getKAddition()
      Retrieves the addition modifier (k_addition) used in the scoring calculations. This value may influence the scoring function by adjusting or modulating specific aspects of the score evaluation.
      Returns:
      the current addition modifier (k_addition) value as a double

    • getKDeletion

      public double getKDeletion()
      Retrieves the deletion modifier (k_deletion) used in the scoring calculations. This value may influence the scoring function by adjusting or modulating specific aspects of the score evaluation.
      Returns:
      the current deletion modifier (k_deletion) value as a double

    • getKReorientation

      public double getKReorientation()
      Retrieves the reorientation modifier (k_reorient) used in the scoring calculations. This value may influence the scoring function by adjusting or modulating specific aspects of the score evaluation related to reorientation operations.
      Returns:
      the current reorientation modifier (k_reorient) value as a double

    • getParentValuesForCombination

      public int[] getParentValuesForCombination(int rowIndex, int[] dims)
      Computes the values of parent variables in a specific combination given a row index in a multi-dimensional array and the dimensions of the array.
      Parameters:
      rowIndex - the index in the flattened multi-dimensional array for which parent values need to be computed
      dims - the dimensions of the multi-dimensional array; an array where each element represents the size of a dimension
      Returns:
      an array of integers where each value corresponds to the parent values for the specified rowIndex based on the provided dimensions