umx_make_GxE_data: Simulate ground-truth Purcell GxE twin data for benchmarking...

In umx: Structural Equation Modeling and Twin Modeling in R

Simulate ground-truth Purcell GxE twin data for benchmarking umxGxE

Description

Generates a wide twin data frame with known path coefficients in the Purcell (2002) moderated ACE form used by umxGxE(): \(a_i = a + a_m M\), and similarly for \(c\) and \(e\).

Usage

umx_make_GxE_data(
  nMZpairs = 2500L,
  nDZpairs = 2500L,
  a = 0.5,
  c = 0.3,
  e = 0.6,
  am = 0.15,
  cm = 0,
  em = 0,
  betaAge = NULL,
  targetAgeCor = 0.2,
  seed = 1L,
  sharedModerator = TRUE,
  sharedAge = TRUE,
  dzAr = 0.5,
  mu = 0,
  betaMod = 0,
  ageMean = 40,
  ageSd = 10,
  clipModerator = TRUE
)

Arguments

nMZpairs	Number of MZ pairs (default 2500).
nDZpairs	Number of DZ pairs (default 2500; total N = 5000 pairs).
a	Main additive path at \(M = 0\) (default 0.50).
c	Main common-environment path at \(M = 0\) (default 0.30).
e	Main unique-environment path at \(M = 0\) (default 0.60).
am	Additive moderation slope \(a_m\) / a-prime (default 0.15).
cm	Common-environment moderation slope (default 0).
em	Unique-environment moderation slope (default 0).
betaAge	Mean slope of age on outcomeAge. If NULL (default), chosen so that the correlation r(outcomeAge_T1, age_T1) is approximately targetAgeCor.
targetAgeCor	Target correlation between outcomeAge and age when calibrating betaAge (default 0.2).
seed	Random seed (default 1).
sharedModerator	If TRUE (default), one moderator draw per family.
sharedAge	If TRUE (default), one age draw per family.
dzAr	DZ additive genetic correlation (default 0.5).
mu	Intercept for both outcomes (default 0).
betaMod	Mean effect of moderator on both outcomes (default 0).
ageMean	Mean of age in years (default 40).
ageSd	SD of age (default 10).
clipModerator	If TRUE (default), clip moderator draws to the interval from -3 to 3.

Details

Two outcomes share the same latent ACE draws and moderation:

outcome

GxE only (no age mean effect).

outcomeAge

Same as outcome plus a mean effect of age calibrated so the sample correlation with age is approximately targetAgeCor.

Family-level moderator and age are shared by co-twins (mod_T1 == mod_T2, age_T1 == age_T2) by default.

Value

data.frame with columns zygosity, outcome_T1/T2, outcomeAge_T1/T2, mod_T1/T2, age_T1/T2. Attribute "truth" is a named list of generative parameters (a, c, e, am, cm, em, betaAge_outcomeAge, cor_outcomeAge_age, sample sizes, seed, etc.). Base R and umxGxE ignore attributes on the data frame; use attr(df, "truth") only for comparison to estimates.

References

Purcell, S. (2002). Variance components models for gene-environment interaction in twin analysis. Twin Research, 5, 554-571. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1375/twin.5.6.554")}

See Also

umxGxE(), umx_make_TwinData()

Other Data Functions: noNAs(), prolific_anonymize(), prolific_check_ID(), prolific_read_demog(), prolific_scoring_stub(), umx, umxFactor(), umxGSEM_sim_snps(), umxHetCor(), umx_as_numeric(), umx_cont_2_quantiles(), umx_lower2full(), umx_make_MR_data(), umx_make_TwinData(), umx_make_fake_data(), umx_make_raw_from_cov(), umx_merge_randomized_columns(), umx_polychoric(), umx_polypairwise(), umx_polytriowise(), umx_read_lower(), umx_rename(), umx_reorder(), umx_score_scale(), umx_select_valid(), umx_stack(), umx_strings2numeric()

Examples

df = umx_make_GxE_data(nMZpairs = 200, nDZpairs = 200, seed = 1)
str(df)
truth = attr(df, "truth")
truth$am
truth$a
## Not run: 
m1 = umxGxE(selDVs = "outcome", selDefs = "mod", sep = "_T",
  data = df, mzData = "MZ", dzData = "DZ", tryHard = "yes")

## End(Not run)

umx documentation built on Oct. 11, 2026, 5:07 p.m.