PoissonQuantificationChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты PoissonQuantificationChecker для сценария Poisson Quantification Checker.

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

• LAMBDA (λ) — КРИТИЧЕСКИЙ ПАРАМЕТР:
• • λ < 0.1: Низкая точность, широкий CI, но результат может быть валиден.
• • λ > 0.8: Множественная занятость нарушает предположение Пуассона. Требуется разбавление.
• • χ² test p-value ≥ 0.05: Данные соответствуют распределению Пуассона.
• • p < 0.05: Модель отвергнута. Возможны агрегация, неоднородность компартментов или технические артефакты.
• • Factor > 1.5: Не-случайное распределение молекул. Агрегация ДНК, неравномерная генерация капель.
• • 95% CI Width ≤ 25%: Количественно надежный результат.
• • > 50%: Только качественный.
• • Ширина CI определяется числом положительных событий и λ.
• • Rain Fraction ≤ 2%: Промежуточные события не должны превышать порог.
• • Signal-to-Noise ≥ 10: Достаточная различимость сигнала.
• • Replicate CV ≤ 25%: Воспроизводимость между техническими репликами.
• • Below LOQ: «Обнаружено, ниже предела количественного определения». Только качественный.
• ⚠️ ВАЖНО:
• • λ > 0.8 = СИСТЕМАТИЧЕСКАЯ ОШИБКА квантификации. Результат занижен.
• • Для MRD/жидкой биопсии λ часто <0.1; это допустимо, но CI будет широким.
• 5. Reporting Convention: Для результатов ниже LOQ указывайте «<LOQ», не числовое значение.

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

Контракт input.csv

SampleID,AssayName,Technology,TotalPartitions,PositivePartitions,NegativePartitions,Lambda_Observed,Lambda_Target_Min,Lambda_Target_Max,Concentration_copies_uL,CI95_Lower_copies_uL,CI95_Upper_copies_uL,CI95_Width_Percent,MaxCI95_Width_Percent,ChiSquare_GoodnessOfFit_P,MinChiSquare_P,Overdispersion_Factor,MaxOverdispersion,RainFraction_Percent,MaxRainFraction_Percent,ClusterSeparation_Adequate,SignalToNoise_Ratio,MinSignalToNoise,NumReplicates,ReplicateCV_Percent,MaxReplicateCV_Percent,OutlierReplicate_Detected,PositiveControl_Pass,NegativeControl_Pass,NoTemplateControl_Pass,AssayLOD_copies_uL,AssayLOQ_copies_uL,BelowLOD,BelowLOQ
POIS-2026-001,KRAS_G12D_ddPCR,ddPCR_droplet,20000,4500,15500,0.256,0.1,0.8,128.0,124.2,131.9,6.0,25,0.42,0.05,1.05,1.5,0.8,2.0,true,35.0,10,4,8.5,25,false,true,true,true,0.5,2.0,false,false
POIS-2026-002,EGFR_T790M_BEAMing,BEAMing,50000,38000,12000,1.427,0.1,0.8,713.5,580.0,890.0,43.4,25,0.001,0.05,2.8,1.5,5.5,2.0,false,6.0,10,3,35.0,25,true,true,true,true,0.5,2.0,false,false
POIS-2026-003,BRAF_V600E_ddPCR,ddPCR_chip,770,5,765,0.0065,0.1,0.8,0.85,0.28,1.98,200.0,25,0.85,0.05,1.1,1.5,0.2,2.0,true,28.0,10,4,65.0,25,false,true,true,true,0.5,2.0,false,true

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

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

Пример output.json

{
  "utilityId": "poissonquantificationchecker",
  "utilityFolder": "PoissonQuantificationChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "POIS-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "AssayName",
      "value": "KRAS_G12D_ddPCR",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "Technology",
      "value": "ddPCR_droplet",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "TotalPartitions",
      "value": "20000",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "PositivePartitions",
      "value": "4500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "NegativePartitions",
      "value": "15500",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "Lambda_Observed",
      "value": "0.256",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "Lambda_Target_Min",
      "value": "0.1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "Lambda_Target_Max",
      "value": "0.8",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "Concentration_copies_uL",
      "value": "128.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "CI95_Lower_copies_uL",
      "value": "124.2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "CI95_Upper_copies_uL",
      "value": "131.9",
      "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": "PoissonQuantificationChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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