ImmuneRepertoireMrdQcChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты ImmuneRepertoireMrdQcChecker для сценария Immune Repertoire MRD QC Checker.

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

• • Background Noise: Частота шума в негативных контролях — определяет предел обнаружения.
• ⚠️ ВАЖНО:
• • MRD-позитивный вызов на <10 ридах = вероятный ЛОЖНОПОЛОЖИТЕЛЬНЫЙ результат.
• • Высокий фоновый шум (>10⁻⁵) делает невозможным надежное определение MRD на уровне 10⁻⁶.
• ⚠️ КРИТИЧЕСКИ ВАЖНО:
• • Total Reads ≥ 1M: Базовый порог для MRD на уровне 10⁻⁵.
• • Unique Molecules ≥ 100K: Определяет реальную чувствительность после дедупликации.
• • Background Noise ≤ 10⁻⁵: Превышение делает MRD-вызовы ненадежными.
• • Sensitivity Achieved ≤ Required: ОБЯЗАТЕЛЬНО для MRD-негативных заключений.
• • MRD Clone Reads ≥ 10: Ниже этого порога позитивный вызов недостоверен.
• Критические параметры:
• • Total Reads: ≥ 1,000,000
• • Unique Molecules: ≥ 100,000
• • UMI Dedup Rate: ≤ 80%
• • Background Noise: ≤ 1×10⁻⁵
• • Replicate Correlation: ≥ 0.90
• • Sensitivity Achieved: ≤ Required
• • MRD Clone Reads: ≥ 10 (if positive)

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

Контракт input.csv

SampleID,PatientID,ReceptorType,Timepoint,TotalReads,MinTotalReads,UniqueMolecules_UMI,MinUniqueMolecules,UMI_Deduplication_Rate,MaxUMI_DedupRate,BackgroundNoise_Frequency,MaxBackgroundNoise,ClonotypeCount_PostDedup,ReplicateCorrelation_R,MinReplicateCorrelation,ControlClonotype_Detected,Sensitivity_Achieved,RequiredSensitivity,MRD_Positive,MRD_CloneFrequency,MRD_CloneReads,MinMRD_CloneReads
MRD-2026-001,ALL-PAT-001,IGH,Post-induction,5200000,1000000,480000,100000,0.65,0.80,2E-6,1E-5,35000,0.96,0.90,true,5E-6,1E-5,false,0,0,10
MRD-2026-002,ALL-PAT-002,TRB,Follow-up,350000,1000000,42000,100000,0.88,0.80,5E-5,1E-5,8500,0.72,0.90,false,2E-4,1E-5,true,3E-5,5,10
MRD-2026-003,MM-PAT-003,IGK,Post-ASCT,2800000,1000000,250000,100000,0.70,0.80,8E-6,1E-5,28000,0.93,0.90,false,8E-6,1E-5,false,0,0,10

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

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

Пример output.json

{
  "utilityId": "immunerepertoiremrdqcchecker",
  "utilityFolder": "ImmuneRepertoireMrdQcChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "MRD-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PatientID",
      "value": "ALL-PAT-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "ReceptorType",
      "value": "IGH",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "Timepoint",
      "value": "Post-induction",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "TotalReads",
      "value": "5200000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "MinTotalReads",
      "value": "1000000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "UniqueMolecules_UMI",
      "value": "480000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MinUniqueMolecules",
      "value": "100000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "UMI_Deduplication_Rate",
      "value": "0.65",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "MaxUMI_DedupRate",
      "value": "0.80",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "BackgroundNoise_Frequency",
      "value": "2E-6",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "MaxBackgroundNoise",
      "value": "1E-5",
      "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": "ImmuneRepertoireMrdQcChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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