FragmentomicsQcChecker

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

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

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

• • Short Fragment Ratio: Соотношение коротких (<150 bp) к длинным фрагментам — маркер опухолевой ДНК.
• • Library Complexity: Количество уникальных молекул — определяет статистическую мощность анализа.
• • Motif Coverage: Глубина покрытия для анализа end-motifs — требует ≥10× для надежной детекции.
• ⚠️ ВАЖНО:
• • Адаптерные димеры (>2%) загрязняют данные и снижают эффективную глубину.
• ⚠️ КРИТИЧЕСКИ ВАЖНО:
• • Nucleosomal Peak ≥3.0: Слабый пик = потеря нуклеосомного позиционирования.
• • Adapter Dimer ≤2%: Выше этого уровня требуется повторная очистка библиотеки.
• • Motif Coverage ≥10×: Ниже этого порога анализ end-motifs статистически ненадежен.
• Критические параметры:
• • Nucleosomal Peak Height: ≥ 3.0
• • Adapter Dimer: ≤ 2%
• • Unique Molecules: ≥ 5M
• • Motif Coverage: ≥ 10×

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

Контракт input.csv

SampleID,LibraryPrepMethod,MedianInsertSize_bp,ExpectedMedianInsert_bp,InsertSizeTolerance_bp,ShortFragmentRatio,MinShortFragmentRatio,MaxShortFragmentRatio,NucleosomalPeakHeight,MinNucleosomalPeakHeight,AdapterDimer_Percent,MaxAdapterDimer_Percent,UniqueMolecules_Million,MinUniqueMolecules_Million,MotifCoverage_X,MinMotifCoverage_X,BackgroundNoise_Score,MaxBackgroundNoise,OvertrimmingDetected
FRAG-2026-001,WGS,168,167,15,0.28,0.15,0.45,5.2,3.0,0.3,2.0,18.5,5.0,25.0,10.0,0.08,0.2,false
FRAG-2026-002,Targeted,142,167,15,0.62,0.15,0.45,1.8,3.0,8.5,2.0,2.1,5.0,4.0,10.0,0.35,0.2,true
FRAG-2026-003,WGS,170,167,15,0.32,0.15,0.45,4.8,3.0,0.5,2.0,15.2,5.0,22.0,10.0,0.12,0.2,false

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

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

Пример output.json

{
  "utilityId": "fragmentomicsqcchecker",
  "utilityFolder": "FragmentomicsQcChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "FRAG-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "LibraryPrepMethod",
      "value": "WGS",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "MedianInsertSize_bp",
      "value": "168",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "ExpectedMedianInsert_bp",
      "value": "167",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "InsertSizeTolerance_bp",
      "value": "15",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "ShortFragmentRatio",
      "value": "0.28",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "MinShortFragmentRatio",
      "value": "0.15",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MaxShortFragmentRatio",
      "value": "0.45",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "NucleosomalPeakHeight",
      "value": "5.2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "MinNucleosomalPeakHeight",
      "value": "3.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "AdapterDimer_Percent",
      "value": "0.3",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "MaxAdapterDimer_Percent",
      "value": "2.0",
      "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": "FragmentomicsQcChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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