NgsRunQcChecker

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

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

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

• • Total Reads ≥ Minimum: Достаточный выход данных для целевой глубины.
• • Q30 ≥ Threshold: Качество баз (порог зависит от платформы и типа панели).
• • Pass-Filter Rate ≥ 70%: Доля прочтений, прошедших фильтр качества Illumina.
• • On-Target Rate ≥ 60%: Эффективность захвата целевых регионов.
• • Uniformity ≥ 80%: Равномерность покрытия (% баз ≥ 0.2× средней глубины).
• • Mean Target Depth ≥ Minimum: Средняя глубина покрытия целевых регионов.
• • Fold-80 Base Penalty ≤ 2.0: Мера неравномерности (сколько нужно досеквенировать для 80% баз).
• • Alignment Rate ≥ 90%: Доля прочтений, успешно выровненных на референс.
• • Duplication Rate ≤ 30%: Уровень PCR/optical дупликатов (зависит от типа библиотеки).
• • Contamination Estimate ≤ 2%: Оценка межобразцовой контаминации.
• • Index Hopping Rate ≤ 0.5%: Перекрестное загрязнение через индексы.
• • PhiX Control: Подтверждение качества химии секвенирования (error rate ≤ 2%).
• • Sample Pass Rate ≥ 80%: Доля образцов в запуске, прошедших индивидуальные QC.
• ⚠️ ВАЖНО:
• • Contamination >2% делает соматические вызовы ненадежными.

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

Контракт input.csv

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

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

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

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

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

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

QA/QC и change control

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