UltraSensitiveMrdRunChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты UltraSensitiveMrdRunChecker для сценария Ultra-Sensitive MRD Run Checker.

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

• ℹ️ Утилита выполняет проверку запусков MRD-ассеев (LOD ≤0.01% VAF) согласно CAP/CLIA §GEN.48800, FDA MRD assay guidance, ESMO MRD Guidelines и Blood Profiling Atlas:
• • Unique Molecular Depth ≥ Required: Глубина после дедупликации определяет реальный LOD.
• • Mean Family Size ≥ 3.0: Минимум для надёжного консенсуса; <3 = ошибка не устраняется.
• • Families ≥3 Members ≥ 70%: Доля UMI, способных сформировать консенсус.
• • Consensus Efficiency ≥ 60%: % UMI, дающих валидный консенсус. Низкая = потеря молекул.
• • UMI Collision Rate ≤ 2%: Коллизии объединяют разные молекулы; критично при высокой глубине.
• • Mean Positional Background ≤ 0.0005% VAF: Средняя частота ошибок на мониторимых позициях в NTC.
• • Max Single Position Background ≤ 0.001% VAF: Худшая позиция не должна превышать порог.
• • Error Suppression Factor ≥ 100×: Во сколько раз UMI-консенсус снижает raw error rate.
• • Recovery ≥ 70%: Достаточное восстановление сигнала.
• • Index Hopping ≤ 0.1%: При MRD-уровнях даже 0.1% hopping создаёт FP.
• • Cross-Sample Contamination ≤ 0.01%: Межобразцовая контаминация недопустима.
• LIMIT OF BLANK (LoB):
• • LoB ≤ 0.005% VAF: Верхняя граница шума из NTC.
• • Должен быть ≤ declared LOD ассая.
• • Если theoretical LOD > declared LOD = запуск не поддерживает заявленную чувствительность.
• ⚠️ ВАЖНО:
• • Ультрачувствительный MRD работает в зоне единичных молекул; каждая метрика критична.

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

Контракт input.csv

RunID,AssayName,Platform,PanelType,RunDate,TotalSamples,TotalReads_Million,UniqueUMIs_Million,UMIDeduplication_Rate,UniqueMolecularDepth_X,RequiredUniqueMolecularDepth_X,MeanFamilySize,MinMeanFamilySize,MedianFamilySize,PercentFamilies_SizeGE3,MinPercentFamilies_SizeGE3,UMICollisionRate_Percent,MaxUMICollisionRate_Percent,ConsensusEfficiency_Percent,MinConsensusEfficiency_Percent,PositionalBackground_Mean_VAF,MaxPositionalBackground_VAF,PositionalBackground_MaxSingle_VAF,MaxAllowed_SinglePosition_Background_VAF,PositionsAboveBackground_Threshold,TotalMonitoredPositions,ErrorSuppression_Factor,MinErrorSuppression_Factor,UltraLowPositive_Control_Passed,UltraLowPos_Recovery_Percent,MinUltraLowPos_Recovery_Percent,UltraLowPos_ObservedVAF,UltraLowPos_ExpectedVAF,NegativeControl_Clean,NTC_PositiveSignals_Detected,MaxNTC_PositiveSignals_Allowed,NoTemplateControl_Pass,IndexHopping_Rate_Percent,MaxIndexHopping_Rate_Percent,UDIndexes_Used,CrossSampleContamination_Estimate_Percent,MaxCrossSampleContamination_Percent,PercentQ30_Read1,PercentQ30_Read2,MinPercentQ30,OnTargetRate_Percent,MinOnTargetRate_Percent,AssayDeclared_LOD_VAF,LimitOfBlank_VAF,MaxAcceptable_LoB_VAF,ReagentKit_Lot,ReagentLot_Verified,Calibration_Current,PipelineVersion,PipelineVersion_Validated
MRD-2026-0142,Signatera_NSCLC_v3,UMI_NGS,Tumor_Informed,2026-06-08,24,120,8.5,0.82,12500,5000,5.8,3.0,5.0,85.0,70,0.8,2.0,92.0,60,0.00008,0.0005,0.00035,0.001,0,32,850,100,true,94.5,70,0.0095,0.01,true,0,0,true,0.02,0.1,true,0.003,0.01,91.5,88.2,75,82.0,60,0.01,0.0002,0.005,RK-2026-0451,true,true,v4.2.1,true
MRD-2026-0143,Guardant_Reveal,UMI_NGS,Tumor_Agnostic,2026-06-09,24,95,4.2,0.78,3800,5000,2.4,3.0,2.0,42.0,70,3.5,2.0,48.0,60,0.0012,0.0005,0.0045,0.001,5,50,35,100,false,52.0,70,0.0052,0.01,false,3,0,false,0.35,0.1,false,0.08,0.01,82.0,76.5,75,65.0,60,0.01,0.008,0.005,RK-2026-0467,true,true,v4.2.1,true

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

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

Пример output.json

{
  "utilityId": "ultrasensitivemrdrunchecker",
  "utilityFolder": "UltraSensitiveMrdRunChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "RunID",
      "value": "MRD-2026-0142",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "AssayName",
      "value": "Signatera_NSCLC_v3",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "Platform",
      "value": "UMI_NGS",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "PanelType",
      "value": "Tumor_Informed",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "RunDate",
      "value": "2026-06-08",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "TotalSamples",
      "value": "24",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "TotalReads_Million",
      "value": "120",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "UniqueUMIs_Million",
      "value": "8.5",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "UMIDeduplication_Rate",
      "value": "0.82",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "UniqueMolecularDepth_X",
      "value": "12500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "RequiredUniqueMolecularDepth_X",
      "value": "5000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "MeanFamilySize",
      "value": "5.8",
      "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": "UltraSensitiveMrdRunChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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