Class KernelMarginalLikelihoodScoreContinuous

java.lang.Object
edu.cmu.tetrad.search.score.KernelMarginalLikelihoodScoreContinuous
All Implemented Interfaces:
Score, EffectiveSampleSizeSettable
public final class KernelMarginalLikelihoodScoreContinuous extends Object implements Score, EffectiveSampleSizeSettable
Kernel Marginal Likelihood (KML) score for continuous variables.

This score implements the exact Gaussian Process (GP) marginal likelihood for evaluating candidate parent sets in score-based causal discovery. For a target variable Y and parent set Z, the model is 

  Y = f(Z) + ε,    ε ~ N(0, σ² I)
  f ~ GP(0, k(·,·))

where k is a positive-definite kernel (typically an RBF kernel). The marginal covariance of Y is 

  C = K_Z + σ² I

with K_Z the kernel Gram matrix over the parent variables. The score (up to an additive constant) is the GP marginal log-likelihood 

  S = -0.5 · Yᵀ C⁻¹ Y - 0.5 · log |C|.

This class is the continuous engine used by KernelMarginalLikelihoodScore, which handles the mixed (continuous + discrete) case and delegates purely continuous local scores here. It also exposes the exact RBF Gram construction (rbfGramContinuous(int[], int[], int)) and the GP marginal-likelihood solvers (gpLogMarginalLikelihood(double[], DMatrixRMaj, double) and gpLogMarginalLikelihoodMulti(double[][], DMatrixRMaj, double)) so the mixed score can compose the RBF kernel with a categorical kernel without re-implementing the linear algebra.

Computational considerations

Computing the KML score requires forming and factorizing an n × n kernel covariance matrix, which has O(n³) time and O(n²) memory complexity. As a result, this score is best suited for small to moderate sample sizes.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    KernelMarginalLikelihoodScoreContinuous(DataSet dataSet)
    Constructs an instance of KernelMarginalLikelihoodScoreContinuous using the provided data set.

  • Method Summary

    Modifier and Type
    Method
    Description
    int[]
    append(int[] z, int x)
    Appends an integer to an int array, returning a new array.
    boolean
    determines(List<Node> z, Node y)
    Determines if a node is determined by a set of nodes.
    DataModel
    getDataModel()
    Retrieves the data model used for scoring.
    int
    getEffectiveSampleSize()
    Retrieves the effective sample size used for scoring.
    double
    getJitter()
    Retrieves the jitter parameter.
    int
    getMaxDegree()
    Retrieves the maximum degree allowed for scoring.
    int
    getSampleSize()
    Retrieves the sample size used for scoring.
    List<Node>
    getVariables()
    Retrieves the list of variables associated with this score object.
    static double
    gpLogMarginalLikelihood(double[] y, org.ejml.data.DMatrixRMaj C, double jitter)
    Computes the single-output GP log marginal likelihood -0.5*yᵀ C⁻¹ y - 0.5*log|C| using Cholesky with jitter escalation.
    static double
    gpLogMarginalLikelihoodMulti(double[][] Ycentered, org.ejml.data.DMatrixRMaj C, double jitter)
    Multi-output GP log marginal likelihood for a shared covariance C.
    boolean
    isEffectEdge(double bump)
    Determines if an edge is an effect edge based on a given bump value.
    double
    localScore(int i, int... parents)
    The score of a node given its parents.
    double
    localScoreDiff(int x, int y, int[] z)
    Computes the difference in local scores when adding a variable to the conditioning set.
    org.ejml.data.DMatrixRMaj
    rbfGramContinuous(int[] contParents, int[] rows, int n)
    Public accessor for the exact RBF Gram matrix over the given (continuous) parents, so composite scores can build product kernels without re-implementing the kernel.
    void
    setBandwidthMultiplier(double bandwidthMultiplier)
    Sets the bandwidth multiplier parameter for the Kernel Marginal Likelihood Score.
    void
    setBwMaxRows(int bwMaxRows)
    Sets the maximum number of rows to be used in bandwidth calculations.
    void
    setEffectiveSampleSize(int nEff)
    Sets the effective sample size used for scoring.
    void
    setJitter(double jitter)
    Sets the jitter parameter for the Kernel Marginal Likelihood Score.
    void
    setLambda(double lambda)
    Sets the lambda hyperparameter for the Kernel Marginal Likelihood Score.
    String
    toString()
    Retrieves the name of the score.

    Methods inherited from class Object

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

    Methods inherited from interface Score

    getMissingValueSupport, getVariable, localScore, localScore, localScoreDiff

  • Constructor Details

    • KernelMarginalLikelihoodScoreContinuous

      public KernelMarginalLikelihoodScoreContinuous(DataSet dataSet)
      Constructs an instance of KernelMarginalLikelihoodScoreContinuous using the provided data set. This constructor initializes internal variables, processes the input data, and applies z-scoring to standardize the columns while preserving NaN values.
      Parameters:
      dataSet - The data set to be used for computing the Kernel Marginal Likelihood Score. Must not be null. Throws a NullPointerException if the data set is null.

  • Method Details

    • localScoreDiff

      public double localScoreDiff(int x, int y, int[] z)
      Computes the difference in local scores when adding a variable to the conditioning set.
      Specified by:
      localScoreDiff in interface Score
      Parameters:
      x - The variable to be added to the conditioning set.
      y - The target variable for which the score is being computed.
      z - The original conditioning set of variables.
      Returns:
      The difference in local scores between the modified and original conditioning sets.

    • localScore

      public double localScore(int i, int... parents)
      Description copied from interface: Score
      The score of a node given its parents.
      Specified by:
      localScore in interface Score
      Parameters:
      i - The node.
      parents - The parents.
      Returns:
      The score.

    • getVariables

      public List<Node> getVariables()
      Retrieves the list of variables associated with this score object.
      Specified by:
      getVariables in interface Score
      Returns:
      A list of Node objects representing the variables.

    • getSampleSize

      public int getSampleSize()
      Retrieves the sample size used for scoring.
      Specified by:
      getSampleSize in interface Score
      Returns:
      The sample size as an integer.

    • getMaxDegree

      public int getMaxDegree()
      Retrieves the maximum degree allowed for scoring.
      Specified by:
      getMaxDegree in interface Score
      Returns:
      The maximum degree as an integer.

    • determines

      public boolean determines(List<Node> z, Node y)
      Determines if a node is determined by a set of nodes.
      Specified by:
      determines in interface Score
      Parameters:
      z - The set of nodes.
      y - The node.
      Returns:
      True if the node is determined by the set of nodes, false otherwise.

    • isEffectEdge

      public boolean isEffectEdge(double bump)
      Determines if an edge is an effect edge based on a given bump value.
      Specified by:
      isEffectEdge in interface Score
      Parameters:
      bump - The bump value.
      Returns:
      True if the edge is an effect edge, false otherwise.

    • getDataModel

      public DataModel getDataModel()
      Retrieves the data model used for scoring.
      Returns:
      The data model.

    • getEffectiveSampleSize

      public int getEffectiveSampleSize()
      Retrieves the effective sample size used for scoring.
      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 used for scoring.
      Specified by:
      setEffectiveSampleSize in interface EffectiveSampleSizeSettable
      Parameters:
      nEff - the effective sample size

    • toString

      public String toString()
      Retrieves the name of the score.
      Specified by:
      toString in interface Score
      Overrides:
      toString in class Object
      Returns:
      The name of the score as a String.

    • setLambda

      public void setLambda(double lambda)
      Sets the lambda hyperparameter for the Kernel Marginal Likelihood Score.
      Parameters:
      lambda - The new value for the lambda hyperparameter. Must be greater than 0.

    • setJitter

      public void setJitter(double jitter)
      Sets the jitter parameter for the Kernel Marginal Likelihood Score.
      Parameters:
      jitter - The new value for the jitter parameter. Must be greater than 0.

    • getJitter

      public double getJitter()
      Retrieves the jitter parameter.
      Returns:
      the jitter value.

    • setBandwidthMultiplier

      public void setBandwidthMultiplier(double bandwidthMultiplier)
      Sets the bandwidth multiplier parameter for the Kernel Marginal Likelihood Score.
      Parameters:
      bandwidthMultiplier - The new value for the bandwidth multiplier. Must be greater than 0 and finite.

    • setBwMaxRows

      public void setBwMaxRows(int bwMaxRows)
      Sets the maximum number of rows to be used in bandwidth calculations. Minimum 50.
      Parameters:
      bwMaxRows - The new maximum number of rows for bandwidth calculations.

    • gpLogMarginalLikelihood

      public static double gpLogMarginalLikelihood(double[] y, org.ejml.data.DMatrixRMaj C, double jitter)
      Computes the single-output GP log marginal likelihood -0.5*yᵀ C⁻¹ y - 0.5*log|C| using Cholesky with jitter escalation. C is expected to already include the σ² I ridge.
      Parameters:
      y - centered target vector (length n).
      C - the n×n marginal covariance (kernel + ridge).
      jitter - jitter base for Cholesky stabilization.
      Returns:
      the GP log marginal likelihood, or NaN if factorization fails.

    • gpLogMarginalLikelihoodMulti

      public static double gpLogMarginalLikelihoodMulti(double[][] Ycentered, org.ejml.data.DMatrixRMaj C, double jitter)
      Multi-output GP log marginal likelihood for a shared covariance C.

      Each column of Ycentered is treated as an independent output with the same covariance C = K + σ² I, so the score is the sum of the per-output single-output log marginal likelihoods: 

        Σ_c [ -0.5 · y_cᵀ C⁻¹ y_c ] - 0.5 · L · log|C|.

      Because C does not depend on the output column, it is factorized once and reused for every column (the log|C| term is shared), which is substantially cheaper than re-factorizing per output.

      Parameters:
      Ycentered - n×L matrix of centered outputs (e.g. centered one-hot columns).
      C - the shared n×n marginal covariance (kernel + ridge).
      jitter - jitter base for Cholesky stabilization.
      Returns:
      the summed multi-output GP log marginal likelihood, or NaN on failure.

    • rbfGramContinuous

      public org.ejml.data.DMatrixRMaj rbfGramContinuous(int[] contParents, int[] rows, int n)
      Public accessor for the exact RBF Gram matrix over the given (continuous) parents, so composite scores can build product kernels without re-implementing the kernel.

      Note: with an empty parent list this returns the all-ones matrix (the RBF kernel over zero dimensions is identically 1), which is exactly the multiplicative identity for a Hadamard product with a categorical kernel.

      Parameters:
      contParents - continuous parent indices (may be empty).
      rows - active absolute row indices, or null to use the first n rows.
      n - number of active rows.
      Returns:
      the n×n RBF Gram matrix.

    • append

      public int[] append(int[] z, int x)
      Appends an integer to an int array, returning a new array.
      Specified by:
      append in interface Score
      Parameters:
      z - the original array.
      x - the value to append.
      Returns:
      a new array with x appended.