Class ObservationalStudySimulation
java.lang.Object
edu.cmu.tetrad.algcomparison.simulation.ObservationalStudySimulation
- All Implemented Interfaces:
Simulation, HasParameters, ProvidesKnowledge, TetradSerializable, Serializable
Simulates data with the anatomy of a real observational scientific dataset (the archetype is
the Algerian Forest Fires dataset, but with all complications defaulted off this is a plain
mixed-data cross-sectional study). Variables come in roles:
- Context variables (C1, ...): exogenous drivers -- weather, season, region, demographics. A fraction osTypePropContextDiscrete are discrete (region-like, osTypeNumCategories levels); the rest are continuous. In serial mode, continuous context follows a stationary AR(1) process with coefficient osSerialArCoef, and discrete context follows a sticky Markov chain. Optionally, osGraphNumHiddenContext additional context variables influence the system but are OMITTED from the dataset (latent confounders); they appear in the true graph as latent nodes, so FCI-style evaluation is possible.
- System variables (S1, ...): a causal DAG among themselves (average degree osGraphAvgSystemDegree), with context parents, monotone transmission nonlinearity (osFormNonlinearity), and heterogeneous non-Gaussian noise. A fixed count round(osTypePropSystemDiscrete * osGraphNumSystem) of them, chosen at random, are DISCRETE (osTypeNumCategories levels): generated from their parents through softmax logits, entering their children through per-category shifts, so a discrete variable can sit inside the system with both parents and children - the case in which conditional-Gaussian and degenerate-Gaussian treatments differ. Discrete system variables are never ordinalized or censored; in serial mode they have a sticky self-lag (previous value kept with probability equal to the self-lag coefficient) and no cross-lag edges; in panel mode the subject effect is a per-category shift on their logits. In serial mode each system variable has a self-lag, and cross-lag edges (probability osSerialPropCrossLag per ordered pair) allow honest representation of feedback as X{t-1} -> Y{t}, Y{t-1} -> X{t}.
- Index variables (I1, ...): near-deterministic functions (noise osFormIndexNoise) of system variables and EARLIER INDEX VARIABLES (chains like ISI/BUI -> FWI). In serial mode each index is a recursive accumulator I{t} = delta I{t-1} + g(parents{t}) + noise, with memory delta drawn per index from [osSerialIndexMemoryLow, osSerialIndexMemoryHigh] -- heterogeneous drought-code-style memory, making indices MORE serially dependent than their drivers.
- Outcome variables (Y1, ...): depend on system, index, and context variables, with pairwise interactions (weight osFormInteraction). If osTypeDiscreteOutcome, outcomes are discrete via softmax logits (fire/no-fire style).
- Ordinalization (osDegradeOrdinalizeProp): that fraction of system variables is generated continuous but RECORDED as ordered categories at random cutpoints -- measurement coarsening, reproducing the ordinal nominal-coding pathology. The true graph is the graph of the underlying continuous system; the coarsening is measurement, exactly as with real ordinal data.
- Serial dependence (osSerialMaxLag): if greater than 0, one time series per subject is generated and the TRUE GRAPH IS A TimeLagGraph with that maximum lag, following the TimeSeriesSemSimulation convention, so lag-data and cross-lag tier machinery apply. Self-lags, AR(1) context, and index accumulators act at lag 1; each cross-lag edge acts at a lag drawn uniformly from 1..osSerialMaxLag. The contemporaneous summary graph is available from getContemporaneousGraph(index). If 0, rows are i.i.d. and the true graph is an ordinary DAG.
- Censoring (osDegradeCensorProp, osDegradeCensorQuantile): that fraction of the continuous, non-ordinalized system and outcome variables is censored at a detection limit -- values beyond the limit are recorded AT the limit (side chosen at random). Rows are kept; this is measurement, not selection, and the true graph is unchanged.
- Missingness (osDegradeMissingMechanism, osDegradeMissingProp): cells of system, index, and outcome variables are marked missing (NaN, or the discrete missing value) at an exact per-column rate. "mcar" is independent of everything; "mar" is driven by the first observed context variable, which is always fully observed; "mnar" is driven by the cell's own underlying value.
- Panel structure (osPanelNumSubjects): the sample is divided into that many independent subjects (replicates of the same system, sampleSize / osPanelNumSubjects rows each). Each subject has a random intercept on the system variables, with standard deviation osPanelSubjectShiftSd, which acts as a subject-level latent confounder in the pooled data. The intercept is a pure offset on the variable that owns it, so within-subject centering removes it there; it acts as a confounder that centering cannot remove only where it reaches a child through a nonlinear transmission map (osFormNonlinearity). Larger shifts move subjects further along that map; larger nonlinearity bends the map more; either makes the panel structure harder to correct for. By default the subjects are CONCATENATED into one dataset per run with the structure undeclared, as panel data usually arrive; subject boundaries are then available from getSubjectStarts(index), and in serial mode lagging must not cross them. Two options change the emission. If osPanelEmitSubjectColumn, a discrete bookkeeping column named SUBJECT is appended to the stacked dataset (the analogue of deEmitConfigColumn); it is not a variable of the system and is not in the true graph, so it should be excluded from search or used as a grouping/tier variable. If osPanelEmitSubjectsAsDataSets, each subject is instead emitted as its own data model sharing the run's true graph, so getNumDataModels() is numRuns * osPanelNumSubjects; this is the convention MultiDataSetAlgorithm implementations such as IMaGES consume, and Comparison will pool them. Note that Comparison draws its pooled selection from ALL data models, so with numRuns greater than 1 and differentGraphs on, subjects of different runs (with different graphs) would be pooled; use numRuns = 1 or differentGraphs off in that mode. SUBJECT is not appended in per-subject mode, where it would be constant.
NOTE: the random graph passed to the constructor is IGNORED; the role structure is generated internally.
- Author:
- josephramsey
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs an ObservationalStudySimulation. -
Method Summary
Modifier and TypeMethodDescriptionvoidcreateData(Parameters parameters, boolean newModel) Creates simulated data and associated graphs based on the given parameters.getContemporaneousGraph(int index) Returns the contemporaneous summary graph for the given run (equal to the true graph in non-serial mode).getDataModel(int index) Returns the data model at the specified index.Returns the data type of the data set.Returns the description of the simulation.getKnowledge(int index) Returns the design-implied knowledge for the given data model: tiers by role, context (C) before system (S) before indices (I) before outcomes (Y), with the SUBJECT bookkeeping column, when emitted, in a tier of its own before all of these (its fixed-effects reading).intReturns the number of data models.Retrieves the parameters required for the simulation.Class<? extends RandomGraph> Returns the random graph class used in the simulation (ignored for structure).Returns the short name of the simulation.Class<? extends Simulation> Returns the class of the current simulation.int[]getSubjectStarts(int index) Returns the subject start row indices for the given data model.getTrueGraph(int index) Returns the true graph at the specified index: a DAG, or a TimeLagGraph with maximum lag 1 in serial mode.
-
Constructor Details
-
ObservationalStudySimulation
Constructs an ObservationalStudySimulation. The given random graph is ignored; the role structure is generated internally from parameters.- Parameters:
graph- the RandomGraph object (ignored).
-
-
Method Details
-
createData
Creates simulated data and associated graphs based on the given parameters.- Specified by:
createDatain interfaceSimulation- Parameters:
parameters- The parameters used to control the simulation process.newModel- A flag indicating whether a new model should be created.
-
getContemporaneousGraph
Returns the contemporaneous summary graph for the given run (equal to the true graph in non-serial mode).- Parameters:
index- the run index.- Returns:
- the contemporaneous graph.
-
getKnowledge
Returns the design-implied knowledge for the given data model: tiers by role, context (C) before system (S) before indices (I) before outcomes (Y), with the SUBJECT bookkeeping column, when emitted, in a tier of its own before all of these (its fixed-effects reading). The random structure within a role - the system DAG, which indices feed which - is NOT encoded; that is what a search is for.- Specified by:
getKnowledgein interfaceProvidesKnowledge- Parameters:
index- the data model index.- Returns:
- the knowledge.
-
getSubjectStarts
public int[] getSubjectStarts(int index) Returns the subject start row indices for the given data model. In serial mode, lagging must not cross these boundaries. When osPanelEmitSubjectsAsDataSets is on, each data model is a single subject and this returns {0}.- Parameters:
index- the data model index.- Returns:
- the subject start rows.
-
getTrueGraph
Returns the true graph at the specified index: a DAG, or a TimeLagGraph with maximum lag 1 in serial mode.- Specified by:
getTrueGraphin interfaceSimulation- Parameters:
index- The index of the desired true graph.- Returns:
- The true graph at the specified index.
-
getNumDataModels
public int getNumDataModels()Returns the number of data models.- Specified by:
getNumDataModelsin interfaceSimulation- Returns:
- The number of data sets to simulate.
-
getDataModel
Returns the data model at the specified index.- Specified by:
getDataModelin interfaceSimulation- Parameters:
index- The index of the desired simulated data set.- Returns:
- The data model at the specified index.
-
getDataType
Returns the data type of the data set.- Specified by:
getDataTypein interfaceSimulation- Returns:
- Mixed in general (the actual composition depends on the parameters).
-
getDescription
Returns the description of the simulation.- Specified by:
getDescriptionin interfaceSimulation- Returns:
- a short, one-line description of the simulation.
-
getShortName
Returns the short name of the simulation.- Specified by:
getShortNamein interfaceSimulation- Returns:
- The short name of the simulation.
-
getParameters
Retrieves the parameters required for the simulation. Graph parameters are omitted since the structure is generated internally.- Specified by:
getParametersin interfaceHasParameters- Specified by:
getParametersin interfaceSimulation- Returns:
- A list of String names representing the parameters.
-
getRandomGraphClass
Returns the random graph class used in the simulation (ignored for structure).- Specified by:
getRandomGraphClassin interfaceSimulation- Returns:
- The class of the random graph.
-
getSimulationClass
Returns the class of the current simulation.- Specified by:
getSimulationClassin interfaceSimulation- Returns:
- The simulation class.
-