NgsRunQcChecker

URS & FS — User Requirements and Functional Specification

This document describes the controlled interface and behaviour of NgsRunQcChecker for NGS Run QC Checker.

Domain limits and critical parameters

• Performs end-to-end quality verification of NGS sequencing runs per CAP/CLIA, FDA NGS guidance, GATK Best Practices and SEQC2 standards: sequencing metrics (total reads, Q30, cluster density, pass-filter rate), enrichment metrics (on-target rate ≥60%, uniformity ≥80%, mean target depth, fold-80 penalty ≤2.0), alignment & duplication (alignment rate ≥90%, duplication rate ≤30%), contamination & integrity (cross-sample estimate ≤2%, index hopping ≤0.5%, UDI flagging), triple control verification (
• ⚠️ Critical: Thresholds DEPEND on panel type (WGS ≠ WES ≠ Targeted ≠ RNA-seq). High duplication is expected in amplicon panels but problematic in WGS. Low uniformity is irreversible. Contamination >2% makes somatic calls unreliable. Any control failure = automatic run FAIL. Non-UDI + high hopping = false-positive risk in multiplexed runs. Run-level QC complements but does not replace sample-level QC and clinical variant interpretation.

URS — User Requirements Specification

input.csv contract

RunID,PanelType,Platform,ReadLength,TotalReads_Million,MinTotalReads_Million,PercentQ30,MinQ30,ClusterDensity_K_mm2,MinClusterDensity,MaxClusterDensity,PercentPF,MinPercentPF,OnTargetRate_Percent,MinOnTargetRate_Percent,Uniformity_Percent,MinUniformity_Percent,MeanTargetDepth_X,MinMeanTargetDepth_X,Fold80_BasePenalty,MaxFold80,AlignmentRate_Percent,MinAlignmentRate_Percent,DuplicationRate_Percent,MaxDuplicationRate_Percent,InsertSize_Mean_bp,InsertSize_SD_bp,ContaminationEstimate_Percent,MaxContamination_Percent,PositiveControl_Pass,NegativeControl_Pass,PhiX_Control_Pass,PhiX_ErrorRate,MaxPhiX_ErrorRate,SamplesInRun,SamplesPassingQC,IndexHoppingRate_Percent,MaxIndexHoppingRate_Percent,UDI_Used
NGS-RUN-2026-001,Targeted_Panel,NovaSeq 6000,2x150,250,100,89.5,75,950,800,1200,88.0,70,82.0,60,93.0,80,850,500,1.3,2.0,98.5,90,12.0,30,285,45,0.3,2.0,true,true,true,0.15,2.0,24,24,0.04,0.5,true
NGS-RUN-2026-002,WES,NextSeq 2000,2x150,180,100,72.0,75,1350,800,1200,62.0,70,48.0,60,65.0,80,45,100,3.8,2.0,85.0,90,45.0,30,320,85,4.5,2.0,true,false,true,0.8,2.0,16,8,1.2,0.5,false

Input validation rules

FS — Functional Specification

Example output.json

{
  "utilityId": "ngsrunqcchecker",
  "utilityFolder": "NgsRunQcChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "RunID",
      "value": "NGS-RUN-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PanelType",
      "value": "Targeted_Panel",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "Platform",
      "value": "NovaSeq 6000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "ReadLength",
      "value": "2x150",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "TotalReads_Million",
      "value": "250",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "MinTotalReads_Million",
      "value": "100",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "PercentQ30",
      "value": "89.5",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MinQ30",
      "value": "75",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "ClusterDensity_K_mm2",
      "value": "950",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "MinClusterDensity",
      "value": "800",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "MaxClusterDensity",
      "value": "1200",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "PercentPF",
      "value": "88.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-012"
    }
  ],
  "criticalFindings": [],
  "warnings": [],
  "audit": {
    "inputHash": "sha256:<calculated at runtime>",
    "rulesVersion": "<utility executable version>",
    "documentation": "NgsRunQcChecker.documentation.html"
  }
}

Traceability matrix

IQ/OQ/PQ test scenarios

QA/QC and change control

• Do not rename columns without updating validator, documentation and test set.
• Retain input.csv, output.json, executable version and checksum.
• Before production use, perform IQ/OQ/PQ or equivalent CSV/CSA verification.
• Critical limits shall be verified against the approved specification, registration dossier and local SOPs.
• The utility provides structured QC decision support; final release decision remains with QA/QP and approved procedures.