How it works
The superpopulation
Covariates come from a Gaussian copula structured as a DAG: every variable has a latent standard normal; those without parents are jointly normal with the scenario’s correlations, the others are linear in their parents’ latents (standardised path coefficients) plus noise. Each latent is mapped to its marginal by the quantile function (NORTA): exact marginals (truncated to their range if given) with the intended dependence. Rules then tie variables together: probabilities that depend on other variables, structural values and formulas.
People are generated in chunks of 5000 with seeds derived from the seed, the scenario and the chunk, so person k is the same whatever the design or the sample size, and a student key changes the seed.
Outcomes and calibration
- binary: logistic model; events: Weibull proportional hazards (inverse transform); continuous: linear (optionally on the log scale); counts: Poisson or negative binomial.
- The intercept, or the baseline hazard, is calibrated on 100 000 simulated people so the population has the scenario’s prevalence, rate, risk at a time, median or mean.
- Each person has their own outcome noise, shared by their treated and untreated versions, so trials compare potential outcomes of the same people.
- A numeric effect modified by another variable (
by:) acts on its distance to acenter(the population mean by default), so the modifier has no implied effect of its own; a continuous outcome with a range is drawn from the truncated distribution.
Designs
| design | sampling |
|---|---|
| cross-sectional | the first n people; an event outcome is read as an event within its risk window |
| ecological | whole regions whose means of the variables differ, plus an unexplained region effect; only totals, means and percentages per region are kept (n is not used) |
| case-control | cases (events within a risk window) from as much population as needed, controls from the non-cases, rows in random order |
| matched case-control | controls matched exactly on categorical variables and within a caliper on numeric ones |
| cohort, prognosis | follow-up with administrative censoring, loss to follow-up and staggered entry; competing events as status 2 |
| nested case-control | controls drawn from each case’s risk set in a followed cohort |
| case-cohort | a random subcohort of a followed cohort plus every case |
| diagnostic accuracy | a cross-sectional sample with markers whose AUC is set (binormal), possibly depending on covariates or on disease severity, optionally in assay batches, with spectrum or partial verification bias |
| method comparison | the outcome measured by two methods, B with a bias, a proportional bias and its own error |
| randomised trial | permuted blocks, treatment effect on the outcome, follow-up for events, optional interim looks |
| cluster randomised trial | arms randomised by cluster, a cluster random effect set by the intraclass correlation |
| 2×2 factorial | two interventions randomised independently, optional interaction |
| 2×2 crossover | sequences AB/BA, within-subject correlation, period and carryover effects |
| longitudinal trial | baseline and repeated visits, dropout that depends on the last value seen (missing at random) |
| before-after | everybody treated, measured before and after; optional entry above a percentile (regression to the mean) |
The answer key
The true model lists the direct effects used. The total effect of a variable that acts through others (its descendants in the structure and the rules) is the regression of the outcome on the variable and on every variable it does not cause, in a simulated population of 40 000 to 200 000 people: a valid adjustment set of the diagram, which leaves the mediators out. Where nothing the variable causes acts on the outcome, the total effect is the direct one.
The expected estimates are the average of three large studies of the same design (one for matched case-control, whose matching is slow): 40 000 rows, more for a rare outcome so that each has about 5000 events, up to 300 000; 1500–3000 cases for case-control designs; 200 regions for an ecological study. Each is analysed with the model a student would fit: logistic, conditional logistic, Cox, linear (with subject effects in a crossover, a mixed model for a longitudinal trial) or Poisson; crude for each variable, adjusted for all measured ones, and adjusted for the measured variables each one does not cause (Adjusted (DAG)). Ratios are averaged on the log scale; the note under the table gives the Monte Carlo uncertainty of the average.
Trials’ absolute effects come from the potential outcomes of 100 000 people under every arm; diagnostic accuracy at a cut-off is true in a clean population of 100 000 and expected in a large study with the same biases.
Source
The engine is plain R (R/engine_*.R), independent of jamovi and tested with testthat; the options panel is tested by driving jamovi in Docker with Playwright. Code: github.com/victor-moreno/jamovi-studysim.