TumorInformedPanelQcChecker

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

Документ описывает контролируемый интерфейс и поведение утилиты TumorInformedPanelQcChecker для сценария Tumor-Informed Panel QC Checker.

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

• • Total Variants ≥ Minimum: Достаточное число мишеней для целевой чувствительности.
• • Clonal Fraction ≥ 50%: Приоритет клональных вариантов (VAF >10% в первичной опухоли).
• • Primer Design Success Rate ≥ 95%: Эффективность дизайна.
• • Max Off-Target Alignment Score ≤ Threshold: Количественная мера специфичности.
• • Min Depth Per Variant ≥ Required: Каждая мишень должна быть покрыта.
• • Uniformity Across Variants ≥ 70%: Равномерность между мишенями.
• • Amplicon Balance CV ≤ 30%: Для ампликонных панелей.
• • Theoretical LOD ≤ Target LOD: Расчёт на основе числа мишеней и глубины.
• • Effective Independent Loci ≥ Minimum: Учёт сцепления/LD между вариантами.
• ⚠️ ВАЖНО:
• • CHIP-варианты составляют до 30% FP в cfDNA у пациентов >60 лет.
• • Клональная фракция <50% означает, что панель отслеживает минорные клоны; доминантный клон может быть упущен.
• • Теоретический LOD — нижняя граница; реальная чувствительность определяется эмпирически.

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

Контракт input.csv

PatientID,PanelID,PrimaryTumorType,TumorSequencingID,MatchedNormalID,AssayPlatform,TotalVariants_Selected,MinVariants_Required,ClonalVariants_Count,SubclonalVariants_Count,ClonalFraction_InPanel,MinClonalFraction,DriverMutations_Included,PassengerMutations_Included,GermlineVariants_Excluded,CHIP_Variants_Excluded,LowConfidenceVariants_Excluded,VariantsInProblematicRegions_Excluded,VariantsRemoved_ByFilters,FilterFailure_Reasons,FailedPrimerDesign_Count,TotalPrimers_Designed,PrimerDesignSuccess_Rate,CrossReactivity_Check_Passed,OffTarget_Analysis_Completed,OffTarget_Sites_Identified,MaxOffTarget_AlignmentScore,MaxAllowed_OffTargetScore,MeanDepth_PerVariant_X,MinDepth_PerVariant_X,RequiredMinDepth_PerVariant_X,VariantsBelowMinDepth,Uniformity_AcrossVariants_Percent,MinUniformity_Percent,AmpliconBalance_CV_Percent,MaxAmpliconBalance_CV_Percent,TheoreticalLOD_VAF_Percent,TargetLOD_VAF_Percent,CurrentDesign_SupportsTargetLOD,EffectiveIndependentLoci,MinEffectiveLoci_ForTargetLOD,PositiveControl_Pass,NegativeControl_Pass,NoTemplateControl_Pass,SyntheticReference_Pass,TumorNormalPair_Verified,SomaticCalling_Pipeline_Validated,PanelDesign_Software_Version_Locked,DesignSoftware_Version,ManufacturingLot_Tracked,ManufacturingLot_Number
PAT-LUNG-042,TI-PNL-042-v1,NSCLC,WES-LUNG-042-T,WES-LUNG-042-N,Bespoke_Amplicon,32,16,26,6,0.81,0.5,3,29,true,true,true,true,45,,1,33,0.97,true,true,0,0.15,0.8,25000,8500,5000,0,88.0,70,18.5,30,0.005,0.01,true,28,10,true,true,true,true,true,true,true,v3.2.1,true,MFG-2026-0451
PAT-CRC-055,TI-PNL-055-v1,CRC,WES-CRC-055-T,WES-CRC-055-N,Bespoke_Amplicon,12,16,4,8,0.33,0.5,2,10,true,false,true,true,68,CHIP_not_filtered;low_tumor_purity,5,17,0.71,false,true,3,0.92,0.8,12000,2800,5000,3,55.0,70,42.0,30,0.035,0.01,false,7,10,true,true,true,false,true,true,true,v3.2.1,true,MFG-2026-0467

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

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

Пример output.json

{
  "utilityId": "tumorinformedpanelqcchecker",
  "utilityFolder": "TumorInformedPanelQcChecker",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "PatientID",
      "value": "PAT-LUNG-042",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PanelID",
      "value": "TI-PNL-042-v1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "PrimaryTumorType",
      "value": "NSCLC",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "TumorSequencingID",
      "value": "WES-LUNG-042-T",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "MatchedNormalID",
      "value": "WES-LUNG-042-N",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "AssayPlatform",
      "value": "Bespoke_Amplicon",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "TotalVariants_Selected",
      "value": "32",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "MinVariants_Required",
      "value": "16",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "ClonalVariants_Count",
      "value": "26",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "SubclonalVariants_Count",
      "value": "6",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "ClonalFraction_InPanel",
      "value": "0.81",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "MinClonalFraction",
      "value": "0.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": "TumorInformedPanelQcChecker.documentation.html"
  }
}

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

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

QA/QC и change control

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