PanelCoverageQcChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты PanelCoverageQcChecker для сценария Panel Coverage QC Checker.

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

• • Percent Bases Above Min Depth ≥ 95%: Доля целевых баз с достаточной глубиной.
• • Minimum Depth: Абсолютный минимум не должен быть катастрофически низким (<50% от требуемого).
• • Uniformity ≥ 80%: Доля баз с глубиной ≥ 0.2× средней.
• • Fold-80 Base Penalty ≤ 2.0×: Во сколько раз нужно увеличить секвенирование для достижения 80% баз на целевой глубине.
• • Blind Spot Fraction ≤ 2%: Доля регионов ниже порога покрытия.
• КЛИНИЧЕСКИ КРИТИЧЕСКИЕ ПАРАМЕТРЫ:
• • Critical Regions Below Min Depth = 0: НИ ОДНОЙ слепой зоны в клинически значимых регионах.
• • GC Correlation |r| ≤ 0.3: Корреляция между GC-content и глубиной покрытия.
• • Off-Target Rate ≤ 20%: Специфичность обогащения.
• ⚠️ ВАЖНО:
• • Одна слепая зона в критическом гене (EGFR exon 19, BRCA1 exon 10) = INSUFFICIENT.
• • GC-bias >0.3 указывает на систематическую проблему обогащения или дизайна панели.
• • Fold-80 >2.0 означает, что >20% базы требуют непропорционального пересеквенирования.
• • Off-target >20% снижает эффективную глубину и увеличивает стоимость.
• 1. Per-Region BED: Используйте BED-файл с аннотацией критических регионов для автоматической проверки.
• 2. GC Stratification: Анализируйте покрытие стратифицированно по GC-content (bins: <30%, 30-40%, ..., >70%).
• ⚠️ Примечание: Утилита оценивает ТЕХНИЧЕСКОЕ ПОКРЫТИЕ панели. Она не заменяет проверку аналитической чувствительности (LoD) для конкретных вариантов в каждом регионе. Покрытие ≥100× необходимо, но не достаточно для гарантии LoD; требуется эмпирическая верификация.

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

Контракт input.csv

RunID,PanelName,PanelVersion,Platform,MeanTargetDepth_X,MedianTargetDepth_X,MinTargetDepth_X,RequiredMinDepth_X,PercentBases_Above_MinDepth,MinPercentBases_Above_MinDepth,Uniformity_Percent,MinUniformity_Percent,Fold80_BasePenalty,MaxFold80,TotalTargetRegions,RegionsBelowMinDepth,CriticalRegionsBelowMinDepth,TotalCriticalRegions,MaxAllowedBlindSpot_Fraction,GCCorrelation_Coefficient,MaxGCCorrelation,HighGC_Regions_BelowThreshold_Count,LowGC_Regions_BelowThreshold_Count,KnownProblematicRegions_Total,KnownProblematicRegions_Covered,UncoveredProblematicRegions,ClinicalGenes_Total,ClinicalGenes_FullyCovered,PartiallyCoveredGenes,OffTargetRate_Percent,MaxOffTargetRate_Percent,RepeatMasking_Applied,SegmentalDuplication_Flagged
COV-2026-001,OncoPanel_500,v4.2,NovaSeq,850,820,120,100,98.5,95,93.0,80,1.3,2.0,5200,78,0,450,0.02,0.12,0.3,15,8,25,25,,50,50,,8.5,20,true,true
COV-2026-002,HemePanel_300,v2.1,NextSeq,450,380,15,100,82.0,95,68.0,80,3.5,2.0,3100,558,12,280,0.02,0.55,0.3,185,92,18,10,FLT3_ITD;CEBPA_TAD;NPM1_exon12,40,35,FLT3;CEBPA;DNMT3A;TET2;ASXL1,22.0,20,false,false

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

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

Пример output.json

{
  "utilityId": "panelcoverageqcchecker",
  "utilityFolder": "PanelCoverageQcChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "RunID",
      "value": "COV-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PanelName",
      "value": "OncoPanel_500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "PanelVersion",
      "value": "v4.2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "Platform",
      "value": "NovaSeq",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "MeanTargetDepth_X",
      "value": "850",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "MedianTargetDepth_X",
      "value": "820",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "MinTargetDepth_X",
      "value": "120",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "RequiredMinDepth_X",
      "value": "100",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "PercentBases_Above_MinDepth",
      "value": "98.5",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "MinPercentBases_Above_MinDepth",
      "value": "95",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "Uniformity_Percent",
      "value": "93.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "MinUniformity_Percent",
      "value": "80",
      "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": "PanelCoverageQcChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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