OncoBEAMRasCrcMutationChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты OncoBEAMRasCrcMutationChecker для сценария OncoBEAM RAS CRC Mutation Checker.

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

• КОМПАРТМЕНТАЛИЗАЦИЯ (КРИТИЧЕСКИЕ ПАРАМЕТРЫ BEAMING):
• • Total Droplets ≥ 50,000: Статистическая мощность для детекции редких аллелей.
• • Lambda ≤ 0.3: Среднее число молекул на каплю. Превышение нарушает предположение Пуассона.
• • Empty Droplets ≥ 70%: Подтверждение режима одиночных молекул.
• • Multiple Occupancy ≤ 5%: Доля капель с >1 молекулой. Высокий % = перегрузка.
• • Signal-to-Noise Ratio ≥ 10: Различимость мутантного сигнала от фона.
• • Fluorescence Separation Index ≥ 5.0: Расстояние между мутантным и WT кластерами.
• • Rain Fraction ≤ 2.0%: Доля промежуточных событий. Высокий rain = проблема зондов или амплификации.
• • Positive Control Recovery ≥ 80%: Подтверждение эффективности эмульсии и детекции.
• • Negative Control FP Rate ≤ 0.01%: Специфичность ассая.
• • Input DNA ≥ 5 ng: Достаточность материала для cfDNA/FFPE.
• • Amplifiable DNA Fraction ≥ 10%: Качество матрицы (особенно критично для FFPE).
• ⚠️ ВАЖНО:
• • Lambda > 0.3 = КОЛИЧЕСТВЕННЫЙ РЕЗУЛЬТАТ НЕВАЛИДЕН. Перегрузка эмульсии.
• • Единичные позитивные капли (<3) при VAF около LOD требуют подтверждения.
• • RAS-статус определяет выбор ПЕРВОЙ ЛИНИИ терапии в метастатическом CRC.
• 1. Lambda Optimization: Титруйте входную ДНК для достижения λ ≤ 0.3. Лучше меньше, чем больше.

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

Контракт input.csv

SampleID,PatientID,Gene,Exon,SpecificMutation,SampleType,TotalDroplets_Analyzed,MinTotalDroplets,PositiveDroplets_Count,WildTypeDroplets_Count,MutantFraction_Percent,AssayLOD_Percent,AssayLOQ_Percent,Lambda_Value,MaxLambda,EmptyDroplet_Percent,MinEmptyDroplet_Percent,MultipleOccupancy_Percent,MaxMultipleOccupancy_Percent,SignalToNoise_Ratio,MinSignalToNoise,FluorescenceSeparation_Index,MinFluorSeparation,RainEvents_Detected,RainFraction_Percent,MaxRainFraction_Percent,PositiveControl_Pass,PosControl_Recovery_Percent,MinPosControl_Recovery,NegativeControl_Pass,NegControl_FalsePositive_Rate,MaxNegControl_FP_Rate,NoTemplateControl_Pass,InputDNA_ng,MinInputDNA_ng,AmplifiableDNA_Fraction,MinAmplifiableDNA_Fraction,IsAntiEGFR_Eligible,ClinicalInterpretation
OB-CRC-2026-001,PAT-CRC-042,KRAS,Exon2,G12D,Plasma_cfDNA,125000,50000,375,124625,0.30,0.02,0.05,0.15,0.3,86.0,70,1.2,5,45.0,10,12.5,5.0,false,0.3,2.0,true,95.0,80,true,0.002,0.01,true,25.0,5,0.45,0.1,false,KRAS G12D mutant. Anti-EGFR therapy NOT recommended.
OB-CRC-2026-002,PAT-CRC-055,NRAS,Exon3,Q61H,FFPE_Tissue,62000,50000,18,61982,0.03,0.02,0.05,0.45,0.3,63.5,70,8.5,5,6.0,10,3.2,5.0,true,4.5,2.0,true,72.0,80,true,0.008,0.01,true,8.0,5,0.08,0.1,false,NRAS Q61H detected but QC concerns.
OB-CRC-2026-003,PAT-CRC-061,KRAS,Exon2,None,Plasma_cfDNA,150000,50000,2,149998,0.001,0.02,0.05,0.12,0.3,88.7,70,0.8,5,52.0,10,14.0,5.0,false,0.1,2.0,true,98.0,80,true,0.001,0.01,true,30.0,5,0.52,0.1,true,KRAS Exon2 WT. Anti-EGFR therapy may be considered.

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

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

Пример output.json

{
  "utilityId": "oncobeamrascrcmutationchecker",
  "utilityFolder": "OncoBEAMRasCrcMutationChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "OB-CRC-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PatientID",
      "value": "PAT-CRC-042",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "Gene",
      "value": "KRAS",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "Exon",
      "value": "Exon2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "SpecificMutation",
      "value": "G12D",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "SampleType",
      "value": "Plasma_cfDNA",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "TotalDroplets_Analyzed",
      "value": "125000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MinTotalDroplets",
      "value": "50000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "PositiveDroplets_Count",
      "value": "375",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "WildTypeDroplets_Count",
      "value": "124625",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "MutantFraction_Percent",
      "value": "0.30",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "AssayLOD_Percent",
      "value": "0.02",
      "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": "OncoBEAMRasCrcMutationChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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