Class HuangMarginalLikelihoodScore

java.lang.Object
edu.cmu.tetrad.search.score.HuangMarginalLikelihoodScore
All Implemented Interfaces:
Score, EffectiveSampleSizeSettable

public final class HuangMarginalLikelihoodScore extends Object implements Score, EffectiveSampleSizeSettable
Kernel-based marginal likelihood score of Huang et al. (2018) for continuous variables.

This score implements the kernel marginal score proposed by Huang, Zhang, Schölkopf, and Zhang (2018) for evaluating the fit of a regression of a target variable X on a parent set Z using reproducing kernel Hilbert space (RKHS) methods. The score is derived from kernel ridge regression and can be interpreted as a surrogate marginal likelihood obtained by integrating out the regression function in an RKHS.

Model and Interpretation

Let X be a univariate response and Z a (possibly multivariate) set of predictors. Huang et al. consider a kernel regression model in which the conditional mean function of X given Z lies in an RKHS associated with a positive-definite kernel. The score is constructed from centered kernel Gram matrices Kx (for the response) and Kz (for the predictors), together with a ridge parameter lambda.

After kernel centering, the score depends on the matrix A = Kz + n * lambda * I, and is computed via the expression

  S = - (n / 2) * log | (n * lambda / 2) * (Kx * A^{-2} * Kx) |  + const,

where n is the sample size and |·| denotes a (pseudo-)determinant. The implementation evaluates this expression using stable linear-algebraic operations (Cholesky decompositions and solves), avoiding explicit matrix inversion.

Numerical Characteristics

Because the centered kernel matrices are singular by construction, the matrix whose determinant appears in the score is typically positive semidefinite rather than strictly positive definite. As a result, the score relies on either a pseudo-determinant (based on eigenvalues) or an implicit ridge regularization to ensure numerical stability.

In practice, this makes the Huang marginal score more sensitive to kernel bandwidth choice, regularization strength, and numerical noise than a full Gaussian process marginal likelihood. While the score can perform well in some nonlinear regression settings, it may exhibit instability in greedy score-based causal search when parent sets differ by small changes.

Comparison to Other Kernel Scores

  • Unlike the exact kernel marginal likelihood (KML), this score does not correspond to a full probabilistic marginal likelihood over functions.
  • Compared to operator-based surrogates, it is more principled but still approximate.
  • Compared to KML or its low-rank variants (e.g., RFF-ML / KFF-ML), it is generally less stable for greedy structure search, though computationally cheaper than exact GP scoring.

Implementation Notes

  • Uses Gaussian RBF kernels with a median-distance bandwidth heuristic.
  • Centers all kernel Gram matrices in feature space.
  • Handles missing data via row-wise deletion over X ∪ Z.
  • Avoids explicit matrix inversion; relies on Cholesky factorizations.

Higher scores indicate better fit, consistent with Tetrad Score conventions.

See Also:
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a HuangMarginalScore object by initializing it with the given dataset and precomputing internal structures required for scoring.
  • Method Summary

    Modifier and Type
    Method
    Description
    int[]
    append(int[] z, int x)
    Appends an extra int to a list of ints.
    boolean
    Determines whether the given variable y is conditionally independent of the set of variables z based on a computed score.
    Retrieves the data model associated with this instance.
    int
    Retrieves the effective sample size used in the scoring algorithm.
    int
    Computes the maximum degree based on a heuristic approach.
    int
    Retrieves the sample size used in the scoring process.
    getVariable(String targetName)
    Returns the variable with the given name.
    Retrieves the list of variables used in the scoring process.
    boolean
    isEffectEdge(double bump)
    Determines whether a given edge has an effect based on the specified bump value.
    double
    localScore(int node)
    Returns the local score of the gien node in the graph.
    double
    localScore(int node, int parent)
    Returns the local score of the graph.
    double
    localScore(int i, int... parents)
    Computes the local score for a given target variable and a set of parent variables.
    double
    localScoreDiff(int x, int y)
    Returns the local score difference of the graph.
    double
    localScoreDiff(int x, int y, int[] z)
    Computes the difference between two local scores: `score(y | z ∪ {x})` and `score(y | z)`.
    void
    Sets the multiplier used to adjust the bandwidth in calculations.
    void
    Sets the effective sample size for score calculations.
    void
    setJitter(double jitter)
    Sets the value of the jitter parameter and clears the local score cache.
    void
    setLambda(double lambda)
    Sets the value of the lambda parameter and clears the local score cache.
    Returns a string representation of the HuangMarginalScore object.

    Methods inherited from class Object

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

    Methods inherited from interface Score

    getMissingValueSupport
  • Constructor Details

    • HuangMarginalLikelihoodScore

      public HuangMarginalLikelihoodScore(DataSet dataSet)
      Constructs a HuangMarginalScore object by initializing it with the given dataset and precomputing internal structures required for scoring.
      Parameters:
      dataSet - The input data set to be used for computing marginal scores. Must not be null; a NullPointerException is thrown if the input is null.
  • Method Details

    • localScoreDiff

      public double localScoreDiff(int x, int y, int[] z)
      Computes the difference between two local scores: `score(y | z ∪ {x})` and `score(y | z)`. This method evaluates the impact of adding a variable `x` to the conditioning set `z` for predicting the target variable `y`.
      Specified by:
      localScoreDiff in interface Score
      Parameters:
      x - The index of the variable being added to the conditioning set.
      y - The index of the target variable whose score is being evaluated.
      z - An array containing the indices of the conditioning variables.
      Returns:
      The difference between the local scores: `score(y | z ∪ {x}) - score(y | z)`.
    • localScore

      public double localScore(int i, int... parents)
      Computes the local score for a given target variable and a set of parent variables. The local score reflects the statistical relationship between the target variable and its conditioning parents based on kernel methods. This method uses precomputed results from a cache if available; otherwise, it computes the score and caches it.
      Specified by:
      localScore in interface Score
      Parameters:
      i - The index of the target variable whose local score is being computed.
      parents - An array of indices representing the parent variables used for computation. This array may be empty if the target variable has no parents.
      Returns:
      The computed local score as a double. NaN is returned if there are insufficient effective samples or other conditions make the score indeterminable.
    • getVariables

      public List<Node> getVariables()
      Retrieves the list of variables used in the scoring process. The returned list contains all variables associated with the dataset.
      Specified by:
      getVariables in interface Score
      Returns:
      A new List of Node objects representing the variables.
    • getSampleSize

      public int getSampleSize()
      Retrieves the sample size used in the scoring process.
      Specified by:
      getSampleSize in interface Score
      Returns:
      The total number of rows in the dataset, representing the sample size as an integer.
    • getMaxDegree

      public int getMaxDegree()
      Computes the maximum degree based on a heuristic approach. The calculation is performed as the ceiling of the logarithm of the effective sample size (nEff). A minimum value of 3 is considered for the logarithmic calculation to ensure robustness.
      Specified by:
      getMaxDegree in interface Score
      Returns:
      the maximum allowed degree as an integer
    • determines

      public boolean determines(List<Node> z, Node y)
      Determines whether the given variable y is conditionally independent of the set of variables z based on a computed score. This is typically used in causal structure discovery algorithms.
      Specified by:
      determines in interface Score
      Parameters:
      z - the list of parent nodes to check for conditional independence
      y - the target node to test against the parent set
      Returns:
      true if the score calculation results in NaN or infinity, indicating an error or undefined state; otherwise, false
    • isEffectEdge

      public boolean isEffectEdge(double bump)
      Determines whether a given edge has an effect based on the specified bump value.
      Specified by:
      isEffectEdge in interface Score
      Parameters:
      bump - The numerical value used to evaluate the edge's effect. A positive value indicates that the edge is considered to have an effect.
      Returns:
      true if the bump value is greater than 0, indicating the edge has an effect; false otherwise.
    • getDataModel

      public DataModel getDataModel()
      Retrieves the data model associated with this instance.
      Returns:
      The DataModel representing the dataset used for scoring.
    • getEffectiveSampleSize

      public int getEffectiveSampleSize()
      Retrieves the effective sample size used in the scoring algorithm. The effective sample size is a parameter that reflects the number of data points effectively contributing to the score calculation.
      Specified by:
      getEffectiveSampleSize in interface EffectiveSampleSizeSettable
      Returns:
      The effective sample size as an integer.
    • setEffectiveSampleSize

      public void setEffectiveSampleSize(int nEff)
      Sets the effective sample size for score calculations. If the provided effective sample size is negative, the method defaults to using the original sample size.
      Specified by:
      setEffectiveSampleSize in interface EffectiveSampleSizeSettable
      Parameters:
      nEff - The effective sample size to be set. If less than 0, the original sample size is used.
    • setBandwidthMultiplier

      public void setBandwidthMultiplier(double m)
      Sets the multiplier used to adjust the bandwidth in calculations. The value must be greater than 0 and finite.
      Parameters:
      m - the value to set as the bandwidth multiplier
      Throws:
      IllegalArgumentException - if the value is not greater than 0 or is not finite
    • toString

      public String toString()
      Returns a string representation of the HuangMarginalScore object.
      Specified by:
      toString in interface Score
      Overrides:
      toString in class Object
      Returns:
      A string describing the Huang Kernel Marginal Score as "Huang Kernel Marginal Score (continuous)".
    • setLambda

      public void setLambda(double lambda)
      Sets the value of the lambda parameter and clears the local score cache. The lambda parameter is a positive value that may be used in computations involving kernel-based methods, such as controlling the regularization strength. If the provided value is less than or equal to 0, an IllegalArgumentException is thrown.
      Parameters:
      lambda - The value to set for the lambda parameter. Must be greater than 0.
      Throws:
      IllegalArgumentException - if the provided lambda value is less than or equal to 0.
    • setJitter

      public void setJitter(double jitter)
      Sets the value of the jitter parameter and clears the local score cache. The jitter parameter is a small positive value added to the diagonal of certain matrices during computations to improve numerical stability. If the provided jitter value is less than or equal to 0, an IllegalArgumentException is thrown.
      Parameters:
      jitter - The value to set for the jitter parameter. Must be a positive double.
      Throws:
      IllegalArgumentException - if the provided jitter value is less than or equal to 0.
    • append

      public int[] append(int[] z, int x)
      Description copied from interface: Score
      Appends an extra int to a list of ints.
      Specified by:
      append in interface Score
      Parameters:
      z - The list of ints.
      x - The extra int.
      Returns:
      The new list of ints.
    • localScoreDiff

      public double localScoreDiff(int x, int y)
      Description copied from interface: Score
      Returns the local score difference of the graph.
      Specified by:
      localScoreDiff in interface Score
      Parameters:
      x - A node.
      y - The node.
      Returns:
      The local score difference.
    • localScore

      public double localScore(int node, int parent)
      Description copied from interface: Score
      Returns the local score of the graph.
      Specified by:
      localScore in interface Score
      Parameters:
      node - A node.
      parent - A parent.
      Returns:
      The local score.
    • localScore

      public double localScore(int node)
      Description copied from interface: Score
      Returns the local score of the gien node in the graph.
      Specified by:
      localScore in interface Score
      Parameters:
      node - A node.
      Returns:
      The local score.
    • getVariable

      public Node getVariable(String targetName)
      Description copied from interface: Score
      Returns the variable with the given name.
      Specified by:
      getVariable in interface Score
      Parameters:
      targetName - The name.
      Returns:
      The variable.