kemal/SimurgArray
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add sanitized Phase-0 research archive under docs/research

Browse Source 
Research notes R1-R4, documentation-study files A-E (source of the
functional spec's `src:` tags) and PGx coverage CSVs, rewritten to use
neutral naming and current project decisions (plan §2).
This commit is contained in:
kemal committed 2026-09-27 16:27:34 +01:00
1 parent 180b6f160a
commit 5695119e9c
12 files changed
+7748
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/research/D_cyto_methyl_pgx.md
+433
View File
@@ -0,0 +1,433 @@
# D — Cloud analysis types, Cytogenetics, Methylation QC, PGx (CNV + star alleles), FAQ, Support
> **Archived Phase-0 study (sanitized copy, see `README.md`).** Written 2026-09-27, before the decisions in
> `SIMURGARRAY_MASTER_PLAN.md` §2. The analysed vendor product is called "the reference product" and its CLI
> `refcli`; its documentation URLs are replaced by `[ref-docs:…]` tokens. Where this file speaks of a clean room,
> legal clearance, or running/benchmarking the vendor binary, plan §2 supersedes it: personal research; MIT/BSD/Apache
> code may be reused with attribution; GPL tools are subprocess oracles only; vendor binaries are never run for
> comparison, inspected or decompiled; oracles are published vendor-produced GTCs, gtc2vcf and BeadArrayFiles.
Source set (read completely):
- `pages/product-guides/cloud-analysis.md`
- `pages/product-guides/cloud-analysis/overview.md`
- `.../overview/genotyping.md`, `...-cytogenetics-analysis.md`, `...-methylation-qc.md`, `...-pgx-cnv-calling.md`, `...-pgx-star-allele.md`
- `.../overview-1.md` + `overview-1/{launch-analysis,plan-analysis,manage-data,share-project,troubleshoot-iscan}.md`
- `pages/pharmacogenomics-pgx-reference/{pgx-cnv-coverage,pgx-allele-definitions-and-pgx-guidelines,pgx-star-allele-coverage}.md` (the 476 KB coverage page was parsed with Python, not transcribed)
- `pages/support-and-updates/{faq,support-and-additional-resources}.md`
Because the in-scope analysis-type pages are thin (they mostly point elsewhere), the method-level details the task asks for (methylation metric formulas, cyto VCF/JSON semantics, PGx scoring/output fields, error strings) were pulled from the linked pages `product-guides/output-files.md`, `overview/our-features.md`, `product-guides/local-analysis.md` (cyto/pgx CLI option tables only) and the release notes. Every such item is tagged **[xref: file]**. Items not in the docs at all are tagged **[HYP]** (our inference) so they are never mistaken for documented behaviour.
Derived data files written alongside this report:
- `pgx_star_allele_coverage.csv` — 2,405 rows (gene × allele), 58 genes. Columns: `gene, allele, allele_kind, result_basis, n_alleles_for_gene, GDA_ePGx, GSAv4_ePGx, GCRA_ePGx, notes`.
- `pgx_masked_variants.csv` — 24 rows (product, manifest, gene, masked variant-ID list).
Vendor terms used below are there only to identify what is being described: platform (cloud hub), analysis types, product/array names, file names. The gap analysis at the end uses generic wording only.
---
## 0. The cloud platform (execution model)
### 0.1 Analysis types offered (cloud)
| Analysis type (UI string) | Local equivalent | Sample min | Cloud max batch |
|---|---|---|---|
| Genotyping and QC | `genotype call`, `genotype gtc-to-vcf`, `qc call`, `qc report` | 1 | 1152 |
| PGx – CNV calling | + `pgx copy-number call` | 24 with ≥22 passing (LogRDev < 0.2); 96 recommended | 384 |
| PGx – Star allele annotation | + `pgx star-allele call`, `pgx star-allele annotate` | same as CNV | 384 |
| Cytogenetics analysis | + `genotype gtc-to-bedgraph`, `cyto call`, `cyto annotate` | 1 | 1152 (known issue: may fail around 200 samples/batch from memory; run smaller batches) |
| Cytogenetics + external interpretation (case-management integration) | cloud only | 1 | 1152 |
| Methylation QC | cloud only (no local command) | 1 | 1152 |
[xref: our-features.md, release notes]
Deprecated in Q1 2026 (pipeline versions only, not analysis types): Methylation QC 1-0-0, PGx Star Allele Annotation 1-0-0, Genotyping 1-0-0, PGx CNV Calling 1-0-0.
### 0.2 Prerequisites
- Platform subscription (Basic/Professional/Enterprise); workgroups must exist before login; workgroup owner must hold "Has Access" role (not "Has Access + Archive"). "Collaborative" workgroup (checkbox "Enable collaborators outside of this domain") needed to share projects.
- Credits for storage/compute; per-sample licence for PGx star-allele pipelines.
- Optional scanner integration: scanner control software ≥ 4.2.1.
- Accept all EULAs before scanning.
- Network ≥ 1 GbE recommended for uploads.
- BeadChip accessioning before scanning is no longer required (automated).
### 0.3 Hub structure
"Microarray Hub" = Runs tab → Microarray scans tab; two sub-tabs: **Data Management** and **Planned Analyses**. Workgroup context must be active (name in top-right).
### 0.4 Launch analysis (immediate) — workflow & inputs
1. Analysis Name. 2. Select Project (existing or New). 3. Type of Analysis. 4. (Optional) "Add Custom Configuration": named; product files uploaded or selected; file-name constraints per platform data-naming rules; options vary per type. 5. Choose Configuration Settings entry. 6. Next. 7. Sample source — one of:
- **Import Sample Sheet** (template downloadable; only way to select a subset of samples within a BeadChip),
- **Select BeadChips** (whole chips),
- **Import IDAT Files** (upload from local folder; stored for future analyses in the workgroup; *manually uploaded IDATs are not QC-checked for failing registration scores*).
8. Launch Analysis.
Outputs: Analyses tab → status (e.g. initializing/complete) → Files tab → Output folder.
Troubleshooting (verbatim concepts): background processes after IDAT upload "should take a few minutes at most"; if samples stay not-ready → re-import; **Product Mismatch**: every BeadChip requires a product association; product of configuration must match IDAT product; **Upload Timeout**: idle timeout logs user out and stops upload → stay active or split into batches; timeout configurable for enterprise domains.
### 0.5 Planned analysis (auto-launch)
Same steps 1–6, then: 7. Import Sample Sheet (samples need not be scanned yet). 8. **Maximum failed scanned samples** threshold. 9. Save.
- A sample "fails during scanning" when **stripe registration < 0.75** (flagged as potentially misregistered; red in scanner progress window).
- Execution rules: auto-launch when all listed samples are available; **abort** if failed-scan count > threshold; if failures ≤ threshold launch with passing samples only.
- Overview card counts: Planned; Planned & Launched; Aborted Before Launch; date-range filter (modified date); click count to filter.
- Detail page sections: Configuration (Analysis Name, Project, Analysis Type, Detailed Configuration Settings), Samples (Samplesheet download, Maximum Failed Samples Allowed), Status (Status: planned/launched/aborted; Array Status Summary; Export Sample Status file).
- Per-sample status/reason table (verbatim):
| Status | Reason |
|---|---|
| Ready | Sample will be included in analysis due to successful data upload. |
| Failed | Sample will be excluded from analysis due to scanning failure. |
| Pending | Sample is pending data upload. |
- Only `planned` (not launched) analyses may be deleted; deletion is permanent.
### 0.6 Data management
Filter by Upload Status, sort/filter by Upload Date; per-row or page-wide bulk delete; "Deleting the selected items will permanently delete them and the action cannot be undone. Deleting items can affect ongoing analysis."
### 0.7 Sharing
Share-by-link from Projects tab (Share → Get Link). Owner keeps ownership/write; if owner deletes data, collaborators lose access. Either sending or receiving domain must be collaborative. Same regional instance required (no cross-region transfer). Enterprise domains use share-by-link, not share-by-transfer.
### 0.8 Scanner integration troubleshooting
Firewall: block inbound, allow outbound; allow-list endpoints:
| Endpoint | Category | Purpose |
|---|---|---|
| [ref-cloud-endpoint] | Required | Send IDAT files to platform |
| o.ss2.us, ocsp.digicert.com, ocsp.pki.goog/gsr2, ocsp.rootca1.amazontrust.com, ocsp.rootg2.amazontrust.com, ocsp.sca1b.amazontrust.com | Required | Certificate authorization |
| fonts.gstatic.com | Required | Display fonts |
| fonts.googleapis.com | Recommended | Display fonts |
| cdn.walkme.com, cdn3.userzoom.com, dpm.demdex.net, illuminainc.demdex.net, illuminainc.tt.omtrdc.net, smetrics.illumina.com, google.com, google-analytics.com, stats.g.doubleclick.net | Recommended | Telemetry |
| illumina.com | Optional | Support material |
**IDAT FAIL status**: scanner marks sections with poor registration as FAIL; such samples are excluded (IDATs exist but are not selectable via BeadChip table or sample sheet). Registration quality is in the scanner's `metrics.txt`.
---
## 1. Genotyping and QC (cloud)
- **Inputs**: IDATs; manifest (BPM/CSV) and cluster file (EGT) — may be pre-set; genome FASTA (pre-set; GRCh37/GRCh38 for human; user FASTA for non-human diploid); optional sample sheet; QC-report config file (pre-set). [xref: our-features]
- **Custom configuration parameters**:
- Output toggles: VCF on/off; Final Report on/off; Locus Summary on/off.
- GenCall Score Cutoff override (default not stated on this page; genotyping default elsewhere is 0.15 — see other analysis files).
- "Use Infinium I probe no-calls" — constrain possible genotypes using Infinium I no-call information.
- QC Report output format: **xlsx (default)** or CSV.
- **Recommendations**: non-human species → turn off VCF (VCF needs genome mapping, only provided for GRCh37/38). **~400+ samples → turn off Final Report** (can reach **50+ GB**).
- **Outputs**: per sample GTC, SNV VCF (+TBI, optional); per batch genotype summary files, Final Report (cloud only), Locus Summary (cloud only), QC metrics files (`controls.raw_metrics.csv`, `controls.qc_metrics.csv`), QC report, warnings/errors. [xref]
- **Functional QC defaults** (QC report): call rate threshold 0.98, LogRDev threshold 0.20. [xref: local-analysis `qc report`]
- **Supported arrays** (cloud v1.1/v1.4): ASA-24v1-0_E2, BovineSNP50_v3_A1 (UMD3), CGA-24v1-0_A1, GCRA-24v1-0 B2, GDA-8v1-0_D2, GSA-24v3-0_A2, GSA-48v4-0 D2, JSA-24v1-0_B2, PRSbooster (GRCh37 only); also the PGx and cyto products. "Any Infinium genotyping array incl. custom/semi-custom and non-human diploid".
---
## 2. Cytogenetics analysis
### 2.1 Inputs
IDATs; manifest + cluster (pre-set); QC report config; **cytogenetics model file** (.dat, pre-set on cloud); cytogenetics annotation database (local only; cloud pre-set, e.g. `CytoAnnotateData_DAv1.2.0.zip`); optional sample sheet.
### 2.2 Parameters (cloud "Cytogenetics Threshold Adjustment"; shown after product files are selected, saved in the configuration)
| Threshold | Default | Min | Max | CLI equivalent [xref] |
|---|---|---|---|---|
| GTC Output | False | – | – | – |
| SNV VCF Output | False | – | – | – |
| DUP minimum size (kb) | 50 | 0 | 250000 | `--min-dup-size` |
| DUP minimum probes | 10 | 0 | 250000 | `--min-dup-probes` |
| DEL minimum size (kb) | 25 | 0 | 250000 | `--min-del-size` |
| DEL minimum probes | 10 | 0 | 250000 | `--min-del-probes` |
| LOH minimum size (kb) | 3000 | 0 | 250000 | `--min-loh-size` |
| LOH minimum probes | 500 | 0 | 250000 | `--min-loh-probes` |
| GAINLOH minimum size (kb) | 500 | 0 | 250000 | `--min-gainloh-size` |
| GAINLOH minimum probes | 300 | 0 | 250000 | `--min-gainloh-probes` |
| mDUP minimum size (kb) | 50 | 0 | 250000 | `--min-mdup-size` |
| mDUP minimum probes | 10 | 0 | 250000 | `--min-mdup-probes` |
| mDEL minimum size (kb) | 25 | 0 | 250000 | `--min-mdel-size` |
| mDEL minimum probes | 10 | 0 | 250000 | `--min-mdel-probes` |
| mLOH minimum size (kb) | 3000 | 0 | 250000 | `--min-mloh-size` |
| mLOH minimum probes | 500 | 0 | 250000 | `--min-mloh-probes` |
| CNV Smoothing window size | 5 | 0 | 1000 | `--smoothing` (probes on each side of the centre probe used to smooth LRR) |
Local-only extras [xref]: `--min-qual` default **20** (CNV and LOH QUAL filter for reporting in JSON); `--max-mosaic-fraction` default **1.0** (mosaic calls with MF ≥ value are "promoted" to non-mosaic and tagged `HIGHFRACTION`, keeping MF).
"Adjusting thresholds will impact the number of events called and thus, the output in the VCF and JSON files."
Filtering semantics [xref release notes 1.3]: `cyto call` filters by **effective size**; `cyto annotate` filters by **raw size**.
### 2.3 Event types / states [xref: output-files]
- VCF ALT: `<DEL>` (copy number loss), `<DUP>` (copy number gain), `<LOH>` (AOH/LOH/ROH).
- IDs: `DEL:chr:start:end`, `DUP:…`, `MosaicDEL:…`, `AOH:…` (e.g. `AOH:22:9426438:14766246`).
- INFO `LOHTYPE` ∈ {**AOH** (germline, CN-neutral or gain LOH), **CNLOH** (somatic CN-neutral LOH), **GAINLOH** (somatic, CN-gain LOH)}; examples: LOH with CN=2, GAINLOH shown with CN=3.
- INFO `MOSAIC` flag; `HIGHFRACTION` flag for promoted events; `SVLEN`, `PROBE`, `END`.
- FORMAT `GT` (hard-coded **1/1** for all cyto entries), `CN` (integer; "CN=4 indicates 4 or 4+"), `NR` (aggregated normalized intensity), `LRD` (SD of LRR in event), `MF` (estimated mosaic fraction; `.` if non-mosaic).
- Header: `##OverallPloidy=1.9`, `##GCCorrect=True`, `##platform=cytoplatform`, `##product=…`, `##genomeBuild=37|38`.
- Mosaic detection sensitivity: ≈ **>15 % mosaic fraction** for one-copy-difference states (CN2/CN1, CN2/CN3 in diploid; CN1/CN0, CN1/CN2 in haploid regions); mosaic dup on male Y supported; the former 5 % hard MF cutoff was removed (v1.4). [xref release notes]
### 2.4 QC gating [xref]
- `QUAL = −10·log10(1 − P(called state))`, capped at **60**, min 0; FILTER **Q10** when QUAL < 10.
- FILTER **SampleQuality** when sample LogRDev > **0.2**.
- FILTER **LowFraction** — mosaic variant with MF below threshold (threshold value not documented).
- JSON reporting additionally requires QUAL ≥ `minQual` (20).
- Unknown sex from genotyping → caller tries to resolve (log "Sample XXX sex updated from Unknown to Male."); if unresolved, assumes **male**.
### 2.5 Annotation / ISCN [xref]
Per-sample JSON: `annotateDb`, `softwareVersion`, `referenceGenome`, `annotationType` (0 = Constitutional, 1 = Oncology; only constitutional supported), `genomeBuild`, `databaseSources` (RefSeq GCF_000001405.40-RS_2023_10; Ensembl 112), `iscnVersion` ("ISCN 2020"), `sampleId`, `sampleName`, `gcCorrect`, all min thresholds, `overallPloidy` (length-weighted mean ploidy; sex-dependent baseline), `callRate`, `logRDev`, `medianLogRDev`, `bafDev{AA,AB,BB}`, `numLOHOver1M`, `numLOHOver8M`, `totalSizeLOHOver1M` (incl. GAINLOH at sample level; excl. at chromosome level), `copyNumberMedian` (length-weighted), `percentLOH`, `sexEstimate`, `traditionalNomenclature`, `microarrayNomenclature`.
Per chromosome: `size, percentHet, hasMosaicism, lrrMedian, lrrMean, lrrDev, numLOHOver1M/8M, totalSizeLOHOver1M, percentLOH, copyNumberMedian, copyNumberMean, minLogRRatio, maxLogRRatio, medianMosaicFraction, numberDel/Dup/LOH/GainLOH/Mosaic`.
Per event: `id, chrom, start, end, callType (DEL/DUP/LOH), mosaicState, mosaicFraction, copyNumber, qualityScore, size, effectiveSize, probeCount, percentHet, lrrMedian, lrrDev, bafDev, startCytoBand, endCytoBand, traditionalNomenclature, microarrayNomenclature, geneCount, genes`.
- **effectiveSize**: gap-excluded length; a gap = probe spacing > **150 ×** median spacing, replaced by the median spacing.
- ISCN strings: traditional `del(1)(p36.33p36.33)`; microarray `arr[GRCh37] 4p16.3(3562944_3627954)x3`, `…x2 hmz` for LOH; ISCN only for events **> 1 kb**; not (fully) for LOH and mosaic events; no mosaic ISCN notation.
- Genes: RefSeq HGNC symbols whose transcripts intersect the event, plus Ensembl IDs without a symbol.
### 2.6 Limitations [xref release notes]
Constitutional only; validated only on GDA-Cyto-8, GSA-Cyto-24, CytoSNP-850K (iScan; NS550 IDATs supported from v1.3 but earlier "not formally validated"); centromeres prone to false positives; large events may be fragmented (need visual review); no calls in PAR for certain manifests; memory failure around 200 samples/batch.
### 2.7 External interpretation integration (cloud only)
Requires extra interpretation-platform subscription ("Array", "Professional" or "Enterprise"); platform notifications: Event "Analysis Success", Type SNS, regional Address, Payload Version **v4**, region auto-filled, optional "Send Test Message". Version compatibility governed by platform-minor-version + case-pipeline-version (both must be updated); v1.3 cyto not compatible with interpretation platform v38 (use 1.2.0 pipeline). Outputs reduced to GTC (opt), SNV VCF (opt), cyto VCF, JSON, bedgraph, genotype summary, logs.
### 2.8 Supported arrays
GDACyto-8v1-0_20047166_E2, GSACyto-24v1_20044998_C2, CytoSNP-850Kv1-4_iScan_B2 (cloud/local v1.2+), CytoSNP-850Kv1-4_NS550_B2 (v1.3+); GRCh37 and GRCh38.
---
## 3. Methylation QC (cloud only)
### 3.1 Inputs
IDATs (from the scanner), methylation manifest CSV (pre-set; must contain `[Assay]` and `[Controls]` sections with IlmnID, AddressA_ID, AddressB_ID, Color_Channel; controls with 4 columns Address,Type,Color_Channel,Name), optional sample sheet (metadata/grouping: Sample_ID, Sample_Group, arbitrary user fields).
### 3.2 Parameters and defaults (21 control thresholds + 2 global)
| Threshold | MSA default | EPIC (v1/v2) default |
|---|---|---|
| Restoration¹ | 0 | 0 |
| StainingGreen | 5 | 5 |
| StainingRed | 5 | 5 |
| ExtensionGreen | 5 | 5 |
| ExtensionRed | 5 | 5 |
| HybridizationHighMedium | 1 | 1 |
| HybridizationMediumLow | 1 | 1 |
| TargetRemoval1 | 1 | 1 |
| TargetRemoval2 | 1 | 1 |
| BisulfiteConversion1Green | 1 | 1 |
| BisulfiteConversion1BackgroundGreen | 0.5 | 1 |
| BisulfiteConversion1Red | 1 | 1 |
| BisulfiteConversion1BackgroundRed | 0.5 | 1 |
| BisulfiteConversion2 | 0.5 | 1 |
| BisulfiteConversion2Background | 0.5 | 1 |
| Specificity1Green | 1 | 1 |
| Specificity1Red | 1 | 1 |
| Specificity2 | 1 | 1 |
| Specificity2Background | 1 | 1 |
| NonpolymorphicGreen | 2.5 | 5 |
| NonpolymorphicRed | 3 | 5 |
| BgCorrectionOffset (x) | 3000 | 3000 |
| PvalThreshold | 0.05 | 0.05 |
¹ FFPE restore kit used → raise Restoration from 0 to 1.
Release-notes also list "proportion probes passing" as adjustable, but the current docs state probe detection rate is **not** used for pass/fail.
Guidance: thresholds are a starting point for custom/semi-custom arrays; tuning may depend on BeadChip, lab, scanner settings, bisulfite method, FFPE; tune on a dataset deemed acceptable by proportion of probes passing. Several docs say "Do not change the default threshold" for hybridization, target removal, specificity and background ratios (only the offset may change); "may be increased for some scanners" for staining, extension, BS-conversion C/U ratios, non-polymorphic.
### 3.3 Metric formulas [xref: output-files]
Let `bkg_G` = highest green intensity of Extension A or T; `bkg_R` = highest red intensity of Extension C or G; `x` = offset (3000). Pass when metric > threshold (documented as "> threshold").
| Metric | Formula |
|---|---|
| restoration | Green / (bkg_G + x) |
| staining_green | Biotin(High) / Biotin(Bkg) |
| staining_red | DNP(High) / DNP(Bkg) |
| extension_green | min(Ext C, Ext G) green / max(Ext A, Ext T) green |
| extension_red | min(Ext A, Ext T) red / max(Ext C, Ext G) red |
| hybridization_high_medium | High / Medium (green) |
| hybridization_medium_low | Medium / Low (green); synthetic targets 5 pM / 1 pM / 0.2 pM |
| target_removal1, target_removal2 | (bkg_G + x) / ctrl green |
| bisulfite_conversion1_green | min(C1, C2) / max(U1, U2) (green) |
| bisulfite_conversion1_background_green | (bkg_G + x) / max(U1, U2) green |
| bisulfite_conversion1_red | min(C3, C4, C5) / max(U3, U4, U5) (red) |
| bisulfite_conversion1_background_red | (bkg_R + x) / max(U) red — docs list both "U3,4,5" and "U4,U5,U6" (inconsistency) |
| bisulfite_conversion2 | min(C1..C4 red) / max(C1..C4 green) |
| bisulfite_conversion2_background | (bkg_G + x) / max(C1..C4 green) |
| specificity1_green / _red | min PM / max MM per channel (GT-mismatch 1–3) |
| specificity2 | min(S1..S3 red) / max(S1..S3 green) |
| specificity2_background | (bkg_G + x) / max(S1..S4 green) |
| nonpolymorphic_green | min(NP C, NP G) / max(NP A, NP T) green |
| nonpolymorphic_red | min(NP A, NP T) / max(NP C, NP G) red |
Sample `passQC` = 1 iff all 21 metrics pass; `failCodes` lists failing metric names. Computed "in the same way as" the vendor's BeadArray Controls Reporter.
### 3.4 Signal processing (what docs say vs what is undocumented)
- Documented: **dye-bias correction** and **noob** normalization ("avg_green_norm / avg_red_norm = average signal after dye bias correction and noob normalization"); "Prep failed" = dye-bias or noob failure; manifest converted to a SeSAMe-format `probes.csv` (Probe_ID, U=AddressA, M=AddressB, col) — log names `convert_manifest_ilmn_sesame.log`, `run_sesame_gs.log` indicate a SeSAMe-based implementation.
- Background correction / dye bias / detection p-value are computed **differently from the legacy desktop methylation module**; detection p-value is **more stringent**, so detection rates are lower (legacy: >96 % typical for non-cancer standard input).
- Example detection rates on MSA (only QC-passing samples, ≥50 ng input, p < 0.05): A min 86 % / mean 93 % (n=220); B 61 %/83 % (951); C 63 %/85 % (34); D 77 %/85 % (22).
- Beta: linear 0..1 (unmethylated ≈0, methylated ≈1); M-value: log-transformed beta; detection p: likelihood signal is background; recommend excluding p > 0.05.
- **Not documented [HYP]**: exact p-value method (likely SeSAMe pOOBAH — out-of-band empirical CDF), beta offset (SeSAMe default beta = M/(M+U) with floors; legacy uses +100), M = log2(M/U) (or log2(β/(1−β))), dye-bias method (likely SeSAMe `dyeBiasNL`/`dyeBiasCorrTypeINorm`), noob parameters. Tech note M-GL-02644 holds details (not archived here).
### 3.5 Outputs
Per sample: `{Barcode}_{Pos}_ctrl.tsv.gz` (address, type, channel, name, probe ID, MG/MR/UG/UR raw) and `{Barcode}_{Pos}_cgs.tsv.gz` (beta, M, detection p per CG). Per batch: `sample_qc_summary.xlsx/.tsv` (Sentrix_ID, Sentrix_Position, Sample_ID, user metadata, 21 metrics, avg_green_raw, avg_red_raw, avg_green_norm, avg_red_norm, ScanTime, NProbes (SNP+CG probes), NPassDetection, prop_probes_passing, passQC, failCodes; xlsx highlights failures), `sample_qc_summary.pdf` (histogram of proportion passing, pass/fail coloured; PCA of betas on all analytical probes, **random 10,000 probes if > 100 samples**, coloured by Sample_Group), `pcs.tsv.gz` (id, PC1, PC2, Sample_Group or NA), `probes.csv`, `controls.csv`, logs.
### 3.6 Error/warning messages (verbatim) [xref]
| Log | Message | Type |
|---|---|---|
| write_samplesheet.log | No IDATs found | Error |
| format_samplesheet.log | No samples in sample sheet | Error |
| format_samplesheet.log | Sample sheet not correctly formatted (not CSV or header lines not starting with "<") | Error |
| format_samplesheet.log | beadChipName and sampleSectionName columns are required for the sample sheet. | Error |
| format_samplesheet.log | Warning: {X} samples have duplicate Sample_ID (duplicates dropped) | Warning |
| convert_manifest_ilmn_sesame.log | Missing control probes in manifest (no "[Controls]") | Error |
| convert_manifest_ilmn_sesame.log | Probe section not found (no "[Assay]") | Error |
| convert_manifest_ilmn_sesame.log | Missing required columns: IlmnID, AddressA_ID, AddressB_ID, Color_Channel | Error |
| convert_manifest_ilmn_sesame.log | Controls not formatted correctly. Must have 4 columns (Address,Type,Color_Channel,Name) | Error |
| run_sesame_gs.log | Missing sample: {sample} | Error |
| run_sesame_gs.log | No scan time available | Warning |
| run_sesame_gs.log | Prep failed | Error |
| run_sesame_gs.log | Warning: missing control probe types {…} (metric → NA) | Warning |
| run_sesame_gs.log | Warning: missing control probe names {…} (metric → NA) | Warning |
| qc.log | No features, skipping PCA plot | Warning |
### 3.7 Limitations / supported arrays
EPIC v1 (b5 manifest), EPIC v2 (EPIC-8v2-0_A2), EPIC-Xtra (custom), MSA-48v1-0 A1; GRCh38; cloud v1.0. Built-in controls may be missing on discontinued/custom chips; thresholds may not apply to NextSeq550 IDATs. v1.0.0 known issue (fixed 1.0.1, Feb 2026): failures at 80–100 samples with >900K-probe arrays.
---
## 4. PGx CNV calling
- **Inputs**: IDATs, manifest, cluster, FASTA, **PGx CN model file** (pre-set), sample sheet. Local: `pgx copy-number call --cn-model … --platform LCG|EX` (LCG for GDA-ePGx; EX for GSAv4-ePGx/GCRA-ePGx). [xref]
- **Batch requirement**: minimum **24 samples with ≥22 passing** (LogRDev < 0.2); **96 or more** samples passing LogRDev ≤ 0.2 recommended. Error when violated: `{numPassingSamples} sample(s) passed QC. Requires at least {minPassingSamples} samples to proceed.`
- **Target regions (GRCh38)** — 7 genes, 10 regions:
| Gene | Region | Chr | Start | End |
|---|---|---|---|---|
| GSTM1 | GSTM1 | 1 | 109687842 | 109693526 |
| UGT2B17 | UGT2B17 | 4 | 68537222 | 68568499 |
| CYP2E1 | CYP2E1 | 10 | 133527374 | 133539096 |
| SULT1A1 | SULT1A1 | 16 | 28603587 | 28613544 |
| CYP2A6 | CYP2A6.intron.7 | 19 | 40844791 | 40845293 |
| CYP2A6 | CYP2A6.exon.1 | 19 | 40850267 | 40850414 |
| CYP2D6 | CYP2D6.exon.9 | 22 | 42126498 | 42126752 |
| CYP2D6 | CYP2D6.intron.2 | 22 | 42129188 | 42129734 |
| CYP2D6 | CYP2D6.p5 | 22 | 42130886 | 42131379 |
| GSTT1 | GSTT1 | 22_KI270879v1_alt | 270316 | 278477 |
Note GSTT1 lives on an **alt contig** — the reference must include alts.
- **CN states / output** [xref]: `*.cnv.vcf.gz` per sample; ALT `<CNV>`, `SVTYPE=CNV`, INFO CNVLEN, PROBE, END; FORMAT `CN` ("CN=5 indicates 5 or 5+"), `NR`; QUAL Phred capped at 60, FILTER **Q7** (QUAL < 7), FILTER **SampleQuality** (LogRDev > 0.2); header `##OverallPloidy`, `##GCCorrect=True`. Example probe counts per region: 21–383. Batch `cn_batch_summary.csv` (Target Region, Total CN gain, Total CN loss, Total CN neutral, plus "All Target Regions"); CN summary file; optional bedgraphs.
- **Semi-custom arrays on cloud**: semi-custom samples are filtered from the BeadChip table → workaround: choose a commercial configuration (e.g. `GDA_PGx-8v1-0_G4 - GRCh38`) and use Import Sample Sheet. Alternatively create a custom configuration with the semi-custom product files and Import IDAT Files.
- Warning: `Cluster file ({GTC.egt}) is not the same as CN Model Cluster file ({CN_Model.egt}).` (re-train CN model when cluster file changes significantly).
- Supported arrays: GDA_PGx-8v1-0_20042614_G4, GSA-PGx-48v4-0_20079540_E2, GCRA-PGx-24v1-0_20084467_C2; GRCh38 only; cloud/local v1.1+.
---
## 5. PGx star-allele annotation
### 5.1 Inputs / parameters
Adds **PGx database file** (.zip; e.g. `DAv1.4.0-pgx-mapping-sha.<sha>.zip`) to the CNV inputs; SNV VCF must be bgzipped + tabix-indexed and produced without `unsquash-duplicates`/`filter-loci`. Only cloud parameter: **Metabolizer Status Database** — default **CPIC**, alternative **DPWG** (CLI `--guidelines CPIC|DPWG`, default CPIC).
### 5.2 QC recommendations
Review samples with **LogRDev > 0.2**, **call rate < 0.99**, or **TGA control probe < 1.0**. Same batch minimum as CNV (24/22, 96 recommended).
### 5.3 Databases & versions
| Source | Version |
|---|---|
| PharmVar | 6.1 |
| PharmGKB | Snapshot-2024.05.16 |
| UGT Alleles Nomenclature | 2010.12.21 |
| Human CYP Allele Nomenclature DB legacy content | July 2024 |
| CPIC guidelines | 1.38.0 (cpicpgx.org/guidelines, github.com/cpicpgx/cpic-data) |
| DPWG guidelines | June 2023 (pharmgkb.org/page/dpwgMapping) |
### 5.4 Phenotype / activity-score coverage
- CPIC phenotype: CACNA1S, CYP2B6, CYP2C19, CYP2C9, CYP2D6, CYP3A5, DPYD, G6PD, MT-RNR1, NUDT15, RYR1, SLCO1B1, TPMT, UGT1A1, CFTR, IFNL3/IFNL4, VKORC1 (17). Activity scores: CYP2C9, CYP2D6, DPYD.
- DPWG phenotype: CYP1A2, CYP2B6, CYP2C19, CYP2C9, CYP2D6, CYP3A4, CYP3A5, DPYD, NUDT15, SLCO1B1, TPMT, UGT1A1, VKORC1, F5 (14). Activity scores: CYP2D6, DPYD.
- Phenotype is a direct lookup (diplotype → guideline table). Reference allele of ABCG2 annotated "Normal" by default (post-1.3 fix). Example output phenotypes: "Normal Metabolizer", "Decreased Function", "Ivacaftor non-responsive", "CYP2D6 Indeterminate"; `n/a` when none.
### 5.5 Database construction rules
- **Multi-allelic variant (MAV) extension**: single-allele definitions whose site is multi-allelic in the product files are extended to all alleles on the array — 52 extensions listed (CACNA1S 1, CFTR 19, COMT 1, DPYD 16, RYR1 15; e.g. `rs113993958.G>T`, `NC_000007.14:g.117530953G>T`).
- **G6PD build-specific definitions**: GRCh37: "Mediterranean Haplotype" = rs2230037 G>A + rs5030868 G>A; "Mediterranean, Dallas, Panama, Sassari, Cagliari, Birmingham" = rs5030868 G>A with rs2230037 ref G. GRCh38: "Mediterranean Haplotype" = rs5030868 G>A with rs2230037 ref A; the multi-name allele = rs2230037 A>G + rs5030868 G>A. rs2230037 is ignored in all other G6PD alleles.
- **\*0 allele** = full gene deletion when no named deletion allele exists.
- **Tagging-variant genes**: HLA-A\*31:01 (rs1061235 A>T), HLA-B\*15:02 (rs144012689 T>A; absent from GDA-ePGx), HLA-B\*57:01 (rs2395029 T>G), HLA-B\*58:01 (rs9263726 G>A), IFNL3/4 rs12979860 (T). Reliability varies by population.
- **Masked variants**: poorly performing probes treated as no-calls; alleles defined solely by masked variants are never called (per product list → `pgx_masked_variants.csv`; GDA-ePGx 4 rows: CYP1A2 rs35694136, CYP2D6 rs72549352, CYP4F2 rs4020346, UGT1A1 rs8175347; GSAv4-ePGx 10 rows: CYP1A2 rs35694136, CYP2C19 rs367543002/rs17882687/rs113934938, CYP2C9 rs774607211 (+10:96701973), CYP2D6 rs1135836/rs769157652, CYP4F2 rs4020346, OPRM1 rs9384179, UGT1A1 rs8175347; GCRA-ePGx 10 rows: COMT rs7287550, CYP1A2 rs35694136, CYP2C19 ×3, CYP2C9 rs774607211, CYP2D6 rs2004511/rs769157652(+rs61737947), CYP4F2 rs4020346, OPRM1 rs9384179).
- Novel and non-database alleles are not reported.
- Aux file `[Product]_GS_import.txt` per product (GDAePGx_G2, GSAePGx_E2, GCRAePGx_E2) lists PGx variants → alleles (SNP/indel only, no SV alleles).
### 5.6 Coverage database statistics (parsed; see CSV)
58 genes, 2,405 allele/variant entries. Breakdown:
- **Star-allele genes (19)** with counts: CYP2D6 184 (incl. 14 duplication forms `*1x2 … *36x3-*10`, 7 hybrid/tandem forms `*13-*1`, `*13-*4-*68`, `*36-*10`, `*4N-*4`, `*68-*4`, `*1-*90`…, sub-allele `*4M`; max number \*172), CYP2C9 85, CYP2A6 51 (incl. `*1x2`), CYP2B6 46, TPMT 46 (`*3A/*3B/*3C`), CYP3A4 45, SLCO1B1 42, CYP1A2 39 (legacy lettered `*1A…*1V`), CYP2C19 34, NUDT15 20, CYP2C8 18, CYP4F2 16, CYP2E1 11 (`*1A,*1B,*5A…`), UGT1A1 9 (`*80+*28`, `*80+*37`), UGT1A4 8, UGT2B15 7, CYP3A5 6, APOE 3 (E2/E3/E4), HLA-B 3 + ref, HLA-A 1 + ref.
- **Named-haplotype gene**: G6PD 187 (186 named variants, e.g. "A-", "Mediterranean…", "B (reference)").
- **Variant-based genes (37)** reported as `Reference` + `rsID.REF>ALT` entries: DPYD 475 (433 distinct rsIDs; suffixes like `rs114096998.2.G>C` distinguish multiple definitions at one rsID), RYR1 355 (244 rsIDs + 72 HGVS-only), OPRM1 175, CFTR 59, DRD2 56 (incl. `rs1799732._113475530insG`, `rs1799732.dup`), COMT 46, OPRD1 46, CACNA1C 37, HTR2A 32, MT-RNR1 24 (13 `NC_012920.1:m.` HGVS), BDNF 23, TNF 23, OPRK1 24, IL6 21, HTR2C 17, GRIN2B 15, MTHFR 13, FKBP5 12, ITGB3 12, ADH1B 10, ANKK1 10, HMGCR 9, ATM 7, KIF6 6, F2 5, CACNA1S 4, F13A1 3, GRIK1 3, GRIK4 3, LPA 3, ABCG2 2, ALDH2 2, ANK3 2, F5 2, VKORC1 2 (rs9923231 T), YEATS4 2, IFNL3/4 2.
- There are **no per-array columns** in the source table (it is the software database, array-agnostic). Per-array status in the CSV is derived from the "Known Limitations" section:
- APOE E2/E4 not callable on GSAv4-ePGx/GCRA-ePGx (rs7412, rs429358 non-functional).
- CYP2A6 \*5 not supported on GDA-ePGx.
- CYP4F2 (all 3): \*2 reported as \*1; \*4 reported as \*3 (no probe for the distinguishing site).
- UGT1A1 \*28 ([TA]8) and \*37 ([TA]9) not covered on any of the 3.
- UGT2B15 \*4/\*5 not supported on GSAv4-ePGx/GCRA-ePGx (rs4148269, rs1902023).
- CYP2D6 \*40 vs \*58 indistinguishable → reported \*40.
- NUDT15 \*6 vs \*9 indistinguishable → reported \*6.
- HLA-B\*15:02 not on GDA-ePGx.
- CSV legend: `allele_kind` ∈ {star_allele, reference, rsid_variant_allele, hgvs_variant, named_haplotype}; `result_basis` ∈ {star_allele, variant_based, haplotype_named, tagging_variant}; per-product column values: `db_supported_if_variants_on_array` (default), `not_supported`, `reported_as_*X`, `array_dependent`, `not_supported_(*28_component)`.
### 5.7 Scoring & outputs [xref]
- Solutions ranked by **qualityScore** (0–1; probability including population allele frequencies); **rawScore** excludes frequency prior. Lower-ranked solutions with score **≥ 50 % of the top** are "feasible" and all listed in `genotype` (semicolon-separated). Consider alternatives when supporting variants have **GS < 0.15**; inspect clusters for shifts.
- Array-equivalent alleles: alleles indistinguishable given array content + no-calls; the **most frequent** (population frequency) is reported.
- Structural alleles use CNV sub-region CNs (`copyNumberRegions: p5, intron.2, exon.9`; `copyNumberSolution: 5, 5, 2`), background alleles, e.g. `*27/*36x2+*83+*10`. Non-\*36 exon-9 conversion alleles (\*83) reported as \*36 with \*83 underlying.
- Files: `diplotype_summary.csv` (Sample, Solution Id, Gene or Variant, Type Haplotype|Variant, Solution, Array-Equivalent Alleles 1/2, No Call Variants, Alleles Impacted by No-Call, Background Alleles, Variant Change, Score, Raw Score, Copy Number Solution), `diplotype_annotations.csv` (Sample, Gene, PGx Guideline, Genotype, Activity Score, Phenotype Database Annotation), `supporting_variants.csv`, `unresolved_variants.csv` (Reason: Not on Array / No Call), `variants_not_covered_on_array.csv`, per-sample star-allele JSON (softwareVersion, genomeBuild, starAlleleDatabaseSources, phenotypeDatabaseSources, mappingFile, pgxGuideline, sampleId, locusAnnotations[gene, callType, genotype, arrayEquivalentAlleles, activityScore, phenotypeDatabaseAnnotation, qualityScore, rawScore, supportingVariants, variantNoCalls, allelesImpactedByNoCalls, candidateSolutions[rank,…,alleles, unresolvedVariantSites, backgroundAllele, copyNumberRegions, copyNumberSolution], variantsNotCoveredOnArray, allelesTested]); `.dat` intermediate between call and annotate. CSVs carry `#` meta lines (build, database).
- Known issues: intermittent `The model has been changed since the solution was last computed.` (memory); some variants delimited with `_` instead of `>`; minor Linux/Windows score discordance with concordant ranking.
### 5.8 Semi-custom
PGx calls limited to content of the commercial PGx arrays; semi-custom designs must retain all commercial content; cloud workaround as in §4.
---
## 6. FAQ (condensed, all 7)
1. **Local or cloud?** Both. Local = CLI, Windows/Linux, CPU-only, no special hardware. Cloud = GUI on the sequencing hub.
2. **Which arrays?** See Product & Analysis Compatibility table.
3. **Samples per analysis?** Cyto ≥1; genotyping ≥1; PGx CNV ≥24 with 22 passing (LogRDev < 0.2), 96 recommended; batches may run in parallel.
4. **Which PGx CNVs / star alleles?** See release notes.
5. **Demo data?** Hub "Demo Data" section; array datasets start with "iScan:" and name the analysis type.
6. **Assay QC metrics?** Functional QC (Autosomal Call Rate, Call Rate, LogRDev, Sex Estimate) in genotype summary files; control-probe metrics in QC metrics files and the QC report (replaces the legacy desktop control dashboard).
7. **Rescans / duplicate IDATs?** Not supported: if several IDAT pairs resolve to the same `SentrixBarcode_A`+`SentrixPosition_A` under `--idat-folder`, only one is processed and which one may differ between Linux and Windows. Keep exactly one pair per barcode+position.
---
## 7. Support & additional resources (every link)
- Tech support: techsupport@illumina.com
- Product webpage: [ref-docs:product-page]
- Support site (installers, docs): [ref-docs:support-page]
- Methylation QC article: [ref-docs:dev-article-1.0-methylation]
- PGx analysis article: [ref-docs:dev-article-1.0-pgx]
- Lab setup & best practices: http://support-docs.illumina.com/ARR/infinium-labsetup.htm
- Evaluation of assay controls (PDF training guide): https://support.illumina.com/content/dam/illumina-support/courses/eval-inf-controls/story_content/external_files/Infinium_Controls_Training_Guide.pdf
- Video, evaluating assay controls: https://www.youtube.com/embed/MuDBayIegkg?autoplay=1&rel=0
- Consumables & equipment list: http://support-docs.illumina.com/ARR/infinium-consumables.htm
- Scanner documentation: http://support-docs.illumina.com/ARR/iscan.htm
- Polygenic risk score module: https://support-docs.illumina.com/ARR/PRS/Content/ARR/PRS/PRS.htm
- Platform core help: [ref-docs:vendor-cloud-platform-help]
- Sequencing hub help: [ref-docs:vendor-cloud-hub-help]
- Interpretation platform help: [ref-docs:tertiary-platform-help]
Other URLs cited in the in-scope pages: methylation QC tech note PDF M-GL-02644 ([ref-docs:methylation-qc-tech-note-M-GL-02644]); software registration guide PDF ([ref-docs:vendor-cloud-software-registration-guide]); scanner+platform how-to ([ref-docs:scanner-to-vendor-cloud-howto]); scan metrics (https://support-docs.illumina.com/ARR/iScan/Content/ARR/iScan/ScanMetrics_fIS.htm); network security (https://support-docs.illumina.com/SHARE/NetworkSecurity/Content/SHARE/FrontPages/NetworkingSecurity.htm); aux-file how-to (https://knowledge.illumina.com/microarray/general/microarray-general-reference_material-list/000008505); PGx product-file pages for GDA-ePGx, GSAv4-ePGx, GCRA-ePGx; CPIC (https://cpicpgx.org/), DPWG (https://www.pharmgkb.org/page/dpwg), PharmVar, PharmGKB, UGT nomenclature (https://www.pharmacogenomics.pha.ulaval.ca/ugt-alleles-nomenclature/), CYP legacy archive (https://www.pharmvar.org/htdocs/archive/index_original.htm); workgroup/session/region/share-by-link help pages on [ref-docs:vendor-cloud-hub-help]; platform notifications ([ref-docs:vendor-cloud-platform-help/project/p-notifications]); interpretation compatibility table and auto-case-creation pages on help.emg.illumina.com; AWS SNS.
---
## 8. Every numeric default collected here
Stripe registration fail < 0.75 · scanner software ≥ 4.2.1 · network ≥ 1 GbE · Final Report off at ~400+ samples (50+ GB) · QC report call rate 0.98, LogRDev 0.20 · cloud max samples 1152 (genotyping, cyto, methyl) / 384 (PGx) · cyto defaults DUP 50 kb/10 probes, DEL 25 kb/10, LOH 3000 kb/500, GAINLOH 500 kb/300, mDUP 50/10, mDEL 25/10, mLOH 3000/500, smoothing 5 (0–1000), size/probe ranges 0–250000, min-qual 20, max-mosaic-fraction 1.0, QUAL cap 60, Q10, SampleQuality LogRDev > 0.2, gap 150× median spacing, ISCN > 1 kb, mosaic sensitivity ≈ 15 %, cyto CN cap "4 or 4+", ~200-sample memory limit · PGx CNV min 24 samples/22 passing, 96 recommended, LogRDev ≤ 0.2, Q7, CN cap "5 or 5+", QUAL cap 60 · star allele review: LogRDev > 0.2, call rate < 0.99, TGA control < 1.0; alternative solutions ≥ 50 % of top score; low-GS 0.15; scores 0–1 · methylation: offset 3000, p 0.05, thresholds per table §3.2, PCA 10,000 random probes when > 100 samples, legacy detection rate > 96 %, 50 ng input in examples, 80–100 sample/>900K probe bug · hybridization targets 5/1/0.2 pM.
---
## 9. Gap analysis vs SimurgArray plan (§9, §10, §11) — concrete spec additions
### 9.1 CNV/LOH/mosaic module (§10)
1. **Add GAINLOH as a first-class event type** (copy-gain + LOH, e.g. CN3 with no heterozygosity) with its own size/probe defaults (500 kb / 300 probes). Plan only lists CN2-LOH. Add LOH subtype field `{AOH (germline), CNLOH (somatic CN-neutral), GAINLOH}`.
2. **Separate per-event-type filters** for DEL, DUP, LOH, GAINLOH, mDEL, mDUP, mLOH (size kb + probe count, range 0–250000). Plan says "mosaic same" — make each independently configurable. Add `min_qual` (default 20) for reporting and state explicitly: calling-stage filter on effective size, annotation-stage filter on raw size.
3. **LRR smoothing window** parameter (probes each side, default 5, range 0–1000) used for segmentation/visualisation; bedgraph outputs for LRR and BAF.
4. **Mosaic handling**: report MF per event; `max_mosaic_fraction` (default 1.0) promotion rule with a `HIGHFRACTION` flag; `LowFraction` FILTER below a configurable minimum MF (define default, e.g. 0.10 [HYP]); target sensitivity ≈15 % for one-copy mosaic states incl. haploid regions (male X/Y, mosaic dup on Y).
5. **QC gating**: Q10 FILTER on QUAL < 10 (cyto) and Q7 (PGx CNV); `SampleQuality` FILTER at LogRDev > 0.2; CN top-coding (cyto CN ≥ 4 → "4+", PGx CN ≥ 5 → "5+"); GT always 1/1 in the event VCF (or document our own convention).
6. **Sex handling**: resolve unknown sex inside the CN caller from X/Y LRR/BAF; if unresolved, choose a documented default and log it; exclude PAR probes when manifest lacks PAR mapping; centromere blacklist.
7. **Per-sample JSON summary** mirroring the field list in §2.5 (overall ploidy length-weighted, copy-number median, callRate, logRDev, medianLogRDev, bafDev per AA/AB/BB, LOH counts >1 Mb and >8 Mb, total LOH >1 Mb, percentLOH, per-chromosome stats, per-event stats incl. effectiveSize, percentHet, lrrMedian/lrrDev/bafDev, cytobands, gene list). Define annotationType (constitutional vs oncology) — v2 supports constitutional only.
8. **ISCN 2020 generator**: both simplified (`del(1)(p36.33p36.33)`) and microarray (`arr[GRCh37] 4p16.3(start_end)x3`, `x2 hmz` for LOH) strings; skip < 1 kb; document mosaic notation (e.g. `x1~2` / `[0.4]`) as an improvement over the reference behaviour.
9. **Batch memory**: test at ≥ 1,152 samples; stream per-sample to avoid a ~200-sample ceiling.
### 9.2 PGx module (§11)
10. **Fix the CN region list**: the 10 GRCh38 regions in §4 (including `CYP2D6.p5` promoter/5′ region, `CYP2A6.exon.1`/`intron.7`, GSTT1 on `chr22_KI270879v1_alt`). Plan must require an alt-aware reference and a liftover strategy for GSTT1.
11. **Batch rule** exactly: error if < N_min passing samples (N_min = 22 of ≥24, LogRDev < 0.2); warn below 96. Emit the error message "{n} sample(s) passed QC. Requires at least {m} samples to proceed." equivalent. Warn when the cluster file differs from the one the CN model was trained with.
12. **CN outputs**: per-sample CN VCF (`<CNV>`, CNVLEN, PROBE, END, CN, NR, OverallPloidy, GCCorrect) and batch gain/loss/neutral count table.
13. **Star-allele scoring spec**: two scores (with/without population-frequency prior), rank, keep all solutions ≥ 50 % of top score, flag supporting variants with GS < 0.15; array-equivalent allele collapsing (report most frequent); background allele; no-call impact lists; unresolved-variant reasons (`Not on Array`, `No Call`); variants-not-covered list; allelesTested list per array.
14. **Database build rules**: MAV extension of single-allele definitions to all array alleles; build-specific G6PD Mediterranean definitions; \*0 = whole-gene deletion when unnamed; tagging-variant genes (HLA-A\*31:01, HLA-B\*15:02/\*57:01/\*58:01, IFNL3/4 rs12979860) with population-reliability caveat; per-array **masked-variant list** (seed from `pgx_masked_variants.csv` concept, but derive our own from concordance data); per-array known-limitation table (indistinguishable pairs such as CYP4F2 \*1/\*2, \*3/\*4; CYP2D6 \*40/\*58; NUDT15 \*6/\*9; UGT1A1 TA-repeat not callable).
15. **Version-pinned sources** in output metadata (star-allele sources, phenotype sources, mapping-DB hash). Target equivalents: PharmVar ≥ 6.1, PharmGKB snapshot, CPIC ≥ 1.38, DPWG ≥ 2023-06; UGT legacy nomenclature; CYP legacy archive for CYP1A2/CYP2E1 lettered alleles.
16. **Phenotype lookup coverage**: CPIC 17 genes (activity: CYP2C9, CYP2D6, DPYD), DPWG 14 genes incl. CYP1A2, CYP3A4, F5 (activity: CYP2D6, DPYD); default "Normal" for reference-only calls (ABCG2 bug to avoid); user switch `--guideline cpic|dpwg`, default CPIC.
17. **Variant-based gene reporting**: ~37 genes reported as `Reference` / `rsID.REF>ALT` calls (DPYD, RYR1, CFTR, OPRM1, …) — spec must support "Variant" call type alongside "Haplotype"; use `>` consistently.
18. **Output files**: diplotype summary, annotations, supporting variants, unresolved variants, not-covered variants, per-sample JSON; intermediate call file separable from annotation step.
19. **Input guard**: the SNV VCF used for PGx must not be de-duplicated/filtered; bgzip + tabix required; combined-probe genotype resolution rules (conflicting probes → no-call).
20. **Semi-custom arrays**: map to the parent commercial PGx content; ignore extra content; warn if commercial PGx probes are missing.
### 9.3 QC module (§9) — methylation (currently only "optional" in scope item 14)
21. Specify a **methylation control-QC submodule** with the 21 metrics and formulas of §3.3, `bkg_G`/`bkg_R` definitions, offset x = 3000, per-array default threshold sets (EPIC vs MSA table §3.2), Restoration 0→1 FFPE switch, `passQC` = all 21 pass, `failCodes`.
22. Signal pipeline: noob background correction + dye-bias correction + detection p-value (pOOBAH-style, threshold 0.05), beta and M-value per CpG; `prop_probes_passing` reported but **not** used for pass/fail (configurable option). Oracle: SeSAMe (R, MIT) via subprocess; open question: exact p-value/beta offset → verify against the tech note.
23. Outputs: per-sample control table (MG/MR/UG/UR), per-sample CpG table (beta, M, p), batch QC table (xlsx+tsv with highlighting), PCA of betas (random 10k probes when > 100 samples), coloured by Sample_Group, pass-rate histogram; SeSAMe-style manifest export.
24. Manifest parser must validate `[Assay]`/`[Controls]` sections and required columns, and report missing control types/names by setting the metric to NA with a warning.
25. Genotyping control QC (§9.1) should add **Restoration** and document **Stringency/NSB** vs methylation's specificity metrics; add a `TGA control` style metric used by the PGx review rule (< 1.0).
### 9.4 Orchestration / workflow (cross-cutting, plan §13–§14)
26. **Scan-registration gate**: read scanner `metrics.txt`; exclude sections with stripe registration < 0.75; per-sample Ready/Failed/Pending status file.
27. **Planned-run mode**: a watch/queue command that starts when all sample-sheet samples have IDATs, aborts if failed-scan count > `max_failed_scans`, else runs with passing samples.
28. **Duplicate IDAT detection**: error (not silent pick) when > 1 IDAT pair maps to the same barcode+position; deterministic OS-independent behaviour.
29. **Product consistency check**: IDAT chip type vs manifest; semi-custom mapping.
30. **Output toggles**: VCF, Final Report, Locus Summary, GTC; QC report xlsx|csv; auto-suggest disabling large reports above ~400 samples.
31. **Per-type batch limits** documented and tested (≥1152 genotyping/cyto/methylation; ≥384 PGx).