Class BasisFunctionBgeScore

java.lang.Object
edu.cmu.tetrad.search.score.BasisFunctionBgeScore
All Implemented Interfaces:
Score
Direct Known Subclasses:
DegenerateGaussianBgeScore
public class BasisFunctionBgeScore extends Object implements Score
BF-BGe: the BGe score applied to the basis-function embedding used by BasisFunctionBicScore. Each continuous variable is expanded into its Legendre basis columns up to a truncation limit and each discrete variable into one indicator column per category but the last, exactly as in BF-BIC; but where BF-BIC scores the expanded family with a BIC-penalized Gaussian likelihood, BF-BGe scores it with the exact Normal-Wishart marginal likelihood of BgeScore. This replaces the BIC penalty on the whole expanded block (the source of BF-BIC's conservatism on weak linear edges) with the Bayesian Occam factor, in the same way that BDeu replaces the discrete BIC penalty.

For a family Y | Pa with embedded column sets A (for Y) and B (for Pa), the local score is 

  log p(D_{A u B}) - log p(D_B),
where p(D_S) is the BGe marginal likelihood of the embedded columns S under the Normal-Wishart prior on the full embedded system of dimension p (the total number of embedded columns), from Kuipers, Moffa, and Heckerman (2014), eq. (10). This is the block analog of BGe's family score, equivalently the chain-rule sum of single-column BGe scores over the columns of A given B and the earlier columns of A, and it telescopes the same way, so the score is decomposable and score-equivalent over the embedded block DAG. Because the prior scale matrix is added to the scatter, the family scatter matrix is always positive definite, and no singularity lambda is needed.

Hyperparameters and prior conventions are those of BgeScore: prior mean equal to the sample mean, prior scale T = t diag(s_j^2) over the embedded columns with t = alpha_mu (alpha_w - p - 1) / (alpha_mu + 1), and alpha_w = p + alphaWOffset. As with BGe, alpha_mu acts on the score only through t, so smaller alpha_mu makes edges more expensive; alpha_mu = 0.1 tracks SEM-BIC at penalty discount 2 in null false-positive rate, and alpha_mu = 1 sits between penalty discounts 1 and 2.

Embedded columns with zero sample variance (e.g., indicators of categories that do not occur) carry no information and are dropped from the embedding at construction.

Discrete interaction order. By default (order 1) the parent block B is additive in the parents' indicator columns, so a discrete child can depend on its discrete parents only through main effects; this is the model class of DG-BIC and BF-BIC, and it cannot represent, e.g., an XOR-type dependence of a child on two parents, which is where these scores lose power relative to BDeu on discrete data. With discrete interaction order k > 1, B is augmented, per family, with products of indicator columns drawn from up to k distinct discrete parents (one indicator from each). Under the reference-cell coding used here these products span exactly the interaction effects up to order k, so order 2 adds pairwise interactions and an order at least the number of discrete parents gives the saturated parent design, the same span as BDeu's conditional table. Product columns that are identically zero (empty cells) are dropped, so, as in BDeu, empty cells cost nothing. Continuous parents and the child's own block are unaffected. The Normal-Wishart prior's projection property means the subset marginal depends on the embedded dimension only through alpha_w - p, so the family-specific columns do not disturb the prior.

The cost is score equivalence: with order > 1 a family's column set depends on its parent set, the local scores no longer telescope to a single joint marginal likelihood, and Markov-equivalent DAGs can score differently (as with the conditional Gaussian score). Use order > 1 with permutation searches such as BOSS and GRaSP; the default 1 preserves the score-equivalent baseline exactly.

Author:
josephramsey
See Also:

  • Constructor Details

    • BasisFunctionBgeScore

      public BasisFunctionBgeScore(DataSet dataSet, int truncationLimit)
      Constructs a BF-BGe score with the Legendre embedding of BasisFunctionBicScore.
      Parameters:
      dataSet - the (mixed) data set.
      truncationLimit - the truncation limit of the basis (1 gives the linear/degenerate-Gaussian embedding).

    • BasisFunctionBgeScore

      public BasisFunctionBgeScore(DataSet dataSet, int truncationLimit, boolean adaptiveBasisSelection)
      Constructs a BF-BGe score with the Legendre embedding of BasisFunctionBicScore, optionally applying the same adaptive basis-column screen that BF-BIC uses.
      Parameters:
      dataSet - the (mixed) data set.
      truncationLimit - the truncation limit of the basis.
      adaptiveBasisSelection - if true, higher-order basis columns that fail BF-BIC's BIC-crossing screen are dropped from the embedding before scoring.
      See Also:

    • BasisFunctionBgeScore

      public BasisFunctionBgeScore(DataSet dataSet, int truncationLimit, boolean adaptiveBasisSelection, MissingDataSpec spec)
      As BasisFunctionBgeScore(DataSet, int, boolean), with an explicit missing-data specification. On a data set with missing values the supported policies are LISTWISE and TESTWISE. Under TESTWISE the embedding carries NaN in every derived column of a variable wherever that variable is missing, and each family's scatter matrix is formed from the covariance of the family's embedded columns over the rows complete on those columns, with the family's own complete-row count as N. Interaction columns (discrete interaction order above 1) are not available under TESTWISE. A null spec on missing data is treated as FAIL.
      Parameters:
      dataSet - the (mixed) data set.
      truncationLimit - the truncation limit of the basis.
      adaptiveBasisSelection - whether to apply the BIC-crossing screen (under TESTWISE the screen is computed from pairwise-deletion correlations).
      spec - the missing-data specification, or null.

  • Method Details

    • localScore

      public double localScore(int node, int... parents)
      Returns log p(D_{A u B}) - log p(D_B) for the embedded columns A of the node and B of its parents.
      Specified by:
      localScore in interface Score
      Parameters:
      node - the index of the child.
      parents - the indices of the parents.
      Returns:
      the local score ("higher is better").

    • localScoreDiff

      public double localScoreDiff(int x, int y, int[] z)
      Returns the score difference of the graph.
      Specified by:
      localScoreDiff in interface Score
      Parameters:
      x - A node.
      y - TAhe node.
      z - A set of nodes.
      Returns:
      The score difference.

    • getVariables

      public List<Node> getVariables()
      The variables of the score.
      Specified by:
      getVariables in interface Score
      Returns:
      This list.

    • getSampleSize

      public int getSampleSize()
      The sample size of the data.
      Specified by:
      getSampleSize in interface Score
      Returns:
      This size.

    • isEffectEdge

      public boolean isEffectEdge(double bump)
      Returns true iff the edge between x and y is an effect edge.
      Specified by:
      isEffectEdge in interface Score
      Parameters:
      bump - The bump.
      Returns:
      True iff the edge between x and y is an effect edge.

    • getMaxDegree

      public int getMaxDegree()
      Returns the max degree, by default 1000.
      Specified by:
      getMaxDegree in interface Score
      Returns:
      The max degree.

    • getEffectiveSampleSize

      public int getEffectiveSampleSize()
      Returns the effective sample size.
      Returns:
      N used in the score.

    • setEffectiveSampleSize

      public void setEffectiveSampleSize(int nEff)
      Sets the effective sample size; a value less than 1 restores the actual sample size.
      Parameters:
      nEff - the effective sample size.

    • getAlphaMu

      public double getAlphaMu()
      Returns the prior precision on the mean.
      Returns:
      alpha_mu.

    • setAlphaMu

      public void setAlphaMu(double alphaMu)
      Sets the prior precision on the mean; must be positive.
      Parameters:
      alphaMu - alpha_mu.

    • getAlphaWOffset

      public double getAlphaWOffset()
      Returns the Wishart degrees-of-freedom offset above the embedded dimension.
      Returns:
      alphaWOffset, where alpha_w = p + alphaWOffset.

    • setAlphaWOffset

      public void setAlphaWOffset(double alphaWOffset)
      Sets the Wishart degrees-of-freedom offset; must exceed 1.
      Parameters:
      alphaWOffset - alphaWOffset, where alpha_w = p + alphaWOffset.

    • getDiscreteInteractionOrder

      public int getDiscreteInteractionOrder()
      Returns the discrete interaction order.
      Returns:
      the maximum number of distinct discrete parents whose indicators are multiplied; 1 = additive.

    • setDiscreteInteractionOrder

      public void setDiscreteInteractionOrder(int discreteInteractionOrder)
      Sets the discrete interaction order: 1 for the additive parent design (the default, score-equivalent), 2 for pairwise interactions among discrete parents, and so on; an order at least the number of discrete parents of a family gives the saturated design. Orders above 1 are not score-equivalent; see the class Javadoc.
      Parameters:
      discreteInteractionOrder - the order; must be at least 1.

    • getTruncationLimit

      public int getTruncationLimit()
      Returns the truncation limit of the basis expansion.
      Returns:
      the truncation limit.

    • getEmbeddedDimension

      public int getEmbeddedDimension()
      Returns the total number of embedded columns (the dimension of the Normal-Wishart prior).
      Returns:
      the embedded dimension.

    • getEmbedding

      public Map<Integer, List<Integer>> getEmbedding()
      Returns a copy of the embedding (variable index to embedded column indices) the score is using.
      Returns:
      the embedding.

    • toString

      public String toString()
      A string representation of the score.
      Specified by:
      toString in interface Score
      Overrides:
      toString in class Object
      Returns:
      This string.

    • getMissingValueSupport

      public MissingValueSupport getMissingValueSupport()
      Declares what this score can do, natively, with data containing missing values. The default is MissingValueSupport.NONE, meaning that missingness must be handled upstream (e.g., by imputation, or by supplying an EM-estimated covariance matrix if the score consumes one); scores that handle missing values themselves should override this.

      TESTWISE: constructed with MissingDataSpec.testwise(), each family is scored on the rows complete on that family's embedded columns.

      Specified by:
      getMissingValueSupport in interface Score
      Returns:
      This support level.