v2 methylation QC validated on minfiDataEPIC and against sesame (K-026)

beta r 0.99998 vs sesame 1.28.1 (max |dbeta| 0.011), detection calls 99.1% identical,
noob within 0.5% median; replicate r 0.997; all 21 control metrics pass. Spec deviations
recorded (5-field control lines, pOOBAH formula, minfi sheet keys). User guide section.

docs/validation/V2_methylation.md

@@ -0,0 +1,53 @@
+# v2 module validation — methylation control QC (`simurg methyl qc`)
+
+Date: 2026-09-29. Development on the Raspberry Pi; oracle runs on AWS (c7g.xlarge, five short runs, ≈ $0.025).
+Spec: MET-001 … MET-018 (and QC-004/QC-006, QC-062).
+
+## Data
+
+* **minfiDataEPIC** (Bioconductor, Artistic-2.0): 3 EPIC v1 arrays of NA12878 (IDATs + minfi-style sample sheet).
+* **Infinium MethylationEPIC v1.0 B5 manifest (CSV)**: 865 918 probes (142 158 Infinium I: 92 212 red, 49 946 green),
+  635 control beads. Read in 8.6 s on the Pi.
+
+## Delivered
+
+`simurg methyl qc`, `simurg methyl convert-manifest`, `simurg qc controls --array-type methylation`, methylation
+datasets in `simurg qc report`; modules `formats/methyl_manifest.py`, `signal/methyl.py`, `pipeline/methyl.py`;
+the 21 methylation metrics in `qc/controls.py`. User guide: "Methylation arrays".
+
+## Results on minfiDataEPIC
+
+| Check | Result |
+|---|---|
+| Run time, 3 samples, 3 workers (Pi) | 25 s (2.9 s signal processing per sample) |
+| 21 control metrics | all evaluable, all pass the `methylation_epic` profile (e.g. staining green 57, BS conversion I green 13, BS conversion II 5.3, specificity II 24) |
+| Probes passing detection (p < 0.05, analytical CG + SNP probes) | 90.9 %, 91.1 %, 91.3 % |
+| β of the three NA12878 replicates | Pearson r 0.997 – 0.9974 between replicates; bimodal distribution |
+| Sheet `Sample_Group` → PCA colours; outputs of MET-013 | present; folder loads in `qc report` |
+
+## Against the sesame oracle (sesame 1.28.1, same probe set via `probes.tsv`/`controls.tsv`)
+
+`scripts/v2/sesame_oracle.R` + `scripts/v2/methyl_oracle_compare.py`, bead-count masking off on both sides (sesame's
+`min_beads` masks every Infinium II probe because their M address is NA), 865 918 probes per sample:
+
+| Quantity | Agreement (3 samples) |
+|---|---|
+| β values | Pearson r 0.99998; \|Δβ\| median 0.0009, 99th percentile 0.008, max 0.011 |
+| noob-corrected M/U signals | relative difference median 0.5 %, max 5 % |
+| Detection calls at p < 0.05 | 99.0 – 99.1 % identical; passing fraction 91.0 – 91.4 % (simurg) vs 92.0 – 92.3 % (sesame) |
+| Detection p-values | not identical (median \|Δp\| 0.0008) |
+
+The remaining difference is systematic (same size in all three samples) and is not the negative controls: sesame did
+not attach the supplied control table (`negControls` failed, so its background is out-of-band Infinium I signal only),
+and simurg without negative controls is not closer (noob difference 0.56 % instead of 0.53 %). The exact cause is
+open (K-026). For QC use — pass/fail per sample, detection rate, β for a PCA — the agreement is sufficient; simurg's
+methylation numerics are documented as its own [OURS] implementation of the published methods (MET-010), not as a
+bit-exact port.
+
+## Spec deviations (K-026)
+
+* MET-002: the vendor EPIC manifest has a 5th field (`AVG`) on some `NEGATIVE` control lines; ≥ 4 fields are
+  accepted and the first four used. Fewer than 4 still gives `E_METH_CONTROLS_FORMAT`.
+* MET-010: the detection p-value follows sesame's pOOBAH (p = 1 − max(F(M), F(U)), each in its own channel) instead
+  of the ambiguous "1 − ECDF(M + U)", so an open-source oracle exists.
+* MET-004: `Sentrix_ID`/`Sentrix_Position` (minfi/sesame sheets) accepted as a third key-column pair.