Simulate genomic data from an in-memory matrix or a qgg Glist

gsim() simulates genomic data for validation and methodological studies. In Glist mode, causal variants are selected from marker metadata. Selected BED dosages are scanned in bounded blocks for statistics, then accumulated natively for all traits without a complete causal-genotype matrix. Genome-wide genotypes are read in bounded chunks only when compute_sumstats = TRUE.

Usage

gsim(
  Glist = NULL,
  W = NULL,
  ids = NULL,
  rsids = NULL,
  A = NULL,
  architecture = c("bayesc", "bayesr", "major_polygenic", "maf_dependent", "clustered",
    "fixed"),
  nt = 1L,
  h2 = 0.5,
  vg = 1,
  pi = NULL,
  mixture_variances = NULL,
  causal_probability = NULL,
  marker_multipliers = NULL,
  n_causal = NULL,
  beta = NULL,
  alpha = NULL,
  annotation_model = c("none", "sbayesrc"),
  rg = NULL,
  re = 0,
  maf = NULL,
  a = 0,
  b = 0,
  c = 0,
  ld_score = NULL,
  annotation_score = NULL,
  maf_exponent = -0.5,
  block_id = NULL,
  n_hot_blocks = NULL,
  cluster_enrichment = 20,
  n = NULL,
  m = 1000L,
  maf_min = 0.05,
  maf_max = 0.5,
  n_annotations = 0L,
  annotation_types = NULL,
  annotation_prob = 0.1,
  seed = NULL,
  standardize_W = TRUE,
  scale_effects = TRUE,
  return_genotypes = FALSE,
  return_marker_probabilities = TRUE,
  compute_sumstats = FALSE,
  chunk_size = 5000L,
  getG_fun = NULL
)

Arguments

Glist: Optional qgg BED-backed genotype-list object. SNP-major bedfiles, companion bimfiles/famfiles (or matching filename stems), ids, and per-file rsids are required. Physical BIM/FAM identities define offsets and selected order. qgg is needed to construct Glist with gprep, but not for native accumulation from an existing supported object.
W: Optional in-memory genotype matrix. At most one of Glist and W may be supplied. If both are NULL, independent binomial genotypes are simulated.
ids: Optional sample IDs. In Glist mode, n randomly selected IDs are used when ids is NULL and n is smaller than the available sample size.
rsids: Optional eligible marker IDs.
A: Optional marker-by-annotation matrix. Row names, when present, are matched to marker IDs. Binary and continuous columns may be mixed.
architecture: One of "bayesc", "bayesr", "major_polygenic", "maf_dependent", "clustered", or "fixed".
nt: Number of traits.
h2: Target trait heritabilities.
vg: Target genetic variances. Marker effects are rescaled to these realized variances when scale_effects = TRUE.
pi: Mixture probabilities, with the null component first.
mixture_variances: Relative mixture-component variances, with zero first.
causal_probability: Optional scalar or marker-specific probability $q_j$ that marker $j$ is non-null. A marker-specific vector must have unique nonempty names exactly matching the simulation markers. When supplied, these probabilities replace the null mass implied by pi, while pi[-1] / sum(pi[-1]) retains the conditional probabilities of the active mixture components. This is a Bernoulli model and cannot be combined with n_causal, architecture = "fixed", architecture = "clustered", or annotation-driven component probabilities.
marker_multipliers: Optional positive marker-specific relative active-effect variance weights, $w_j$. A scalar is repeated; a marker-specific vector must have unique nonempty names exactly matching the simulation markers and is aligned once to canonical marker order. Direct multipliers cannot be combined with nonzero a, b, or c. The multiplier is applied only to non-null effect draws, separately from component probabilities and the component multiplier. NULL gives unit multipliers when the derived model is not requested. Values are not clipped or normalized. Non-unit multipliers are not defined for architecture = "fixed", where beta supplies realized effects directly.
n_causal: Optional exact number of non-null markers. If supplied, markers are sampled without replacement using their annotation-informed non-null probabilities.
beta: Fixed marker effects for architecture = "fixed".
alpha: Annotation effects, with dimensions ncol(A) by length(pi)-1. Effects act on centered annotations and continuation logits.
annotation_model: "none" or "sbayesrc".
rg, re: Genetic-effect and residual correlation matrices (or scalar off-diagonal correlations for multiple traits).
maf: Optional marker MAF. A scalar is repeated; a marker-specific vector must be named by marker ID. In Glist mode, Glist$maf, aligned through Glist$rsids, supplies MAF when a is nonzero and maf is NULL.
a, b, c: Finite scalar exponents in the marker-specific conditional effect-variance model $w_j=[p_j(1-p_j)]^a r_j^b s_j^c$. All default to zero. The model is requested when any exponent is nonzero.
ld_score: Optional marker LD score $r_j$. A scalar is repeated; a marker-specific vector must be named by marker ID. In Glist mode, Glist$ldscores, aligned through Glist$rsidsLD, is used when b is nonzero and ld_score is NULL. LD scores are not calculated or floored.
annotation_score: Optional single positive scalar annotation score $s_j$ per marker. A scalar is repeated; a marker-specific vector must be named by marker ID. This controls conditional effect variance only and is never inferred from the SBayesRC A matrix.
maf_exponent: For maf_dependent, effect variance is proportional to [2p(1-p)]^maf_exponent before realized-variance calibration.
block_id: Optional marker block labels for clustered.
n_hot_blocks: Number of enriched blocks in the clustered architecture.
cluster_enrichment: Active-odds multiplier in enriched blocks.
n, m: Sample and marker counts when genotypes are simulated. In Glist mode, n = NULL uses all available samples.
maf_min, maf_max: MAF range for simulated genotypes.
n_annotations: Number of annotations to simulate when A is NULL.
annotation_types: Simulated annotation types: "binary" and/or "continuous".
annotation_prob: Probability for simulated binary annotations.
seed: Optional seed.
standardize_W: Whether loaded causal genotypes are standardized.
scale_effects: Whether effects are calibrated to vg.
return_genotypes: Return causal genotype columns in W_causal for in-memory or simulated input. Must be FALSE for bounded Glist input.
return_marker_probabilities: Return the full marker probability surface.
compute_sumstats: Compute marginal GWAS statistics. Glist data are read in chunks for this optional step.
chunk_size: Maximum marker columns requested in each Glist read; capped internally at 64, including optional summary statistics. Transient decoded copies are bounded by this cap, independently of causal count.
getG_fun: Optional deterministic custom reader with the qgg::getG calling convention. Must honor bounded requests and return consistent raw dosages across repeated reads. NULL uses native BED access; unsupported storage errors instead of silently falling back to dense extraction.

Value

A list containing phenotypes, genetic values, residuals, exact marker effects and states, annotation truth, probability surfaces, the complete canonical causal_probability and marker_multipliers vectors, compact provenance under settings$causal_probability and settings$marker_multipliers (including the variance formula, exponents, metadata sources, and alignment), and optional summary statistics. Glist settings$genotype_stream records the backend and buffer capacity. Full marker effects/probability surfaces and optional summary tables still scale with marker count; this is not a constant-memory phenotype workflow.