BAMulator

BAMulator simulates variants directly into existing BAM files while preserving the characteristics of the original sequencing data.

Supported variant types include:

• SNVs
• INDELs
• CNVs
• SVs (including balanced and whole-arm translocations)
• Subclonal variants
• Haplotype-based variants

Requirements

Input BAMs must be coordinate sorted and indexed.

Install the Python dependencies and build the simulation engine:

python3 -m pip install -r requirements.txt
make -C src

The wrapper expects Linux-compatible binaries at:

bwa/bwa
samtools/samtools

Optional phasing also requires java, bcftools, bgzip, and tabix on PATH.

---

Quick start

Variants can be provided in three ways:

1. Use an existing VCF, BCF or BEDPE
2. Generate a BAMulator config using the included scripts
3. Write a BAMulator TSV manually

For most use cases, the first two options are recommended.

Use an existing VCF

python3 bamulator.py \
  --variants variants.vcf.gz \
  --sample_bam sample.bam \
  --reference hg38.fa \
  --output simulated

The main output is:

simulated/sample_merged.bam

VCF, compressed VCF, BCF and BEDPE inputs are supported.

For multi-sample VCF/BCF files, use --sample_map to associate each sample with its BAM.

---

Generate variant configurations

BAMulator includes scripts to automatically generate variants from a BAM directory and a gene-panel BED.

Generate SNVs and indels

For example, generate 20 small variants:

python3 scripts/generate_indels_config.py \
  --indir /path/to/bams \
  --bed panel.bed \
  --genome hg38.fa \
  --num_variants 20 \
  --proportions 1 \
  --output variants.tsv

Then simulate them:

python3 bamulator.py \
  --variants variants.tsv \
  --reference hg38.fa \
  --output simulated

Exactly one of --indir or --list must be provided.

The SNV, insertion, deletion and delins rates must sum to 1.

Generate structural variants

For example, generate a set containing only deletions and duplications:

python3 scripts/generate_sv_config.py \
  --indir /path/to/bams \
  --bed panel.bed \
  --num_variants 20 \
  --proportions 1 \
  --deletion_rate 0.5 \
  --duplication_rate 0.5 \
  --inversion_rate 0 \
  --translocation_rate 0 \
  --output variants.tsv

Then run:

python3 bamulator.py \
  --variants variants.tsv \
  --reference hg38.fa \
  --output simulated

Non-zero SV rates are automatically normalized.

---

Manually define variants

Manual TSV files are useful when you want to simulate specific variants.

Small variant example

SAMPLE	CHROM	POS	REF	ALT	TYPE	CLONE	CLONAL_PROPORTION	GENOTYPE	ADDITIONAL_INFO
sample.bam	chr7	55259515	T	G	snv	clone1	1.0	0/1	EGFR_p.L858R

Run:

python3 bamulator.py \
  --variants variants.tsv \
  --reference hg19.fa \
  --output simulated

Supported small-variant types are:

snv
insertion
deletion
delins

POS is 1-based.

CLONAL_PROPORTION controls the fraction of the sample carrying the variant. For example:

1.0   clonal
0.5   50% of the sample
0.2   20% of the sample

An optional HAPLOTYPE column can be used for explicit allele-specific simulation.

---

Structural variant example

Structural variants use a different TSV format.

Example heterozygous deletion:

SAMPLE	CHR1	START1	END1	CHR2	START2	END2	SVTYPE	SVID	PLOIDY	SV_MECHANISM	NTINS	HOMOLOGY	CLONE	CLONAL_PROPORTION	ADDITIONAL_INFO	HAPLOTYPE
sample.bam	chr9	21970277	21975386	.	.	.	DEL	CDKN2A_del	1	random	.	.	clone1	1.0	.	1

Supported structural variant types are:

DEL
DUP
INV
BALANCED_TRANSLOCATION
WHOLE_ARM_TRANSLOCATION

Common PLOIDY values:

PLOIDY	Meaning
0	Homozygous deletion
1	Heterozygous deletion
2	Balanced event
3	One-copy gain
4	Two-copy gain

Native TSV breakpoint coordinates are 1-based.

For point breakpoints such as translocations:

START1 = END1
START2 = END2

---

Cancer presets

Ready-made cancer variant configurations are available under:

scripts/presets/hg19/
scripts/presets/hg38/

For example:

python3 bamulator.py \
  --variants scripts/presets/hg19/lung_cancer_small_variants.tsv \
  --reference hg19.fa \
  --output simulated

Edit the SAMPLE column in the preset before running.

Available preset groups include:

• NSCLC
• melanoma
• colorectal cancer
• breast cancer
• CNS / GBM
• AML

Some panels have separate files for small variants and structural variants.

Variants that cannot be simulated together because they occupy the same position are stored in companion *_alternates.tsv files.

---

Combining small and structural variants

Small variants and structural variants cannot currently be simulated in the same BAMulator run.

To simulate both, run BAMulator twice.

First simulate the structural variants:

python3 bamulator.py \
  --variants svs.tsv \
  --reference hg38.fa \
  --output sv_out

Then use the resulting BAM as the input for the small-variant configuration:

sv_out/sample_merged.bam

and run BAMulator again:

python3 bamulator.py \
  --variants snvs.tsv \
  --reference hg38.fa \
  --output final

---

Reproducible simulations

Use --seed to reproduce the same stochastic simulation:

python3 bamulator.py \
  --variants variants.tsv \
  --reference hg38.fa \
  --output simulated \
  --seed 42

The effective seed is logged for every run.

---

Outputs

A typical run produces:

sample_merged.bam
sample_merged.bam.bai

sample_simulated.bam
sample_simulated.bam.bai

sample_unsimulated.bam

sample_simulated_R1.fq
sample_simulated_R2.fq

sample_coverage_warnings.tsv

bamulator.truth.vcf

The main downstream file is:

sample_merged.bam

bamulator.truth.vcf contains the variants requested for the simulation.

sample_coverage_warnings.tsv reports variants with insufficient source coverage.

Check this file whenever a configured variant does not appear in the output.

Variants with zero or fewer than 10 overlapping read pairs are reported as coverage warnings.

---

Phasing

Optional phasing can be enabled with:

--phase_snvs

Example:

python3 bamulator.py \
  --variants deletions.tsv \
  --reference hg38.fa \
  --output simulated \
  --phase_snvs \
  --input_vcf_list vcfs/ \
  --genome_version hg38 \
  --map_dir maps/ \
  --ref_dir reference-panels/

Phasing allows nearby heterozygous SNVs to be retained on consistent parental haplotypes.

Supported genome labels are:

hg19
b37
hg38
b38

The optional HAPLOTYPE field can explicitly assign variants to:

maternal
paternal
both

Nearby variants assigned to the same parental haplotype remain in cis, while variants assigned to opposite haplotypes remain in trans.

---

Current limitations

• Small variants and structural variants cannot be mixed in one run.
• Mixed small/SV VCF or BCF inputs are rejected.
• Background phasing currently supports SNVs but not background indels.
• HOMOLOGY is parsed but is not currently applied to simulated sequences.
• Phasing currently processes chromosomes 1–22 and X.
• --suffix and --max_reads are accepted for compatibility but currently do not modify the corresponding engine behavior.
• --minins and --maxins are accepted by the SV generator but currently unused. Breakpoint NTINS length is controlled with --ntmin and --ntmax.