IndexHoppingContaminationChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты IndexHoppingContaminationChecker для сценария Index Hopping Contamination Checker.

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

• ⚠️ ВАЖНО:
• • Для жидкой биопсии (VAF <0.5%) даже 0.1% контаминации может вызвать ложноположительный результат.
• • Жидкая биопсия: Критический контроль для ultrasensitive assays (VAF <0.5%).
• ⚠️ КРИТИЧЕСКИ ВАЖНО:
• • Contamination vs Sensitivity: Если Estimated Contamination ≥ Required VAF → данные НЕПРИГОДНЫ.
• • Четырёхуровневая классификация (Clean / Low / High / Critical)
• Критические параметры:
• • Hopping Rate: ≤ 0.5% (typical threshold)
• • Estimated Contamination: ≤ Assay-specific limit
• • Contamination vs VAF Threshold: Contamination < Required Sensitivity
• 2. Балансируйте пул: Избегайте >10× разницы в молярности между образцами.

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

Контракт input.csv

RunID,SampleID,ExpectedIndex_I7,ExpectedIndex_I5,AssignedReads,HoppedReads_Total,HoppedReads_FromHighAbundance,HoppingRate_Percent,MaxAcceptableHoppingRate_Percent,EstimatedContamination_Percent,MaxAcceptableContamination_Percent,TopDonorSample,DonorContribution_Percent,DualIndexUsed,UniqueDualIndex,Platform,PatternedFlowCell,AssaySensitivity_Required_VAF
RUN-2026-045,LB-PAT-001,ATTACTCG,TATAGCCT,25000000,12500,8500,0.05,0.5,0.02,0.1,LB-PAT-003,68.0,true,true,NovaSeq 6000,true,0.1
RUN-2026-045,LB-PAT-002,TCCGGAGA,TCCGGAGA,18000000,540000,420000,3.0,0.5,1.8,0.1,LB-PAT-005,78.0,true,false,NovaSeq 6000,true,0.1
RUN-2026-045,WES-SAMPLE-010,CGCTCATT,,45000000,180000,95000,0.4,0.5,0.25,0.1,WES-SAMPLE-008,53.0,false,false,NovaSeq 6000,true,5.0

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

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

Пример output.json

{
  "utilityId": "indexhoppingcontaminationchecker",
  "utilityFolder": "IndexHoppingContaminationChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "RunID",
      "value": "RUN-2026-045",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "SampleID",
      "value": "LB-PAT-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "ExpectedIndex_I7",
      "value": "ATTACTCG",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "ExpectedIndex_I5",
      "value": "TATAGCCT",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "AssignedReads",
      "value": "25000000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "HoppedReads_Total",
      "value": "12500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "HoppedReads_FromHighAbundance",
      "value": "8500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "HoppingRate_Percent",
      "value": "0.05",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "MaxAcceptableHoppingRate_Percent",
      "value": "0.5",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "EstimatedContamination_Percent",
      "value": "0.02",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "MaxAcceptableContamination_Percent",
      "value": "0.1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "TopDonorSample",
      "value": "LB-PAT-003",
      "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": "IndexHoppingContaminationChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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