# Simulated whole-genome cohort: frozen model, pilot pending

Status on 2026-10-21: assembly acquisition is running for 52 Arab APR and nine
Saudi JASAPAGE donors. The simulator, source quality profiles and wrapper are
frozen and have passed bounded fixtures. The APR-F full-genome simulation pilot
has been submitted as Slurm job 54157112, using eight threads and 15× per
haplotype. Pilot validation, full-cohort simulation expansion, caller execution
and scoring remain pending. The completed
86-donor empirical-read benchmark is documented in [RESULTS.md](RESULTS.md).

## Design and source binding

The simulation will generate NovaSeq X Plus-style paired-end 150-base reads
from both donor-bound full haplotype assemblies. Each haplotype contributes an
expected 15× depth, giving approximately 30× total diploid depth relative to
one haploid genome. For haplotype lengths G1 and G2, expected sequenced bases
are 15 × (G1 + G2), corresponding to 15 × (G1 + G2) / 300 read pairs before
simulator rounding, contig exclusions and sequence rejection. Observed output
and recruitment depth will be reported separately from target depth.

The acquisition array, job 54156332, was submitted for 122 full assemblies from
61 intended donors. Source-binding pilot jobs 54156786 and 54156787, with
remaining bindings submitted as job 54156788, check assembly provenance. A donor
manifest must bind each complete assembly to its
public source, original haplotype label, verified public-label crosswalk and
checksums before simulation. Regional HLA sequences support reference-label
construction; full assemblies supply the simulation's off-target sequence and
recruitment challenge.

Saudi WGS labels remain disputed. All 13 APR entries labelled WGS in the source
audit were explicitly Hi-C. Their molecule-sampling design differs from ordinary
paired-end WGS. This experiment therefore has its own simulated-read provenance.
The 61 donors also contributed sequences to some developmental catalogues;
training/reference exposure and any donor/family exclusions must be reported
for each comparison.

## Frozen simulator and quality model

[simulation/SIMULATION_RUNTIME.json](simulation/SIMULATION_RUNTIME.json) pins
unmodified **ART-modern v1.3.2**, its upstream source commit, release archive,
binary and wrapper checksums. The separate
[baseline version manifest](SOFTWARE_DATABASES.json) remains unchanged.

Quality profiles come from the first **100,000 paired records** of
**ERR15382247**, study **PRJEB90663**, a PCR-free human WGS run on **Illumina
NovaSeq X Plus**. The primary study is linked by
[DOI 10.1093/nargab/lqag053](https://doi.org/10.1093/nargab/lqag053).
Source reads are 151 bases; the first 150 cycles form separate mate profiles
with observed Phred bins **2, 12, 24 and 40**. The
[profile receipt](simulation/PROFILE_RECEIPT.json) binds original read URLs,
record-prefix hashes, cycle histograms and the two exact profile files.
[fetch_profile.py](simulation/fetch_profile.py) documents their construction.

ART samples the empirical mate/cycle quality marginals independently and derives
substitution probabilities as 10^(−Q/10). Insertion and deletion rates are
**zero**, an explicit model assumption. Fragment lengths use mean **350 bases**
and standard deviation **50 bases**, also a prespecified assumption. These
parameters model quality-driven substitutions and an assumed fragment
population. Empirical context effects, homopolymer errors, indels, PCR/GC
coverage bias and cross-cycle correlations remain outside this model. A single
run's prefix can reflect its initial tiles and limits instrument-wide
representativeness.

Fragments remain within FASTA records. ART skips contigs shorter than 250 bases
and rejects fragment lengths that exceed a record. With maximum read-end N
count zero, sequenced ends containing Ns are rejected and retried; Ns inside an
unsequenced insert can remain. Large-N records can underproduce when the
simulator reaches its failure budget, so full-genome QC must inspect achieved
yield, contig counts and stderr before cohort expansion.

## Portable runtime and reproduction

The `simulation/` directory keeps the contract, wrapper and profiles together,
matching the contract's relative paths. The upstream binary is downloaded
separately; it is excluded from this repository. On a compatible Linux x86-64
host, run from the repository root:

```bash
curl --fail --location https://github.com/YU-Zhejian/art_modern/releases/download/1.3.2/build_rel_with_dbg_alpine-x86_64.tar.gz -o /tmp/art-modern-1.3.2.tar.gz
printf '%s  %s\n' 1d443209fbf773424e6768b5f050564b56149ba83c354e873b48cf5d55618f96 /tmp/art-modern-1.3.2.tar.gz | sha256sum -c -
mkdir -p simulation/bin-1.3.2
tar -xzf /tmp/art-modern-1.3.2.tar.gz -C simulation/bin-1.3.2
printf '%s  %s\n' 24ba37808374e4924bcd865c0947d042cc30540af1ed6d9f83de5ef437c2e193 simulation/bin-1.3.2/art_modern | sha256sum -c -
python3 simulation/simulate_haplotype.py \
  --input /path/to/DONOR_hap1.fa \
  --output-prefix results/simulation/DONOR/hap1 \
  --name-prefix DONOR_hap1 --seed 42521 --threads 8 --coverage 15
```

The command illustrates one haplotype; 42521 is an example seed. Cohort seeds
will be fixed per donor/haplotype in the execution manifest before generation.
The wrapper accepts positive signed-32-bit seeds, synchronizes ART's interleaved
mate output, refuses existing outputs and writes paired FASTQ plus a completion
receipt. A failed run can leave partial outputs, which require inspection before
retry. The completion receipt records the actual input, binary, profile, wrapper
and output hashes, commands, pair count, quality histograms and elapsed time.

The [bounded validation](simulation/TOY_VALIDATION.json) generated 20,000 pairs
at PE150 and 30× depth on its fixture, retaining all four quality bins. Its
observed substitution rate was 0.001421 versus a quality-predicted rate of
0.001456, and its fragment mean/SD were 349.53/50.30 bases. This validates the
bounded model fixture; the full-genome pilot remains the next gate.

A [bounded repeated-run check](simulation/REPRODUCIBILITY_CHECK.json) with seed
42521 and two threads produced identical sorted records, including read names,
sequences and qualities, for each mate. Parallel interleaving changed record
order, and Python gzip metadata changed compressed bytes. Preserve actual
output checksums per execution; fixed seeds and thread counts support the
record-content comparison tested by this fixture.

## Benchmark execution and reporting

Caller configurations remain pinned in [SOFTWARE_DATABASES.json](SOFTWARE_DATABASES.json),
including historical database-version gaps and SpecHLA's mixed annotation and
mapping databases. Supported-resolution comparisons will retain matched
eligible donor–locus pairs, separate completion/call/accuracy counts and HLA*LA's
common-G endpoint. Read recruitment, source exposure, reference-label admission,
recovery rules and planned contrasts will be recorded before scoring.

The full-genome pilot must pass input identity, paired-read integrity,
read-length/quality checks, achieved-yield assessment and resource checks before
cohort expansion. Generated reads, predictions and scores will have separate
release manifests. The published empirical results retain their existing frozen
artifacts and interpretation.