SimurgArray/docs/research/A_cli_inputs.md

A — Local CLI & Input Files: exhaustive analysis

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.

Sources (both read in full, line by line):

• site/pages/product-guides/local-analysis.md (647 lines, "[product] Local Analysis")
• site/pages/product-guides/input-files.md (205 lines, "Input Files")

Conventions in this document: "the vendor tool" = the analysed product; executable name is refcli. Line references L:n = local-analysis page, I:n = input-files page. Verbatim quotes are in code or "quotes". Items marked [DOC-INCONSISTENCY] are contradictions/omissions in the source docs themselves.

Images: neither page contains any image reference (no ![], <img>, .png/.jpg/.svg, or gitbook/assets URLs). Only external hyperlinks exist (listed in §8).

---

1. Complete command reference

1.1 General syntax (L:143-147)

refcli [module] [sub-module (not needed for cyto)] [command] [required parameters] [optional parameters]

• Command names are lowercase; CLI options are case-sensitive and must be typed exactly, notably mixed-case --threshold-callRate and --threshold-logRdev (L:147, repeated L:564).
• Top-level modules (L:149-156):

Module	Description (verbatim)
qc	Extract control probe intensities, compute QC metrics and generate QC reports.
genotype	Call genotypes, single nucleotide variants, and various related file conversions.
pgx	Pharmacogenomics CNV, star allele calling and metabolizer status annotation.
cyto	Cytogenetics CNV/LOH/mosaic calling and annotation.
help	Display more information on a specific command.
version	Display version information.

• refcli help — "Displays the first-layer help information." (L:160)
• refcli version — "Displays current [product] Local version." (L:164). Used as installation check (L:55).
• Every module and sub-module also has its own help and version commands; every leaf command has --help and (almost all) --version flags.

Full command tree:

refcli
├── help
├── version
├── qc
│   ├── call
│   ├── report
│   ├── help
│   └── version
├── genotype
│   ├── call
│   ├── gtc-to-bedgraph
│   ├── gtc-to-vcf
│   ├── help
│   └── version
├── pgx
│   ├── copy-number
│   │   ├── call
│   │   ├── train
│   │   ├── help
│   │   └── version
│   ├── star-allele
│   │   ├── call
│   │   ├── annotate
│   │   ├── help
│   │   └── version
│   ├── help
│   └── version
└── cyto            (no sub-module)
    ├── call
    ├── annotate
    ├── help
    └── version

1.2 Common option semantics (apply to all leaf commands where present)

Flag	Type	Default	Meaning
--debug	boolean switch	false	"Includes stack traces in logs." / "Logs will include stack traces."
--json-log	boolean switch	false	"Outputs logs in JSON format." (JSON schema not documented on these pages)
--help	switch	—	Command help screen ("Display this help screen.")
--version	switch	—	"Displays version information." (absent from qc call table)
--output-folder	path	CWD for qc call, qc report, pgx copy-number train, star-allele call/annotate, cyto call/annotate; not stated for genotype call, gtc-to-bedgraph, gtc-to-vcf, pgx copy-number call	Output directory. Re-using an output folder overwrites older files (L:87).
--sample-sheet	path (CSV)	—	Filter samples and supply metadata; see §3.9
--idat-folder / --gtc-folder	directory	—	Root folder; recursive (includes subdirectories, stated for idat-folder). Overrides sample-sheet RootFolder.

Rule repeated for every sample-set command: "Either --idat-folder, --sample-sheet, or both are required inputs." (qc call L:192, genotype call L:256) / "Either --gtc-folder, --sample-sheet, or both are required inputs." (gtc-to-bedgraph L:273, gtc-to-vcf L:324). For pgx copy-number call/train and cyto call the same pattern is implied (--gtc-folder not marked required) but not stated explicitly.

1.3 qc call (L:177-192)

"Performs QC sample analysis given raw iScan data (IDAT)." / "Extracts raw control probe intensities and computes QC metrics from IDAT files."

Option	Req	Type	Default	Allowed	Description
--array-type	Required	enum	—	genotyping, methylation	Array type for QC analysis
--csv-manifest	Required	path	—	—	CSV manifest
--idat-folder	"[Required]" in table, but see note	dir	—	—	IDAT dir incl. all subdirectories; overrides sheet RootFolder
--sample-sheet	optional	path	—	—	Sample sheet for filtering
--output-folder	optional	dir	CWD	—	Output dir
--debug	optional	bool	false	—	stack traces
--help	—	—	—	—	help
--json-log	optional	bool	false	—	JSON logs

Note: "Either --idat-folder, --sample-sheet, or both are required inputs." [DOC-INCONSISTENCY] table says --idat-folder "[Required]" while the note says sheet alone suffices. No --version, no --num-threads, no BPM (QC uses the CSV manifest's [Controls] section, not BPM). Outputs (from L:106-107,196): controls.raw_metrics.csv, controls.qc_metrics.csv.

1.4 qc report (L:194-216)

Generates QC Report (interactive HTML) + QC Table (spreadsheet) from one or more dataset folders. Inputs per dataset folder: controls.raw_metrics.csv (required), controls.qc_metrics.csv (required), from qc call or genotype call; gt_sample_summary.csv ("highly recommended", optional) from genotype call for "functional QC". Supports "parent-folder discovery, dataset labeling, and interactive dashboards".

Option	Req	Type	Default	Description
--data	Required	<path[,path,...]>	—	One or more dataset folders, comma-separated; or one parent folder → datasets auto-discovered beneath it
--config	optional	<file> YAML	built-ins	Default QC thresholds. CLI thresholds override config. Built-in defaults callRate = 0.98, logRDev = 0.20; "All other thresholds are unset by default."
--label	optional	<label[,label,...]>	dataset folder names	One label per dataset; count must equal number of datasets
--output-folder	optional	dir	CWD
--output-format	optional	<csv|xlsx>	xlsx	Format of sample QC table; XLSX has conditional colouring and a "Thresholds" sheet
--threshold-callRate	optional	<value> float	0.98	Functional QC call-rate threshold; overrides YAML
--threshold-logRdev	optional	<value> float	0.20	Functional QC LogRDev threshold; overrides YAML
--debug	optional	bool	false
--json-log	optional	bool	false
--help, --version	—	—	—

Precedence: CLI threshold > YAML --config > built-in defaults (L:212). Example (verbatim, L:109): refcli qc report --data /user/gtc --config /user/config.yaml --output-folder /user/qc_report --label dataset_name Privacy warning (danger hint, L:214-216, verbatim): "If the input data for qc report was generated while using a sample sheet, sample metadata such as sample names, process information, and other sample-sheet values will be carried into the QC report outputs, including tables and HTML files. Review QC report outputs before sharing them. If you need to remove some metadata before sharing, remove it from gt_sample_summary.csv and rerun the qc report command." → i.e. the report reads metadata from gt_sample_summary.csv, and editing that CSV is the supported redaction path. Also covers methylation arrays (L:101). Details delegated to sub-page qc-report.md (anchors: #metadata-propagation-gt_sample_summary, #multiple-dataset-folders, #parent-folder-containing-multiple-dataset-folders, #configuration-file-optional).

1.5 genotype call (L:238-256)

"Determines genotype calls (GTC) from IDAT files."

Option	Req	Type	Default	Description
--bpm-manifest	Required	path	—	BPM manifest
--cluster-file	Required	path	—	EGT cluster file
--idat-folder	cond.	dir	—	recursive; overrides sheet RootFolder
--sample-sheet	cond.	path	—	filtering + metadata
--debug	opt	bool	false
--gencall-cutoff	opt	float	0.15	"GenCall score cutoff to label a NoCall."
--help	—
--json-log	opt	bool	false
--num-threads	opt	int	not documented	"Number of parallel threads to run." (only command with a threads flag)
--output-folder	opt	dir	not stated
--version	—

Outputs (implied on this page): <sample>.gtc (GTC v5, L:277), controls.raw_metrics.csv, controls.qc_metrics.csv, gt_sample_summary.csv (genotype sample summary; sample-sheet optional columns are echoed as-is, I:104). Example (verbatim): refcli genotype call --bpm-manifest /user/productfiles/manifest.bpm --cluster-file /user/productfiles/clusterfile.egt --idat-folder /user/IDATs --output-folder /user/gtc

1.6 genotype gtc-to-bedgraph (L:258-273)

Converts GTC to BedGraph visualisation files "from the Log R Ratio and B-allele frequency data" (L:260); the module table (L:233) says only "log R ratio data" [DOC-INCONSISTENCY].

Option	Req	Type	Default	Description
--bpm-manifest	Required	path	—	BPM
--gtc-folder	cond.	dir	—	overrides RootFolder
--sample-sheet	cond.	path	—
--debug, --json-log	opt	bool	false
--help, --version	—
--output-folder	opt	dir	not stated

1.7 genotype gtc-to-vcf (L:275-325)

"Converts GTC (v5) to SNV VCF Files. The command is only applicable for Genotype Call Files produced by [product] Array." (i.e. GTCs from other producers, e.g. older AutoConvert/GenomeStudio, are unsupported/untested).

Option	Req	Type	Default	Description
--bpm-manifest	Required	path	—	BPM
--csv-manifest	Required	path	—	CSV manifest "with SourceSeq column"
--genome-fasta-file	Required	path (.fa)	—	".fai" must be in same directory
--gtc-folder	cond.	dir	—	overrides RootFolder
--sample-sheet	cond.	path	—
--auxiliary-loci	opt	path (VCF)	—	"VCF file with auxiliary definitions of loci, such as for multi-nucleotide variants"
--debug	opt	bool	false
--disable-genome-cache	opt	bool	(cache on)	"Disables the reference genome cache."
--filter-loci	opt	(path? text file)	—	"Generates a text file containing a list of probe names to be filtered." [DOC-INCONSISTENCY/ambiguous]: wording says "generates", but it is almost certainly an input list of probe names to exclude (L:419 "without filter loci" treats it as a filter applied to VCF content).
--unsquash-duplicates	opt	bool	false	"Generates unique VCF records for duplicate assays."
--help	—
--json-log	opt	bool	false
--no-bgzip	opt	bool	false	"VCFs are not bgzip compressed (.gz) and no tabix index files (.tbi) are output."
--use-infI-nc-info	opt	bool	false	"When combining loci, use Infinium I probe no-calls to constrain possible genotypes." (mixed-case I in flag)
--output-folder	opt	dir	not stated
--version	—

Example (verbatim): refcli genotype gtc-to-vcf --bpm-manifest /user/productfiles/manifest.bpm --csv-manifest /user/productfiles/manifest.csv --genome-fasta-file /user/productfiles/genome.fa --gtc-folder /user/gtc --output-folder /user/vcf Output file naming (from I:181 / L:425): *.snv.vcf.gz (+ .tbi), or .snv.vcf with --no-bgzip. Sub-behaviours: squashing duplicates, genome cache, auxiliary loci — see §2.

1.8 pgx copy-number call (L:357-371)

"Determines copy number variants given genotypes (GTC to CNV VCF)." "A batch of 24 samples or more are required for analysis. For a successful analysis, 22 samples must pass QC defined as having log R dev < 0.2."

Option	Req	Type	Default	Description
--cn-model	Required	path (.dat)	—	PGx CN model
--gtc-folder	cond.	dir	—	overrides RootFolder
--sample-sheet	cond.	path	—
--debug, --json-log	opt	bool	false
--no-bgzip	opt	bool	false	as above
--output-folder	"[Optional]"	dir	not stated	Recommended: same folder as SNV VCFs (star-allele call takes one VCF folder)
--help, --version	—

Note: no BPM/FASTA/EGT argument — the CN model must therefore embed/locate everything else needed (and is matched to the manifest revision; mismatch → error, I:37). Output: *.cnv.vcf.gz. Example (verbatim): refcli pgx copy-number call --cn-model /user/productfiles/manifest_pgx_model.dat --gtc-folder /user/gtc --output-folder /user/vcf

1.9 pgx copy-number train (L:373-396)

"Trains copy number model for a set of samples (GTC to CN Model File)." Generate a new model when using a customised EGT.

Option	Req	Type	Default	Description
--bpm-manifest	Required	path	—	BPM; mask file (.msk) assumed in same directory
--genome-fasta-file	Required	path	—	.fai in same directory
--platform	Required	enum	—	LCG for GDA-ePGx; EX for GSAv4-ePGx or GCRA-ePGx. Value = Assay Format heading of the CSV manifest (L:587)
--gtc-folder	cond.	dir	—	overrides RootFolder
--sample-sheet	cond.	path	—
--debug, --json-log	opt	bool	false
--disable-genome-cache	opt	bool	(cache on)
--help, --version	—
--output-folder	opt	dir	CWD	"The location to output the CN model."

Example (verbatim, L:127): refcli pgx copy-number train --bpm-manifest /user/productfiles/manifest.bpm --genome-fasta-file /user/productfiles/genome.fa --gtc-folder /user/gtc --platform LCG --output-folder /user/productfiles/cnmodelnew Second example (L:588, verbatim, [DOC-INCONSISTENCY] missing pgx module): refcli copy-number train --bpm-manifest /user/productfiles/manifest.bpm --genome-fasta-file /user/productfiles/genome.fa --gtc-folder /user/new_gtcs --platform LCG --output-folder /user/productfiles/new_cnmodel

1.10 pgx star-allele call (L:417-431)

"Calls PGx star allele diplotypes. The SNV VCF files should be generated using the [product] gtc-to-vcf command with unsquash-duplicates off (default) and without filter loci."

Option	Req	Type	Default	Description
--database	Required	path (.zip)	—	PGx database
--license-server-url	Required	URL w/ credentials	—	e.g. https://username:password@[ref-license-server]
--vcf-folder	Required	dir	—	contains *.snv.vcf.gz and *.cnv.vcf.gz
--query-license-quota	opt	bool	—	query and display quotas at beginning and end
--debug, --json-log	opt	bool	false
--output-folder	opt	dir	CWD
--help, --version	—

No --sample-sheet (samples come from VCF folder). Output: star_alleles.dat (name from the annotate example). Example (verbatim): refcli pgx star-allele call --vcf-folder /user/vcf --database /user/productfiles/DAv1.4.0-rc2-pgx-mapping-sha.b164b4aa02f34cc9b72aba020c3a8735cb8e4421.zip --output-folder /user/star-alleles --license-server-url https://username:password@[ref-license-server] Note: database file name embeds software version + content SHA (<ver>-pgx-mapping-sha.<40-hex>.zip).

1.11 pgx star-allele annotate (L:433-445)

"Annotates and summarizes the star-alleles, specifically for metabolizer statuses and outputs in a consolidated JSON report. Metabolizer status is determined through direct lookup into public PGx guidelines CPIC or DPWG." Quick-start text says it also summarizes into CSV files (L:124).

Option	Req	Type	Default	Allowed	Description
--star-alleles	Required	path (.dat)	—	—	from star-allele call
--guidelines	opt	enum	CPIC	CPIC, DPWG	guideline set
--debug, --json-log	opt	bool	false
--output-folder	opt	dir	CWD
--help, --version	—

Example (verbatim): refcli pgx star-allele annotate --star-alleles star_alleles.dat --guidelines CPIC --output-folder /user/metabolizer-statuses No license needed for annotate (only star-allele call requires quota).

1.12 cyto call (L:466-508)

"Determines copy number variants (CNV) and loss/absence of heterozygosity (LOH/AOH) given genotypes." Also mosaic events.

Option	Req	Type	Default	Description
--cn-model	Required	path (.dat)	—	cyto model
--gtc-folder	cond.	dir	—	overrides RootFolder
--sample-sheet	cond.	path	—
--debug, --json-log	opt	bool	false
--no-bgzip	opt	bool	false	(must NOT be used if cyto annotate follows)
--output-folder	"[Optional]"	dir	CWD
--help, --version	—
--min-del-probes	opt	int	10	deletions reported only if ≥ N probes
--min-del-size	opt	kb	25	deletions ≥ size
--min-dup-probes	opt	int	10
--min-dup-size	opt	kb	50
--min-loh-probes	opt	int	500
--min-loh-size	opt	kb	3000
--min-gainloh-probes	opt	int	300	GAINLOH events
--min-gainloh-size	opt	kb	500
--min-mdel-probes	opt	int	10	mosaic deletions
--min-mdel-size	opt	kb	25
--min-mdup-probes	opt	int	10	mosaic duplications
--min-mdup-size	opt	kb	50
--min-mloh-probes	opt	int	500	mosaic LOH
--min-mloh-size	opt	kb	3000
--max-mosaic-fraction	opt	float	1.0	mosaic variants with fraction ≥ this are "promoted", marked INFO HIGHFRACTION (replaces MOSAIC tag), retain their mosaic fraction value
--smoothing	opt	int	5	LRR smoothing window: number of probes on each side of centre probe

Filter descriptions all say "will be reported in the json file" — i.e. the thresholds on cyto call govern what is reported downstream (the cyto call VCF and/or a cyto.cnv.dat metadata file), duplicated on cyto annotate. Example (verbatim): refcli cyto call --cn-model /user/productfiles/cyto_model.dat --gtc-folder /user/gtc --output-folder /user/vcf

1.13 cyto annotate (L:510-545)

"Annotates samples and generates cytogenetic json reports." (gene annotations, cytogenetic bands, QC fields, variant info from the VCFs, L:138)

Option	Req	Type	Default	Description
--annotation-db	Required	path (.zip)	—	cyto annotation database
--vcf-folder	Required	dir	—	contains *.cnv.vcf.gz (+ cyto.cnv.dat)
--output-folder	"[Optional]"	dir	CWD
--debug, --json-log	opt	bool	false
--help, --version	—
--min-del-probes … --min-mloh-size	opt		same 12 flags and defaults as cyto call
--min-qual	opt	number	20	"Min CNV qual and LOH qual scores."

(no --max-mosaic-fraction, --smoothing, --no-bgzip, --sample-sheet on annotate) Example (verbatim): refcli cyto annotate --annotation-db /user/productfiles/CytoAnnotateData_DAv1.2.0.zip --vcf-folder user/vcf --output-folder /user/cyto-annotations (note the relative user/vcf in the original — likely a typo.)

1.14 Mutually exclusive / dependent option groups

• At-least-one-of groups: {--idat-folder, --sample-sheet} (qc call, genotype call); {--gtc-folder, --sample-sheet} (gtc-to-bedgraph, gtc-to-vcf, implicitly pgx cn call/train, cyto call). When both given, folder option overrides sheet RootFolder.
• Threshold precedence: --threshold-* > --config YAML > built-in.
• --label cardinality must equal number of --data datasets.
• Pipeline incompatibilities: --unsquash-duplicates and --filter-loci must not be used when star-allele call follows; --no-bgzip on cyto call must not be used if cyto annotate follows.
• No true mutually-exclusive flags are documented.

1.15 Quick-start workflows (verbatim command sequences)

Genotyping: genotype call → genotype gtc-to-vcf. QC report: genotype call (or qc call) → qc report. PGx (L:113-127): genotype call → gtc-to-vcf → pgx copy-number call (same output folder as SNV VCF) → pgx star-allele call → pgx star-allele annotate → [optional] pgx copy-number train. Cytogenetics (L:129-139): genotype call → cyto call → cyto annotate. Semi-custom PGx (L:614-623): GenomeStudio custom EGT → genotype call (semi-custom BPM/EGT) → gtc-to-vcf (semi-custom BPM/CSV) → full commercial-product PGx pipeline separately.

refcli genotype call --bpm-manifest /user/productfiles/semi_custom_manifest.bpm --cluster-file /user/productfiles/semi_custom_clusterfile.egt --idat-folder /user/IDATs --output-folder /user/semi_custom_gtcs
refcli genotype gtc-to-vcf --bpm-manifest /user/productfiles/semi_custom_manifest.bpm --csv-manifest /user/productfiles/semi_custom_manifest.csv --genome-fasta-file /user/productfiles/genome.fa --gtc-folder /user/semi_custom_gtcs --output-folder /user/semi_custom_vcfs
refcli genotype call --bpm-manifest /user/productfiles/manifest.bpm --cluster-file /user/productfiles/new_clusterfile.egt --idat-folder /user/IDATs --output-folder /user/new_gtcs

---

2. Documented behaviours

2.1 Computing requirements (L:13-24)

Category	Recommendation
CPU	8 cores
Memory	32 GB available or more
Disk	30 GB or more free
OS	Windows 10+ (win10-x64); CentOS 7+, Ubuntu 20.04+ (linux-x64)

• Cybersecurity: must not require admin; "We recommend you do not run with elevated permissions."
• Up to 500 GDA-ePGx samples per analysis batch on this hardware (L:71).
• cyto annotate needs ≥ 5 GB free disk (L:545).

2.2 Installation (L:42-65)

1. Download platform package (Windows/Linux) from support site; move to desired folder (admin may be needed for /usr/local/bin, C:\Program Files).
2. Unzip; executable is in the refcli subfolder, e.g. /usr/local/bin/<refcli>-linux-x64-DAv1.4.0/<refcli>/.
3. Optionally add to PATH; verify with refcli version (prints version on success).

• Distributed as a self-contained .NET application (bundled runtime) but needs host native libraries (the .NET DEB/RPM dependency lists: ICU, OpenSSL, zlib, libstdc++, etc.); missing libs → fails to start or runtime errors.
• Package naming convention: <refcli>-<rid>-DAv<version> (rid = win10-x64 / linux-x64).

2.3 Licensing / quota (L:26-40) — only pgx star-allele call

• Quota charged per sample analysed, including re-analysis and low-quality samples.
• Quota checked "before and after analysis but not after updating the usage"; re-run to see current usage.
• Credential from activation email passed via --license-server-url; logs record remaining quota at beginning and end.
• Internet required. Endpoints: v1.0/v1.1 [ref-license-server-legacy]; v1.2+ [ref-license-server] (new domain does not work with v1.0/1.1).
• v1.1+: precomputed quota no longer checked during analysis → an over-quota run proceeds and fails only at the end: Error updating usage. HTTP error status code: 409, and results are not written to disk. (Irrelevant to an open reimplementation except as a UX anti-pattern: never discard computed results.)

2.4 Sample minimums / batch rules

• Genotyping and cyto: no sample minimum (L:69).
• PGx CNV call: ≥ 24 samples, of which ≥ 22 pass QC (LogRDev < 0.2) (L:71, L:359). Recommended ≥ 96 samples passing LogRDev ≤ 0.2 (L:121); "Analyze batches of 96 samples or more" (L:77).
• PGx CN train: ≥ 96 samples, ≥ 90 passing LogRDev ≤ 0.2; recommended ≥ 150; diminishing returns and longer runtime beyond 3,000 (L:379, L:598).
• Batch recommendations for PGx CNV (L:73-79): same assay batch (WGA + targeted gene amplification) → same analysis batch; don't combine different reagent lots; samples processed within a two-week period from multiple library prep batches may be pooled (same reagent lots/instruments); use the standard CN model and PGx DB.
• Note boundary inconsistencies: "< 0.2" (call) vs "≤ 0.2" (train, recommendation) [DOC-INCONSISTENCY].

2.5 File discovery

• --idat-folder is searched recursively ("This path also includes the contents of all subdirectories").
• Duplicate IDAT pairs for the same SentrixBarcode_Position under one --idat-folder are not allowed (rescans must be removed/relocated before genotype call/qc call) (L:565). Behaviour on violation not stated (presumably error).
• Samples identified by <12-digit barcode>_<RxxCxx>_{Grn,Red}.idat (I:12).
• Sample sheet selects a subset of samples from the folder ("A sample sheet can be used to select specific samples out of a folder", L:85).
• RootFolder in [Header] (absolute path) is used when no folder option; CLI folder option wins on conflict.
• star-allele call pairs *.snv.vcf.gz and *.cnv.vcf.gz in one folder; cyto annotate needs *.cnv.vcf.gz + the cyto.cnv.dat metadata file in the same folder.
• CN train finds .msk next to the BPM with the same base name as the manifest; FASTA commands find .fai next to the .fa.

2.6 Overwrite behaviour

"[product] will overwrite older files if using the same --output-folder from a previous analysis. If this is not desired, use different --output-folder for re-analyses." (L:87) — silent overwrite, no --force.

2.7 Threading

Only genotype call --num-threads ("Number of parallel threads to run."), default undocumented. Other commands have no thread control.

2.8 Genome cache (L:302-304)

Default: whole reference genome read into memory (faster than indexed disk reads, more RAM). --disable-genome-cache for low memory or small manifests (gtc-to-vcf, pgx copy-number train).

2.9 Logging / exit

• --debug: include stack traces in logs (default off).
• --json-log: JSON-formatted logs (default off). Field schema not documented here (see output-files page #section-warningerror-messages-and-logs).
• Logs record license quota at start/end for star-allele call.
• Cancel with Ctrl+C. Exit codes not documented. On quota failure, nothing written.
• Error on cluster/CN-model mismatch in v1.0: "produce an error and exit" (L:594).

2.10 Squashing duplicates (L:298-300)

Default: multiple assays probing the same variant (same or alternate designs) are squashed into one VCF record reflecting the true variant; method in output-files VCF description. --unsquash-duplicates → one record per assay (for assay validation). Exception: multi-allelic loci queried with duplicated designs are never unsquashed. "DO NOT use --unsquash-duplicates option if doing star allele calling downstream as that command expects squashed variants."

2.11 Infinium I no-call info

--use-infI-nc-info: when combining loci, Infinium I probe no-calls constrain possible genotypes (details on output-files page #using-infinium-i-nocall-information). Default off.

2.12 Auxiliary loci (L:306-320)

MNVs unsupported upstream; can be designed as SNP assay e.g. true ATGC[AT/CG]GTAA designed as ATGC[A/C]NNNN. --auxiliary-loci <VCF> restores true alleles. Restrictions (verbatim):

• "The auxiliary definition must NOT be a multi-allelic variant."
• "The auxiliary definition must be a multi-nucleotide variant."
• "There must NOT be multiple array assays (e.g., duplicates) for the locus."

2.13 Cyto call behaviours (L:498-508)

• 10 probes per region recommended for confident CNV calls.

• Any probe-min threshold < 10 is silently reset to 10 (applies to call and annotate).
• Threshold > effective genome size → all variants filtered out.

• 10 events (DEL/DUP/AOH) per chromosome → indication for visual inspection.

• Mosaic fraction not estimable (insufficient informative probes) → NaN.
• Mosaic events ≥ --max-mosaic-fraction: INFO MOSAIC replaced by HIGHFRACTION.
• Mosaic events < 15–20 % fraction may be missed (sensitivity limit).
• LogRDev > 0.2 → low-quality; flagged with SampleQuality flag in VCF.
• LogRDev > 0.3 → very noisy; only whole-chromosome-level events detected/reported.

2.14 Cyto annotate behaviours (L:539-545)

• cyto.cnv.dat metadata file produced by cyto call must remain in the vcf-folder.
• VCFs must be bgzipped + indexed.
• ≥ 5 GB free disk.

2.15 Custom cluster files and CN models (L:572-602)

• Custom EGT created in GenomeStudio 2.0; EGT file name: only [A-Za-z0-9_-], no spaces/special chars.
• For PGx products a GenomeStudio auxiliary file (tab-delimited, Column Import) maps Infinium assays → PGx star alleles, for reviewing cluster positions of PGx variants.
• If EGT customised, PGx CN model should be retrained with the same samples used for the EGT.
• v1.1+: CN model with a different cluster file → warning, proceeds. v1.0: same EGT required → error & exit.
• Training QC recommendation: remove samples with LogRDev > 0.2, call rate < 0.99, or TGA control probe < 1.0; same reagent lots; few batches.
• Algorithm assumption: training cohort's CN distribution resembles standard population distributions.
• Validate a retrained CN model with truth data before use.

2.16 Semi-custom arrays (L:604-625)

• PGx CNV and star-allele calls limited to commercial content; add-on content excluded.
• Retain all backbone content when designing semi-custom PGx arrays.
• Run pipeline twice: semi-custom files for SNV VCFs, commercial files for PGx. Semi-custom GTC/VCFs "cannot be used for downstream PGx analysis commands". Keep in clearly labelled folders.

2.17 CLI tips (L:561-570)

Quote paths with spaces; case-sensitive options; no duplicate IDAT pairs; up-arrow to edit; copy-paste paths; Windows "Copy as Path"; Ctrl+C cancels.

---

3. Input file types

#	File	Ext	Source	Commands (option)
3.1	IDAT	.idat	scanner (iScan, NextSeq550 for select arrays)	genotype call, qc call (--idat-folder)
3.2	CSV manifest	.csv	vendor	gtc-to-vcf, qc call (--csv-manifest)
3.3	BPM manifest	.bpm	vendor	cn train, genotype call, gtc-to-bedgraph, gtc-to-vcf (--bpm-manifest)
3.4	Cluster file	.egt	vendor or GenomeStudio	genotype call (--cluster-file)
3.5	PGx CN model	.dat	vendor or pgx copy-number train	pgx cn call (--cn-model)
3.6	Cyto CN model	.dat	vendor	cyto call (--cn-model)
3.7	Mask	.msk	vendor	cn train (implicit, next to BPM)
3.8	PGx database	.zip	vendor	star-allele call (--database)
3.9	Cyto database	.zip	vendor	cyto annotate (--annotation-db)
3.10	Genome FASTA (+.fai)	.fa	vendor	gtc-to-vcf, cn train (--genome-fasta-file)
3.11	YAML config	.yaml/.yml	template or user	qc report (--config)
3.12	Sample sheet	.csv	user	genotype call, gtc-to-bedgraph, gtc-to-vcf, cn call, cn train, cyto call, qc call (--sample-sheet)
3.13	GTC	.gtc	genotype call	gtc-to-bedgraph, gtc-to-vcf, cn call, cn train (--gtc-folder) [cyto call also]
3.14	SNV VCF / PGx CNV VCF	.snv.vcf / .cnv.vcf	gtc-to-vcf / cn call	star-allele call (--vcf-folder)
3.15	PGx DAT	.dat	star-allele call	star-allele annotate (--star-alleles)
3.16	Cyto CNV VCF	.cnv.vcf	cyto call	cyto annotate (--vcf-folder)
3.17	QC dataset folder CSVs	.csv	qc call / genotype call	qc report (--data)
3.18	Auxiliary loci VCF	.vcf	user	gtc-to-vcf (--auxiliary-loci)
3.19	Filter-loci list	.txt	user	gtc-to-vcf (--filter-loci)

Note: the summary table omits cyto call from GTC consumers and omits 3.17–3.19. Product files (all but IDATs) download: [ref-docs:downloads].

Details:

• 3.1 IDAT: one pair per sample, Red and Grn channels, intensities per probe. Identified by 12-digit Sentrix barcode (e.g. 123456789101), position R01C01, and Grn/Red.
• 3.2/3.3 Manifests: commercial from support site; custom/semi-custom from MyIllumina. "[product] only supports manifest files from the Illumina Support site." CSV is human-readable complement to BPM; required for indel VCF generation; gtc-to-vcf may be inaccurate if mapping info wrong. Mapping follows implicit dbSNP standard: 1-based positions; PAR positions reported on X; insertion → position of base immediately 5′ of insertion (plus strand); deletion → position of most 5′ deleted base (plus strand). CSV heading contains Assay Format (e.g. LCG, EX) used for --platform. CSV must have SourceSeq.
• 3.4 EGT: required for genotype call; custom may be needed; naming restriction [A-Za-z0-9_-].
• 3.5 PGx CN model: one per PGx product; named after the manifest revision (e.g. B1) and must be used with the same-revision manifest. Must be retrained when EGT customised (v1.1+ only warns on mismatch).
• 3.6 Cyto model: one per supported product; named after manifest revision; must match. Contains primarily probe GC content information; tied to probe sequence/manifest; no retraining needed unless manifest or software version changes; independent of cluster file. Custom products: contact support with BPM, EGT and IDAT/GTC for ≥ 1 sample.
• Model/manifest mismatch → error during pgx copy-number call and cyto call (probes added/removed between revisions).
• 3.7 Mask: required for CN train; same base name as manifest, same folder as BPM; one per PGx product.
• 3.8 PGx DB: zip; each line maps one probe ID → a variant HGVS tag (many probes → one variant); cross-referenced with SNV VCF IDs at runtime; one DB works across all supported PGx products.
• 3.9 Cyto DB: zip of Ensembl + RefSeq data; product-independent; may be updated.
• 3.10 FASTA: .fa + .fai in same folder; PGx supports GRCh37 and GRCh38; custom references: contig IDs must match manifest chromosome IDs exactly — >1, not >chr1, for standard human manifests.
• 3.11 YAML: set threshold to a number to enable, null to disable; without --config built-ins for callRate and logRDev only; cloud uses chemistry-specific default configs.
• 3.12 Sample sheet: see §3.12 detail below.

3.12 Sample sheet detail (I:56-147)

• CSV. Required key columns: local SentrixBarcode_A, SentrixPosition_A; cloud beadChipName, sampleSectionName. Backwards compatible with most GenomeStudio sheets.
• Sections optional: [Header] (with RootFolder,<abs path>, arbitrary keys e.g. Date,1/1/2025), [Data]. [Manifests] section is ignored. Sectionless sheets valid (header row first line).
• Valid examples (verbatim):

SentrixBarcode_A,SentrixPosition_A
204753010023,R02C01

SentrixBarcode_A,SentrixPosition_A,Sample_ID,Sample_Group,MetaData1
204753010023,R01C01,NA1231,Group1,F
204753010024,R01C01,NA1233,Group2,M

[Header]
RootFolder,/tests/samples
Date,1/1/2025
[Data]
SentrixBarcode_A,SentrixPosition_A,Sample_ID,Sample_Group,MetaData1
204753010023,R01C01,NA1231,Group1,F
204753010024,R01C01,NA1233,Group2,M

• Column names case-insensitive; duplicates after case-folding are an error.
• Column names must not collide with genotype-summary output fields (reserved keywords, e.g. Sex Estimate).
• Optional columns are echoed as-is into genotype summary files (gt_sample_summary.csv).
• Column names and field values ≤ 500 characters.
• Excel: format SentrixBarcode_A as number with 0 decimals; text-with-decimal or scientific notation → IDAT names cannot be resolved → run fails.
• Sample name precedence: (1) sheet Sample_Name (if column present, must be non-empty in every row and must not conflict with default ID SentrixBarcode_Position, e.g. 204753010023_R01C01); (2) sample name embedded in IDAT/GTC metadata; (3) SentrixBarcode_Position. Sheet value never rewrites the name stored in the GTC; affects only downstream outputs (summary, VCFs); "the samplesheet for any given command is treated as the source of truth".
• Cloud methylation QC sheet: no sections; keys beadChipName,sampleSectionName; Sample_Group colours PCA control plot/Principal Component Summary; any extra columns after Sample_Group replicated to Sample QC Summary outputs.

beadChipName,sampleSectionName,Sample_ID,Sample_Group,MetaData1
204753010023,R01C01,NA1231,Group1,F
204753010023,R02C01,NA1232,Group2,F
204753010024,R01C01,NA1233,Group2,M
204753010024,R02C01,NA1234,Group1,M

• Cloud cyto + interpretation sheet: column demographicSex ∈ {M,F,U} compared against Sex Estimate.

SentrixBarcode_A,SentrixPosition_A,demographicSex
204753010023,R01C01,F
204753010023,R02C01,F
204753010024,R01C01,M
204753010024,R02C01,M

---

4. Error / warning messages (verbatim) and triggers

Message	Trigger	Source
Error updating usage. HTTP error status code: 409	v1.1+ star-allele call exceeded quota; detected at end; results not written	L:40
Duplicate column sample_name found. Column names are case-insensitive. Please remove or rename the column from the samplesheet and re-process.	two sheet columns equal after case-folding (e.g. Sample_Name, sample_name)	I:102
Sex Estimate is a reserved keyword. Please remove or rename the column from the samplesheet and re-process.	sheet column collides with a genotype-summary output field	I:103
(warning, text not given) CN model built with different cluster file	v1.1+ pgx copy-number call; proceeds	L:593
(error & exit, text not given) cluster file differs from CN-model training	v1.0	L:594
(error, text not given) CN/cyto model vs manifest mismatch	pgx copy-number call, cyto call	I:37
(failure, text not given) barcode unreadable from sheet (Excel sci-notation)	IDAT name resolution	I:107
(validation, text not given) name/value > 500 chars	sample sheet	I:106
(validation, implied) Sample_Name empty in some row, or equals another sample's default ID	sample sheet	I:113
(implied) --label count ≠ dataset count	qc report	L:202
(implied) missing controls.*_metrics.csv in dataset folder	qc report	L:200
(silent) probe threshold < 10 reset to 10	cyto call/annotate	L:501, L:541
(implicit) license domain mismatch with v1.0/1.1	star-allele call	L:39
"application may fail to start or produce runtime errors"	missing .NET native libs	L:61

---

5. Numeric thresholds and defaults (consolidated)

Value	Meaning
8 cores / 32 GB / 30 GB disk	recommended hardware
5 GB	free disk for cyto annotate
500	max GDA-ePGx samples per batch on recommended HW
0.15	--gencall-cutoff default (GenCall score < cutoff → NoCall)
0.98	qc report call-rate threshold default
0.20	qc report LogRDev threshold default; PGx/cyto QC boundary
0.3	LogRDev above which cyto reports only whole-chromosome events
0.99	call-rate recommended minimum for PGx samples / CN training samples
1.0	TGA control probe metric recommended minimum (PGx review/training)
24 / 22	PGx CNV call minimum batch / minimum passing LogRDev < 0.2
96	recommended PGx CNV batch; minimum CN train samples
90	CN train samples passing LogRDev ≤ 0.2
150	recommended CN train size
3,000	CN train diminishing returns
2 weeks	window for pooling library-prep batches
10 / 25 kb	DEL probes / size
10 / 50 kb	DUP probes / size
500 / 3000 kb	LOH probes / size
300 / 500 kb	GAINLOH probes / size
10 / 25 kb	mosaic DEL
10 / 50 kb	mosaic DUP
500 / 3000 kb	mosaic LOH
10	hard floor for any probe-count threshold
1.0	--max-mosaic-fraction
5	--smoothing probes each side (window = 11 probes)
20	--min-qual (cyto annotate)
15–20 %	mosaic detection lower limit
> 10 events/chromosome	visual-inspection trigger
500 chars	sample-sheet name/value limit
12 digits	Sentrix barcode length
409	HTTP status on over-quota
CPIC	default guideline
xlsx	default QC table format

---

6. Algorithmic hints

• Genotype calling: GenCall score with no-call cutoff 0.15; uses BPM + EGT (standard GenCall-style pipeline). Outputs GTC v5 plus control metrics and sample summary (call rate, LogRDev, Sex Estimate, TGA control metric…).
• Control QC (qc call): control-probe intensity extraction from IDAT using the CSV manifest (Controls section); supports genotyping and methylation arrays; outputs raw metrics and computed QC metrics.
• Functional QC: pass/fail on call rate ≥ 0.98 and LogRDev ≤ 0.20 (direction presumed); other thresholds optional via YAML (numeric enables, null disables).
• gtc-to-vcf: REF from FASTA (whole-genome in-memory cache by default); indels resolved from CSV SourceSeq; duplicate assays squashed into single variant-level genotypes; optional use of Infinium I no-calls as constraints; MNV restoration from auxiliary VCF (SNP-designed proxies with N flanks); multi-allelic sites combine multiple assays; probe IDs used as VCF IDs (PGx DB joins on VCF ID).
• BedGraph: LRR and BAF tracks from GTC + BPM positions.
• PGx CNV: batch-based caller (needs ≥ 24 samples/≥ 22 good ones → cohort normalisation / batch-effect sensitive); model file (.dat) tied to manifest revision and (in v1.0) to cluster file → model contains per-probe intensity reference parameters derived from EGT-normalised data; training requires BPM + mask (probe exclusion) + FASTA (likely GC content / probe positions) + platform code (LCG vs EX assay format), assumes population-typical CN distribution (i.e. unsupervised mixture fit where the modal state is CN2 and prior frequencies ≈ population).
• Star alleles: probe→HGVS mapping DB; SNV + CNV VCFs combined; expects squashed variants and unfiltered loci; output .dat then annotate with CPIC/DPWG lookup (direct table lookup for metabolizer status).
• Cyto: model = probe GC content (→ GC-wave correction of LRR); LRR smoothing with ±5-probe window; CNV/LOH/AOH/ GAINLOH (gain with LOH, i.e. CN≥3 with no heterozygosity) and mosaic DEL/DUP/LOH with mosaic fraction estimate (NaN if too few informative probes); promotion of high-fraction mosaic events (HIGHFRACTION); QUAL scores for CNV and LOH (min 20 at annotate); sample-quality flag at LogRDev > 0.2; whole-chromosome-only mode at > 0.3; "effective genome size" concept; annotation with Ensembl/RefSeq genes and cytobands to JSON.
• CN training QC: exclude LogRDev > 0.2, call rate < 0.99, TGA control < 1.0.

---

7. Gap analysis vs SimurgArray plan

Plan sections compared: §1 goals, §6 formats, §8 VCF, §9 QC, §10 CN/LOH, §11 PGx, §13 outputs, §14 CLI, §15, §19.

7.1 CLI structure & global behaviour

#	Vendor behaviour	Plan status	Suggested spec addition
G1	Hierarchical module sub-module command; help/version at every level	flat simurg <verb>	Keep flat verbs but add simurg <verb> --help everywhere and a simurg version subcommand; optionally provide a compatibility alias layer mapping genotype call, genotype gtc-to-vcf, qc call, qc report, cyto call … to simurg verbs for users migrating scripts.
G2	--debug (stack traces) separate from logging format	--log-level only	Add --debug = include tracebacks + DEBUG level.
G3	--json-log	--log-json	Fine; document JSON log schema (timestamp, level, sample, step, message, error_code). Consider accepting --json-log as alias.
G4	Silent overwrite of output folder	"never silently overwrite (require --force)"	Keep safer default; document that re-running into the same folder requires --force or --resume.
G5	Folder OR sheet OR both; folder overrides sheet RootFolder	--idats DIR|--sheet F (exclusive)	Allow both together: sheet filters, --idats/--gtcs overrides sheet RootFolder; sheet alone uses RootFolder; error if neither.
G6	Recursive IDAT discovery; duplicate barcode_position pairs disallowed	recursive discovery mentioned	Specify: recursive search, .idat and .idat.gz, error E_DUP_IDAT listing all paths when the same barcode_position is found twice; `--allow-duplicates=first
G7	--num-threads only on genotype call	--threads common	OK; specify default = all physical cores (document).
G8	Genome in-memory cache default, --disable-genome-cache	not specified	Add FASTA access policy: default load whole genome (or mmap) with --no-genome-cache to use indexed random access.
G9	--no-bgzip on VCF writers	always bgzip	Add --no-bgzip (plain .vcf, no index) with warning that downstream CN annotate/PGx require compressed+indexed input.
G10	Exit codes undocumented; quota failure discards results	defined exit codes	Keep; add rule: results computed are always written before any post-processing step can fail.
G11	Case-sensitive, mixed-case flags	n/a	Use lowercase kebab-case only; no mixed-case flags.
G12	Self-contained distribution, OS list, HW recommendation (8 cores/32 GB/30 GB)	§3 dev machine only	Add "user runtime requirements" section: supported OS/arch, min/recommended RAM per workload (e.g. 500-sample CN batch), disk for annotation DBs, no-root operation.
G13	Licence/quota server	none (open)	Out of scope; explicitly state no network access required at runtime (offline-first).

7.2 Genotyping (genotype call equivalent)

#	Vendor	Plan	Suggestion
G14	Outputs per batch: controls.raw_metrics.csv, controls.qc_metrics.csv, gt_sample_summary.csv produced by genotype call itself	§13 has controls_raw.tsv, controls_qc.tsv, sample_summary.tsv	Make simurg genotype emit control metrics + sample summary automatically (so QC report works directly on the genotype output folder); offer CSV output with compatible column names as an option (--summary-format csv).
G15	Sample-sheet metadata columns echoed as-is into sample summary	not specified	Specify: all non-key sheet columns propagated verbatim (order preserved) into sample_summary and QC report; reserved-name check.
G16	GTC sample name not rewritten by sheet; sheet is source of truth per command	§6.6 precedence only	Add: name resolution happens per command; GTC-stored name is kept; downstream outputs use sheet value. Add rule Sample_Name non-empty for all rows if column present and must not equal another sample's default barcode_position ID.
G17	Custom EGT naming restriction	none	Validate output EGT names from ArrayTrain [A-Za-z0-9_-] (portability), warn on others.

7.3 gtc-to-vcf equivalent

#	Vendor	Plan	Suggestion
G18	--auxiliary-loci VCF to restore MNV alleles for SNP-proxy designs (with 3 restrictions)	absent	Add --auxiliary-loci FILE.vcf: records keyed by probe ID/position override REF/ALT for single-assay, biallelic MNV loci; validate restrictions and error otherwise.
G19	--filter-loci text list of probe names to exclude	absent	Add --exclude-loci FILE (one probe name per line) and --include-loci; record in provenance; warn when PGx step later consumes filtered VCFs.
G20	--use-infI-nc-info (Infinium I no-calls constrain combined genotypes)	multi-probe merge in §8.3 but no Inf-I no-call rule	Add opt-in rule: when merging probes, an Infinium I probe no-call removes candidate genotypes that the probe would have been able to distinguish; default off.
G21	Multi-allelic duplicated designs never unsquashed	§8.3 unsquash described generally	Specify exception: --unsquash-duplicates has no effect for multi-allelic sites.
G22	Only GTC v5 from own caller accepted	plan reads v3–v5	Keep broader support, but warn when GTC lacks v5 fields (BAF/LRR/percentiles) or was produced by other software.
G23	CSV manifest required, must contain SourceSeq; mapping conventions (1-based, PAR on X, indel anchor positions)	§6.3/§8.1 partial	Add explicit validation of manifest mapping conventions: PAR loci on X coordinates, insertion anchor = base 5′ of insertion, deletion = first deleted base; convert to VCF left-anchored representation.
G24	FASTA contig names must exactly match manifest chrom names (1 not chr1)	alias table (more permissive)	Keep alias table but document default strict mode and the alias opt-in; verify .fai exists next to FASTA (or build it).
G25	Output naming <sample>.snv.vcf.gz, CNV <sample>.cnv.vcf.gz	<sample>.vcf.gz, <sample>.cnv.vcf.gz	Adopt .snv.vcf.gz suffix to disambiguate SNV and CNV VCFs coexisting in one folder.

7.4 bedGraph

| G26 | Dedicated command from GTC+BPM producing LRR and BAF bedGraphs | export bedgraph | Covered; ensure it takes GTC folder + sheet and works without re-running genotyping. |

7.5 QC

#	Vendor	Plan	Suggestion
G27	qc call works directly from IDAT + CSV manifest (no EGT/BPM), `--array-type genotyping	methylation`	methylation QC is v2 optional; control metrics derived in genotype pipeline
G28	qc report accepts multiple dataset folders (comma list) or a parent folder with auto-discovery, --label per dataset	single report	Add multi-dataset report: --data DIR[,DIR...] or parent dir discovery (any subfolder containing the two control-metrics files); --label list with cardinality check; datasets shown side by side.
G29	`--output-format csv	xlsx` (xlsx default with conditional colouring + "Thresholds" sheet)	TSV/XLSX
G30	YAML config: numeric = enable, null = disable; only callRate/logRDev enabled by default; CLI > YAML > defaults	§14 qc: block	Adopt the same tri-level precedence and null-disables semantics; record effective thresholds with their source in outputs.
G31	Privacy: sheet metadata flows into HTML; redact by editing the summary CSV and rerunning	none	Add --redact-columns COL,... and a warning in docs; report built only from summary file so edits propagate.
G32	TGA control probe metric (< 1.0 flagged) used for PGx review	not in §9	Add targeted-gene-amplification control metric for ePGx arrays to control QC (definition to be derived from control probes).

7.6 PGx CNV and star alleles

#	Vendor	Plan	Suggestion
G33	CN call: ≥ 24 samples, ≥ 22 with LogRDev < 0.2, recommended ≥ 96	§11 "≥ 24 samples"	Add explicit pre-flight check and error when fewer than N_min total / passing samples; configurable but defaulting to 24/22; warn below 96.
G34	CN train: ≥ 96 samples, ≥ 90 passing; recommend ≥ 150; plateau ~3000; QC exclusions (LogRDev>0.2, CR<0.99, TGA<1.0)	"≥ 96 for training"	Add pass-count requirement and automatic exclusion rules with report of excluded samples.
G35	Mask file (.msk) next to BPM with same base name, used in training	absent	Define an open probe-mask format (list of probe names excluded from CN modelling) discovered next to the manifest or given via --mask.
G36	--platform (assay format LCG/EX) from CSV Assay Format heading	absent	Read assay format from CSV heading automatically; allow override.
G37	CN model tied to manifest revision (error on mismatch), and to cluster file (warn on mismatch)	absent	CN model file header must store manifest name/revision + probe-set hash and EGT hash; error on manifest mismatch, warning on EGT mismatch.
G38	Batch recommendations (same reagent lot, 2-week window, same assay batch)	absent	Add documentation + optional batch-consistency warnings using sheet columns (e.g. plate/lot) if present.
G39	Star-allele input folder with paired *.snv.vcf.gz/*.cnv.vcf.gz; requires squashed, unfiltered SNV VCFs	§11 VCF input	Validate that VCF headers record unsquash=false and no filter list; refuse otherwise.
G40	Probe→HGVS mapping DB (many probes → one variant), versioned zip with content hash in name	versioned SQLite pgx_db	Include a content hash + software-version in DB filename/metadata; record in provenance.
G41	Separate annotate step: .dat → JSON + CSV, `--guidelines CPIC	DPWG` default CPIC	"phenotype" subcommand
G42	Semi-custom arrays: PGx limited to backbone content; run twice	none	Document how SimurgArray handles add-on content (likely we can include it natively; state policy).
G43	Per-sample batch size limit (500 GDA samples at 32 GB)	performance plan	Add memory model for cohort CN steps and document max batch per RAM.

7.7 Cytogenetics (genome-wide CNV/LOH)

#	Vendor	Plan	Suggestion
G44	Separate call (→ CNV VCF + metadata dat) and annotate (→ JSON) commands	`cn call	train
G45	Event classes include GAINLOH (300 probes / 500 kb) and mosaic DEL/DUP/LOH each with own thresholds	§10.2 has DEL/DUP/LOH/mosaic "same"	Add GAINLOH class and separate mosaic thresholds; 12 flags: --min-{del,dup,loh,gainloh,mdel,mdup,mloh}-{probes,size} with defaults 10/25kb, 10/50kb, 500/3000kb, 300/500kb, 10/25kb, 10/50kb, 500/3000kb.
G46	Probe threshold floor = 10 (silently reset)	none	Enforce floor 10 with a logged warning (not silent).
G47	--max-mosaic-fraction (default 1.0) → HIGHFRACTION INFO replaces MOSAIC	none	Add parameter and INFO flags MOSAIC/HIGHFRACTION; MF=NaN when not estimable.
G48	--smoothing ±5 probes LRR smoothing	none	Add --smoothing K (probes each side, default 5) pre-segmentation smoothing.
G49	--min-qual 20 at annotation	QUAL defined, cap 60	Add annotation-time QUAL filter default 20.
G50	Sample-level SampleQuality VCF flag at LogRDev > 0.2; whole-chromosome-only above 0.3	§10.2 already has these	Covered; name the flag and header line.
G51	>10 events per chromosome → needs review	none	Add per-sample QC flag EXCESS_EVENTS when any chromosome has >10 DEL/DUP/AOH calls.
G52	Cyto model = probe GC content, per manifest revision, independent of EGT; custom model on request	§10.1 compute GC from FASTA	Good: we derive GC ourselves; persist as a per-manifest model file with manifest hash; no cluster dependency.
G53	Cyto annotation DB (Ensembl+RefSeq zip), product-independent, JSON reports with genes, cytobands, QC fields	§10.4	Specify JSON report schema and a versioned annotation bundle built by script; 5 GB disk note.
G54	Annotate requires bgzipped + indexed VCF and sidecar in same folder	none	Validate and error clearly.
G55	Mosaic sensitivity limit 15–20 %	§10.3	Document target sensitivity; validate against it.

7.8 Input formats

#	Vendor	Plan	Suggestion
G56	Sample sheet: 500-char limit; reserved names = output columns; duplicate case-insensitive columns error; [Manifests] ignored; Excel sci-notation barcode failure	§6.6 partial	Add validations with messages: duplicate column (case-insensitive), reserved column name, >500 chars, empty Sample_Name, Sample_Name colliding with default IDs, non-integer barcode (detect 2.04753E+11 / 204753010023.0 and give a targeted hint). Consider auto-repairing .0 suffix with a warning.
G57	[Header] RootFolder absolute path	not in plan	Support RootFolder; relative paths resolved against sheet location (extension), CLI override.
G58	Sectionless sheets valid (first line = header)	implied	Explicitly support.
G59	Cloud variants: beadChipName/sampleSectionName keys; Sample_Group colouring in PCA plots; demographicSex M/F/U compared to sex estimate	plan uses Gender	Accept alias key columns; accept demographicSex/Gender/Sex for reported sex (M/F/U); use Sample_Group for plot colouring.
G60	Methylation QC includes PCA control plot & principal component summary	not planned	Add optional PCA of control-probe metrics coloured by group to QC report (applies to genotyping too).
G61	NextSeq550-scanned IDATs supported for select arrays	not mentioned	Test IDATs from NextSeq550 (format may differ in RunInfo/fields).
G62	Genome builds 37 and 38 for PGx	plan PGx GRCh38	Decide: support both or require 38 with explicit error.

7.9 Documentation-level items

• G63: Provide a "product file compatibility matrix" (manifest revision ↔ EGT ↔ CN model ↔ cyto model ↔ DB version).
• G64: Provide end-to-end workflow recipes (genotyping, QC report, PGx, cyto, semi-custom) mirroring §1.15.
• G65: Document the recommended sample-QC gates for downstream steps (LogRDev ≤ 0.2, call rate ≥ 0.99, TGA ≥ 1.0).

---

8. External links referenced

• [ref-docs:llms.txt]
• [ref-docs:product-page]
• [ref-docs:downloads]
• [ref-docs:support-page]
• https://support.illumina.com/array/array_kits/infinium-global-diversity-pgx/product-files.html
• https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#deb-dependencies
• https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#rpm-dependencies
• https://www.illumina.com/techniques/microarrays/array-data-analysis-experimental-design/genomestudio.html
• https://www.illumina.com/Documents/products/technotes/technote_infinium_genotyping_data_analysis.pdf
• https://youtu.be/4JTrbMUbVN0?si=ZgRDLwN6umGBhv2G
• https://www.illumina.com/content/dam/illumina/gcs/assembled-assets/marketing-literature/custom-cluster-file-tech-note-m-gl-02142/custom-cluster-file-tech-note-m-gl-02142.pdf
• https://www.illumina.com/science/consortia/human-consortia.html
• https://knowledge.illumina.com/microarray/general/microarray-general-faq-list/000003871 (NextSeq550 arrays)
• http://my.illumina.com/
• https://knowledge.illumina.com/microarray/general/microarray-general-reference_material-list/000001531
• Internal: output-files.md (#snv_vcf_file, #genotype_call_file, #genotype_summary_files, #cnv_vcf_file, #cyto_vcf_file, #star_allele_dat, #using-infinium-i-nocall-information, #section-warningerror-messages-and-logs), qc-report.md, overview/our-features.md, release notes v1.0.0/v1.1.0 known issues.