Simulate a reusable phased synthetic base population — gsim_simulate

Generates unrelated founders from a packed reference panel using the HAPNEST-compatible historical copying model. Output is always phased HAP/BIM/FAM so that the base population can be reused by independent pedigree simulations.

Usage

gsim_simulate_founders(
  reference,
  n = NULL,
  founder_ids = NULL,
  populations,
  ancestry_weights,
  mutation_age,
  N,
  Ne,
  rho,
  seed,
  output,
  batch_size = NULL,
  threads = 1L,
  overwrite = FALSE
)

Arguments

reference: A gsim_reference() descriptor or HAP/BIM/FAM prefix.
n: Number of founders. Exactly one of n and founder_ids is used. Generated IDs are syn1, syn2, and so on.
founder_ids: Explicit unique character founder IDs in final sample order.
populations: Population labels named by reference FAM IID.
ancestry_weights: Named donor-population probabilities.
mutation_age: Finite mutation ages named by reference BIM ID.
N, Ne, rho: Named HAPNEST population parameters in the committed cumulative-cM founder convention.
seed: Founder-generation seed.
output: Extension-free HAP/BIM/FAM output prefix.
batch_size: Positive requested founder batch size. Internal batches are aligned to packed 64-sample words; NULL uses a bounded default.
threads: Positive native founder worker count.
overwrite: Whether to replace an existing complete triplet.

Value

A lightweight reusable phased base-population descriptor.

Details

Founder H1 copies only donor H1 and founder H2 only donor H2 under the chromosome-label-keyed SplitMix64 contract and strict T < mutation_age filtering. batch_size = NULL requests 8,192 founders; explicit sizes are rounded up to a 64-sample word boundary and the last batch may be partial. Each batch is materialized by static native workers that own disjoint packed words, then written directly to its final HAP sample range. Batch size and thread count do not enter RNG streams. The R global RNG is not used.