Class TrainedDagSimulatorGNM2

java.lang.Object
edu.cmu.tetrad.sem.TrainedDagSimulatorGNM2
public final class TrainedDagSimulatorGNM2 extends Object

Trained DAG simulator (GNM): learn local mechanisms with non-additive noise and resimulate

This class is a “train-then-resimulate” simulator: given an observed DataSet and a user-supplied acyclic Graph (treated as a DAG), it learns a local conditional mechanism for each node and then generates new samples by running the DAG forward in topological order.

Primary motivation. The purpose is to construct realistic-looking synthetic datasets anchored to an observed dataset while making the assumed causal structure explicit. Because the mechanisms are learned from real data and noise is bootstrapped, substantially different DAGs can yield resimulated data with similar marginals and pairwise structure; however, scoring the resulting data with the wrong graph should degrade in a systematic way. This helps separate “looks plausible” from “fits the causal structure.”

Model family (GNM)

For each node Y with parents Pa(Y), the fitted mechanism is a general-noise model

  Y = g(Pa(Y), e)

where e is a bootstrapped noise term and g is learned by a small neural network that allows the noise to enter non-additively. One simple realization is a two-stage fit:

  1. Fit μ(x) ≈ E[Y | x] using an MLP on parent features x.
  2. Compute residuals e = y - μ(x) on the training rows, bootstrap e, and train a second network to predict y from (x, e).

At simulation time, sample e by bootstrap and generate y = g(x, e).

Mixed data support

  • Continuous child: uses the general-noise mechanism described above; noise values are bootstrapped (optionally stratified by discrete-parent signatures) and injected as an explicit input to g.
  • Discrete child: uses a softmax classifier; optionally mixes unconditional base rates with parent-conditional probabilities to “turn down” parent influence.

Parent encoding

  • Continuous parents enter as z-scored scalars.
  • Discrete parents enter as one-hot blocks (with a configurable maximum number of levels).

Missingness

Training is done node-by-node using only rows where the child and all of its parents are observed. Rows with any missing among {Y} ∪ Pa(Y) are skipped for that node. Simulation produces complete samples given the learned mechanisms.

Notes and limitations

  • This is intentionally a lightweight, dependency-minimal mechanism learner (single hidden layer, SGD, L2 decay), intended for simulation fidelity and portability rather than best-in-class predictive modeling.
  • Because the simulator runs forward under the supplied DAG, unrealistic samples may occur when simulated parent configurations leave the support of the training data (extrapolation). Optional diagnostics may warn when parent z-scores become extreme.
  • The GNM is strictly more expressive than the ANM: it can represent non-additive effects of noise on the child given parents, while still using bootstrapped noise anchored to the observed dataset.

  • Constructor Details

    • TrainedDagSimulatorGNM2

      public TrainedDagSimulatorGNM2(DataSet data, Graph dag, TrainedDagSimulatorGNM2.Params params)
      Constructs a new instance of the TrainedDagSimulatorGNM class. This simulator utilizes a directed acyclic graph (DAG) representation and corresponding data to model variable relationships and simulate values based on learned mechanisms.
      Parameters:
      data - A DataSet object containing the variables and observations to be utilized in the simulation. Must not be null.
      dag - A Graph object representing the structure of the DAG to be used. The DAG must be acyclic and must also not be null.
      params - An optional Params object containing additional configuration parameters for the simulator. If this parameter is null, default parameters will be used.
      Throws:
      NullPointerException - If data or dag is null.
      IllegalArgumentException - If dag contains cycles (i.e., is not a valid DAG).

  • Method Details

    • safeGetInt

      public static int safeGetInt(DataSet data, int row, int col)
      Safely retrieves an integer value from the specified DataSet at the given row and column. If the cell contains a non-integer but finite value, it is rounded to the nearest integer. For non-finite values (e.g., NaN or infinities), a default value of -1 is returned.
      Parameters:
      data - The DataSet object from which the value is retrieved. Must not be null.
      row - The row index of the value to retrieve. Must be a valid index within the dataset.
      col - The column index of the value to retrieve. Must be a valid index within the dataset.
      Returns:
      The integer value at the specified cell, or -1 if the cell contains a non-finite value.

    • getFitReportText

      public String getFitReportText()
      Human-readable report (one block per node).
      Returns:
      A string containing

    • getNodeReports

      public List<TrainedDagSimulatorGNM2.NodeReport> getNodeReports()
      Structured per-node reports.
      Returns:
      An unmodifiable list of node reports, each containing fit metrics for a node.

    • writeFitReportTxt

      public void writeFitReportTxt(File file) throws IOException
      Writes a human-readable textual representation of the fit report to the specified file. The report contains information about the trained DAG simulator, including parameters and per-node reports on training fit metrics.
      Parameters:
      file - The target file where the fit report will be written. Must be writable and not null.
      Throws:
      IOException - If an error occurs while writing to the file.

    • fit

      public void fit()
      Fit one mechanism per node given its parents in the supplied DAG.

    • simulate

      public TrainedDagSimulatorGNM2.SimResult simulate(int nSamples)
      Simulates data by generating continuous and discrete values for all variables in the trained directed acyclic graph (DAG) model. It performs the simulation using a specified number of samples and a seed for random number generation.
      Parameters:
      nSamples - The number of samples to generate during the simulation. Must be a positive integer.
      Returns:
      A SimResult object containing the simulated continuous and discrete values, along with additional metadata related to the DAG and variables used in the simulation.

    • simulate

      public TrainedDagSimulatorGNM2.SimResult simulate(int nSamples, long seed)
      Simulates data by generating continuous and discrete values for all variables in the trained directed acyclic graph (DAG) model. The simulation uses a specified number of samples and a seed for random number generation, ensuring reproducibility.
      Parameters:
      nSamples - The number of samples to generate during the simulation. Must be a positive integer greater than or equal to 1.
      seed - A long value representing the seed for the random number generator. Provides deterministic simulation results when the same seed is used.
      Returns:
      A SimResult object containing the simulated continuous and discrete values, along with metadata about the DAG and the set of variables used in the simulation.
      Throws:
      IllegalArgumentException - If nSamples is less than 1.