TumorNormalWgsInputChecker

URS & FS — спецификация пользователя и функциональная спецификация

Документ описывает контролируемый интерфейс и поведение утилиты TumorNormalWgsInputChecker для сценария Tumor-Normal WGS Input Checker.

Предметные ограничения и критические параметры

• Tumor-Normal WGS Input Checker — Преаналитический QC парных образцов «опухоль–норма» для WGS
• ℹ️ Утилита выполняет проверку входного материала согласно CAP/CLIA §GEN.48800, ISO 15189 §7.3.3, FDA NGS somatic guidance и ICGC/TCGA:
• • Total Yield ≥ Required: Достаточность для библиотеки (обычно ≥1000 нг для PCR-free).
• • Integrity: DIN ≥ 2.5 (fresh frozen) или DV200 ≥ 30% (FFPE).
• • Purity Ratios: A260/A280 1.7–2.1, A260/A230 ≥ 1.8.
• • Total Yield ≥ Required: Обычно ≥1000 нг.
• • DIN ≥ 7.0: Высокая целостность критична для germline calling.
• • Purity Ratios: Те же требования, что и для опухоли.
• • ⚠ Деградированная норма = ложные соматические вызовы из-за артефактов germline filtering.
• • Pathologist Estimated Purity ≥ 20%: Минимум для надёжного соматического вызова.
• • Macrodissection: Рекомендуется при чистоте <40%.
• • Necrosis Estimate: >20% некроза снижает качество ДНК и эффективную чистоту.
• • Bioinformatic Purity: Дополнительная оценка, если доступна.
• • SNP Fingerprint Concordance ≥ 0.95: Подтверждение, что пара от одного пациента.
• • Cross-Contamination ≤ 2%: Оценка по allele balance или SNP-based методам.
• • Input Sufficient: Оба образца ≥ требуемого количества для kit.
• • Freeze-Thaw Cycles ≤ Max: Обычно ≤3 циклов.
• ⚠️ ВАЖНО:

URS — пользовательские требования

Контракт input.csv

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

Правила валидации входных данных

FS — функциональная спецификация

Пример 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"
  }
}

Матрица трассируемости

IQ/OQ/PQ тестовые сценарии

QA/QC и change control

• Не менять имена колонок без обновления валидатора, документации и тестового набора.
• Хранить input.csv, output.json, версию исполняемого файла и контрольную сумму.
• Перед продуктивным использованием провести IQ/OQ/PQ или эквивалентную CSV/CSA-проверку.
• Критические пределы должны быть сверены с утверждённой спецификацией, регистрационным досье и локальными SOP.
• Утилита предоставляет формализованный QC decision support, но окончательное решение выпуска остаётся за QA/QP и утверждёнными процедурами.