Simulation

Haplotype-based simulation of admixed mosaics from phased founder panels. Requires PyTorch (pip install "snputils[torch]"). OnlineSimulator draws crossover breakpoints from an optional genetic map and returns batched haplotype labels with SNP matrices on CPU or GPU.

Simulation inputs must preserve haplotype phase. Phased VCF, PGEN, or BGEN inputs are appropriate; PLINK1 BED/BIM/FAM files are rejected because they cannot store chromosome-scale phase.

OnlineSimulator

class snputils.simulation.simulator.simulator.OnlineSimulator(snp_data, meta, genetic_map=None, make_haploid=True, window_size=None, store_latlon_as_nvec=False, cp_tolerance=0, ancestry_proportions=None)

Bases: object

A refactored ‘OnlineSimulator’ for haplotype simulation with window-based SNP data.

Core Functionality:

• Simulates admixed haplotypes.

• Supports:

  1. discrete labels (e.g., population codes), or

  2. lat/lon (converted to n-vectors) stored per window of SNPs.

Example usage:

sim = OnlineSimulator(
    snp_data=my_snpobj,
    meta=metadata_df,
    genetic_map=genetic_map_df,  # optional
    ...
)

# Then to simulate:
snps, labels_discrete, labels_continuous, changepoints = sim.simulate(batch_size=32)

simulate_diploid_population(n_individuals, num_generation_max=10, num_generations=None, sample_prefix='SIM')

Simulate a full diploid cohort from ancestry-specific founder haplotypes.

Returns:

genotypes – int8 array with shape (n_snps, n_individuals, 2) samples: sample IDs with shape (n_individuals,) segments: list of per-haplotype (starts, ends, ancestry_codes) arrays

simulate(batch_size=256, num_generation_max=10, balanced=False, single_ancestry=False, device='cpu', pool_method='mode', num_generations=None)

Returns a tuple of:

( batch_snps, final_discrete_labels_window, final_continuous_labels_window )

where:

• batch_snps.shape == (B, D)

• final_discrete_labels_window == (B, n_windows) if discrete was present, else None

• final_continuous_labels_window == (B, n_windows, cdim) if continuous was present, else None

See Analysis for a Python example and the Command-Line Interface simulate subcommand for file-backed batch generation.