TumorNormalWgsInputChecker

URS & FS — User Requirements and Functional Specification

This document describes the controlled interface and behaviour of TumorNormalWgsInputChecker for Tumor-Normal WGS Input Checker.

Domain limits and critical parameters

• Performs input material verification per CAP/CLIA §GEN.48800, ISO 15189 §7.3.3, FDA NGS somatic guidance and ICGC/TCGA standards: tumor DNA QC (yield ≥ required, DIN ≥2.5 or DV200 ≥30% for FFPE, A260/A280 1.7–2.1, A260/A230 ≥1.8, FFPE repair planned), normal DNA QC (yield ≥ required, DIN ≥7.0, purity ratios), tumor purity assessment (pathologist estimate ≥20%, macrodissection recommendation, necrosis estimation, bioinformatic estimate), identity verification (SNP fingerprint concordance ≥0.95, g
• ⚠️ Critical: Paired WGS is meaningless without identity verification; sex check is minimum mandatory level. Low tumor purity (<20%) requires increased depth or enrichment; otherwise FN rate unacceptable. Degraded normal (DIN <7) introduces systematic artifacts into germline filtering. FFPE artifacts (C>T) require UDG repair or bioinformatic filtering. Cross-contamination >2% makes subclonal variant calling unreliable. Different extraction protocols for T/N can create batch effects mimicking soma
• • CAP/ISO accreditation: Documentation of pre-analytical QC for somatic WGS.
• 2. Purity Thresholds: Establish assay-specific purity thresholds based on validation.
• 5. Coverage Planning: Calculate T:N ratio accounting for actual tumor purity.
• ⚠️ Note: This utility assesses INPUT MATERIAL SUITABILITY. It does not replace post-sequencing QC (SequencerRunQcChecker, SequencingDepthGateChecker) or bioinformatic somatic call validation. For IDENTITY_MISMATCH status, all work must be immediately halted pending investigation. For TUMOR_CONCERN status, the decision to proceed is made by the laboratory director with documented limitations.

URS — User Requirements Specification

input.csv contract

PatientID,TumorSampleID,NormalSampleID,PrimaryTumorType,TumorSourceType,NormalSourceType,TumorDNA_Concentration_ng_uL,TumorDNA_TotalYield_ng,MinTumorDNA_Yield_ng,TumorDNA_DIN_Score,MinTumorDNA_DIN,TumorDNA_DV200_Percent,MinTumorDNA_DV200_Percent,TumorDNA_A260_A280,TumorDNA_A260_A230,TumorDNA_QC_Passed,NormalDNA_Concentration_ng_uL,NormalDNA_TotalYield_ng,MinNormalDNA_Yield_ng,NormalDNA_DIN_Score,MinNormalDNA_DIN,NormalDNA_A260_A280,NormalDNA_A260_A230,NormalDNA_QC_Passed,PathologistEstimated_Purity_Percent,MinPathologistPurity_Percent,BioinformaticPurity_Estimate_Percent,MinBioinformaticPurity_Percent,PurityAssessment_Available,Macrodissection_Performed,NecrosisEstimate_Percent,SNP_Fingerprint_Performed,SNP_Concordance_Score,MinSNP_Concordance,GeneticSex_Tumor,GeneticSex_Normal,SexMatch_Confirmed,IdentityVerification_Passed,CrossContamination_Estimate_Percent,MaxCrossContamination_Percent,ContaminationCheck_Passed,LibraryPrepKit,RequiredInputDNA_ng,TumorInput_Sufficient,NormalInput_Sufficient,FFPE_Repair_Planned,ExtractionMethod,SameExtractionProtocol,TumorStorage_Condition,NormalStorage_Condition,TumorFreezeThawCycles,NormalFreezeThawCycles,MaxFreezeThawCycles,StorageConditions_Appropriate,TargetTumorCoverage_X,TargetNormalCoverage_X,PlannedTumorNormal_Ratio,MinAcceptable_TNRatio,MaxAcceptable_TNRatio
PAT-LUNG-042,T-LUNG-042-FFPE,N-LUNG-042-Blood,NSCLC,FFPE,Blood_Buffy_Coat,45.0,2250,1000,3.2,2.5,65,30,1.85,2.1,true,85.0,4250,1000,8.5,7.0,1.90,2.3,true,65,20,58,20,true,Yes,5,true,0.998,0.95,XY,XY,true,true,0.3,2.0,true,TruSeq_DNA_PCR_Free,1000,true,true,true,QIAamp_FFPE,false,RT_Block,-80C,0,1,3,true,90,30,3.0,2.0,5.0
PAT-CRC-055,T-CRC-055-FFPE,N-CRC-055-Blood,CRC,FFPE,Blood_Buffy_Coat,12.0,600,1000,1.8,2.5,22,30,1.65,1.2,false,75.0,3750,1000,8.2,7.0,1.88,2.2,true,15,20,0,20,true,No,30,true,0.72,0.95,XX,XY,false,false,5.5,2.0,false,TruSeq_DNA_PCR_Free,1000,false,true,true,QIAamp_FFPE,false,RT_Block,-80C,4,1,3,false,90,30,3.0,2.0,5.0

Input validation rules

FS — Functional Specification

Example output.json

{
  "utilityId": "tumornormalwgsinputchecker",
  "utilityFolder": "TumorNormalWgsInputChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "PatientID",
      "value": "PAT-LUNG-042",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "TumorSampleID",
      "value": "T-LUNG-042-FFPE",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "NormalSampleID",
      "value": "N-LUNG-042-Blood",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "PrimaryTumorType",
      "value": "NSCLC",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "TumorSourceType",
      "value": "FFPE",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "NormalSourceType",
      "value": "Blood_Buffy_Coat",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "TumorDNA_Concentration_ng_uL",
      "value": "45.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "TumorDNA_TotalYield_ng",
      "value": "2250",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "MinTumorDNA_Yield_ng",
      "value": "1000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "TumorDNA_DIN_Score",
      "value": "3.2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "MinTumorDNA_DIN",
      "value": "2.5",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "TumorDNA_DV200_Percent",
      "value": "65",
      "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": "TumorNormalWgsInputChecker.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.