SequencingDepthGateChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты SequencingDepthGateChecker для сценария Sequencing Depth Gate Checker.

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

• • Mean Target Depth ≥ Required: Средняя глубина по целевым регионам.
• • Percent Bases Above Min Depth ≥ 95%: Доля баз с достаточным покрытием.
• • Min Depth: Абсолютный минимум; должен быть >0 для всех критических регионов.
• • Fold-80 Base Penalty ≤ 2.0×: Во сколько раз нужно увеличить секвенирование для покрытия 80% баз на целевой глубине.
• • Uniformity ≥ 80%: Доля баз с глубиной ≥ 0.2× средней.
• • Depth Floor (% at 10% mean): Доля баз с глубиной ≥ 10% от средней. Индикатор «хвоста» распределения.
• КРИТИЧЕСКИЕ РЕГИОНЫ И ГОРЯЧИЕ ТОЧКИ:
• • Critical Regions at Min Depth = 100%: ВСЕ клинически значимые регионы должны быть покрыты.
• • Critical Hotspots at Min Depth = 100%: ВСЕ терапевтически значимые варианты должны быть детектируемы.
• • ⛔ Любой непокрытый критический регион = потенциальный ложноотрицательный результат.
• • Unique Molecular Depth ≥ Required: Глубина после дедупликации (для UMI-ассеев).
• • Mean Family Size ≥ 3.0: Минимальный размер консенсусного семейства.
• • ⚠ Для cfDNA/somatic: именно UMI depth определяет реальную чувствительность, не raw depth.
• • On-Target Rate ≥ 60%: Эффективность обогащения.
• • GC Bias Correlation ≤ 0.3: Отсутствие систематического недопокрытия GC-rich/poor регионов.
• • Duplicate Rate ≤ 30%: Высокая дупликация снижает эффективную глубину.
• ⚠️ ВАЖНО:
• • Для UMI-ассеев raw depth может быть 20 000×, но unique molecular depth только 500× — именно последнее определяет LOD.

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

Контракт input.csv

SampleID,PatientID,AssayName,AssayType,PanelName,MeanTargetDepth_X,MedianTargetDepth_X,MinTargetDepth_X,PercentBases_Above_MinDepth,RequiredMinDepth_X,RequiredMeanDepth_X,RequiredPercentAbove_MinDepth,Fold80_BasePenalty,MaxFold80_Allowed,Uniformity_Percent,MinUniformity_Percent,PercentBases_At10pctMean,MinPercentBases_At10pctMean,UMI_Assay,UniqueMolecularDepth_X,RequiredUniqueMolecularDepth_X,UMIDeduplication_Rate,MeanFamilySize,MinMeanFamilySize,TotalCriticalRegions,CriticalRegions_AtMinDepth,CriticalHotspots_Total,CriticalHotspots_AtMinDepth,UncoveredCriticalRegions,UncoveredHotspots,OnTargetRate_Percent,MinOnTargetRate_Percent,TotalReads_Million,OnTargetReads_Million,TargetLOD_VAF_Percent,GCBias_Correlation,MaxGCBias_Correlation,DuplicateRate_High,DuplicateRate_Percent,MaxDuplicateRate_Percent
DEP-2026-001,PAT-LUNG-042,OncoPanel_500,Somatic_Targeted,NSCLC_CGP,850,820,180,98.5,100,500,95,1.4,2.0,92.0,80,97.5,90,true,3200,1000,0.45,4.2,3.0,150,150,45,45,,,85.0,60,25,21,0.5,0.08,0.3,false,12.0,30
DEP-2026-002,PAT-CRC-055,CRC_Panel,Hybrid_Capture,CRC_200,320,180,15,72.0,100,500,95,3.8,2.0,62.0,80,75.0,90,false,0,0,0,0,0,80,68,25,22,APC_exon15;SMAD4_exon2;TGFBR2_exon3,KRAS_G13D;BRAF_V600E,55.0,60,12,7,1.0,0.45,0.3,true,42.0,30
DEP-2026-003,PAT-BRCA-061,MRD_Panel,cfDNA_Panel,Breast_MRD,18000,15000,2500,94.0,5000,20000,95,1.8,2.0,85.0,80,92.0,90,true,1800,2000,0.72,8.5,3.0,60,58,20,20,ESR1_Y537S_region,,78.0,60,80,62,0.01,0.12,0.3,false,25.0,30

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

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

Пример output.json

{
  "utilityId": "sequencingdepthgatechecker",
  "utilityFolder": "SequencingDepthGateChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "DEP-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PatientID",
      "value": "PAT-LUNG-042",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "AssayName",
      "value": "OncoPanel_500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "AssayType",
      "value": "Somatic_Targeted",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "PanelName",
      "value": "NSCLC_CGP",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "MeanTargetDepth_X",
      "value": "850",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "MedianTargetDepth_X",
      "value": "820",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MinTargetDepth_X",
      "value": "180",
      "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": "RequiredMinDepth_X",
      "value": "100",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "RequiredMeanDepth_X",
      "value": "500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "RequiredPercentAbove_MinDepth",
      "value": "95",
      "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": "SequencingDepthGateChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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