Class PlotMatrixMimicSimulator

java.lang.Object
edu.cmu.tetrad.sem.PlotMatrixMimicSimulator
public final class PlotMatrixMimicSimulator extends Object
PlotMatrixMimicSimulator (continuous-only, v1)

Goal: given a continuous dataset X (n x p), simulate a new dataset X' (m x p) such that:

  • Each marginal distribution is approximately preserved (histograms match closely) via inverse empirical CDF mapping.
  • Pairwise dependence structure is mimicked via a Gaussian copula: we compute normal-scores Z from ranks, estimate Corr(Z), then sample multivariate normal with that correlation and map back through empirical quantiles.

Optional "novel mechanism": we can apply a mild nonlinear distortion in latent Gaussian space (still mapped back through empirical marginals), which changes the joint in a controlled way while keeping histograms identical.

Notes:

  • Continuous-only for now (throws if any DiscreteVariable is present).
  • Missing values are handled by listwise deletion across all columns by default.
  • Correlation matrix is regularized with diagonal jitter if Cholesky fails.

Typical usage:

  PlotMatrixMimicSimulator sim = new PlotMatrixMimicSimulator(data);
  sim.setNoveltyStrength(0.15);   // 0.0 = off
  DataSet fake = sim.simulate(2000, 12345L);

  • Constructor Summary

    Constructors
    Constructor
    Description
    PlotMatrixMimicSimulator(DataSet data)
    Constructs a new instance of PlotMatrixMimicSimulator, designed for processing continuous-only datasets and generating matrices used in copula normal-score simulations.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    getNoveltyStrength()
    Getter for noveltyStrength.
    void
    setCholJitter(double cholJitter)
    Getter for cholJitter.
    void
    setCholRetries(int cholRetries)
    Sets the maximum number of retries allowed for the Cholesky decomposition process.
    void
    setListwiseDeleteMissing(boolean listwiseDeleteMissing)
    Setter for listwiseDeleteMissing.
    void
    setNoveltyStrength(double noveltyStrength)
    Setter for noveltyStrength.
    DataSet
    simulate(int m, long seed)
    Simulates a synthetic dataset by sampling from a multivariate normal distribution, applying optional nonlinear distortions, and mapping the latent variables to real values through inverse empirical cumulative distribution functions.

    Methods inherited from class Object

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

  • Constructor Details

    • PlotMatrixMimicSimulator

      public PlotMatrixMimicSimulator(DataSet data)
      Constructs a new instance of PlotMatrixMimicSimulator, designed for processing continuous-only datasets and generating matrices used in copula normal-score simulations. This constructor validates the input dataset and preprocesses it for further computations, such as empirical CDF mappings and rank-based transformations.
      Parameters:
      data - the dataset to be used for the simulation. It must contain only continuous variables, and cannot be null. The dataset should have at least 10 rows after optional listwise deletion of rows with missing values.
      Throws:
      NullPointerException - if the provided dataset is null.
      IllegalArgumentException - if the dataset contains any non-continuous variables, or has fewer than 10 rows after preprocessing.

  • Method Details

    • getNoveltyStrength

      public double getNoveltyStrength()
      Getter for noveltyStrength.
      Returns:
      the novelty strength parameter

    • setNoveltyStrength

      public void setNoveltyStrength(double noveltyStrength)
      Setter for noveltyStrength.
      Parameters:
      noveltyStrength - the novelty strength parameter

    • setListwiseDeleteMissing

      public void setListwiseDeleteMissing(boolean listwiseDeleteMissing)
      Setter for listwiseDeleteMissing.
      Parameters:
      listwiseDeleteMissing - the listwise delete missing flag

    • setCholJitter

      public void setCholJitter(double cholJitter)
      Getter for cholJitter.
      Parameters:
      cholJitter - the jitter parameter

    • setCholRetries

      public void setCholRetries(int cholRetries)
      Sets the maximum number of retries allowed for the Cholesky decomposition process. The provided value is constrained to a minimum of 1 to ensure at least one retry is performed.
      Parameters:
      cholRetries - the maximum number of retries for the Cholesky decomposition; must be a positive integer.

    • simulate

      public DataSet simulate(int m, long seed)
      Simulates a synthetic dataset by sampling from a multivariate normal distribution, applying optional nonlinear distortions, and mapping the latent variables to real values through inverse empirical cumulative distribution functions.
      Parameters:
      m - the number of samples to generate; must be greater than or equal to 1
      seed - the seed for the random number generator to ensure reproducibility
      Returns:
      a DataSet containing the simulated data
      Throws:
      IllegalArgumentException - if the specified number of samples (m) is less than 1