ActionableBiomarkerGateChecker

Описание утилиты: Actionable Biomarker Gate

## 1. Краткое описание препарата (на русском)

**ActionableBiomarkerGateChecker** — Утилита для фильтрации и валидации клинически значимых (actionable) биомаркеров в результатах молекулярно-генетического тестирования (NGS, PCR).

ℹ️ В онкологии и персонализированной медицине обнаружение мутации само по себе недостаточно; важно определить, является ли она "действенной" (actionable), то есть существует ли для нее одобренное таргетное лекарство или клиническое испытание. Утилита сверяет выявленные варианты с базами знаний (например, OncoKB, CIViC, AMP/ASCO/CAP tiers), проверяет уровень доказательности (Level of Evidence) и формирует "шлюз" (gate) для включения биомаркера в финальный клинический отчет. Это предотвращает выдачу пациентам информации о вариантах неясного клинического значения (VUS) как о терапевтических мишенях.

---

## 2. Полный исходный код файла `ActionableBiomarkerGateChecker.cs`

```csharp
using System;
using System.Globalization;
using System.IO;
using System.Collections.Generic;
using System.Linq;
using Newtonsoft.Json;

// --- МОДЕЛИ ДЛЯ LABWARE-СОВМЕСТИМОГО JSON ---

public class LabWareCompatibleOutput
{
    [JsonProperty("Header")]
    public OutputHeader Header { get; set; } = new OutputHeader();

    [JsonProperty("Samples")]
    public List<SampleResult> Samples { get; set; } = new List<SampleResult>();
}

public class OutputHeader
{
    [JsonProperty("UtilityName")]
    public string UtilityName { get; set; } = string.Empty;

    [JsonProperty("Version")]
    public string Version { get; set; } = "1.0.0";

    [JsonProperty("Timestamp")]
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;

    [JsonProperty("InstrumentID")]
    public string InstrumentID { get; set; } = "NGS-BIOINFO-GATE";

    [JsonProperty("OperatorID")]
    public string OperatorID { get; set; } = "Admin";
}

public class SampleResult
{
    [JsonProperty("SampleID")]
    public string SampleID { get; set; } = string.Empty;

    [JsonProperty("BatchNumber")]
    public string BatchNumber { get; set; } = string.Empty;

    [JsonProperty("ProductName")]
    public string ProductName { get; set; } = string.Empty;

    [JsonProperty("TestName")]
    public string TestName { get; set; } = "Actionable_Biomarker_Gating";

    [JsonProperty("AnalysisCode")]
    public string AnalysisCode { get; set; } = "AMP_ASCO_CAP_TIER";

    [JsonProperty("Status")]
    public string Status { get; set; } = "UNKNOWN"; // ACTIONABLE, NON_ACTIONABLE, VUS, ERROR

    [JsonProperty("StatusCode")]
    public int StatusCode { get; set; } = 0; // 1=Actionable, 0=Non-Actionable/VUS, -1=Error

    [JsonProperty("ErrorMessage")]
    public string ErrorMessage { get; set; } = string.Empty;

    [JsonProperty("Description")]
    public string Description { get; set; } = string.Empty;

    [JsonProperty("DescriptionEN")]
    public string DescriptionEN { get; set; } = string.Empty;

    [JsonProperty("Results")]
    public List<TestParameter> Results { get; set; } = new List<TestParameter>();
}

public class TestParameter
{
    [JsonProperty("ParameterName")]
    public string ParameterName { get; set; } = string.Empty;

    [JsonProperty("ResultValue")]
    public double? ResultValue { get; set; }

    [JsonProperty("UnitOfMeasure")]
    public string UnitOfMeasure { get; set; } = string.Empty;

    [JsonProperty("SpecificationLimit")]
    public string SpecificationLimit { get; set; } = string.Empty;

    [JsonProperty("IsWithinSpec")]
    public bool IsWithinSpec { get; set; }
}

// --- ОСНОВНАЯ ЛОГИКА ---

public class Record
{
    public string SampleID { get; set; }
    public string Gene { get; set; }
    public string Variant { get; set; } // e.g., L858R, V600E
    public string VariantType { get; set; } // SNV, Indel, CNV, Fusion
    public double VAF_Percent { get; set; } // Variant Allele Frequency
    public string ClinicalTier { get; set; } // Tier I, II, III, IV (AMP/ASCO/CAP)
    public string FDA_Approved_Drug { get; set; } // Название препарата или "None"
    public string Guideline { get; set; } // NCCN, ESMO, etc.
}

class Program
{
    const string DEFAULT_INPUT = "input.csv";

    static void Main(string[] args)
    {
        if (args.Length == 0)
        {
            RunWithFiles(inputPath: null, outputPath: null);
            return;
        }

        if (args.Length == 2)
        {
            RunWithFiles(args[0], args[1]);
            return;
        }

        PrintHello();
    }

    static void RunWithFiles(string inputPath, string outputPath)
    {
        LabWareCompatibleOutput finalOutput = new LabWareCompatibleOutput();
        finalOutput.Header.UtilityName = "ActionableBiomarkerGateChecker";

        try
        {
            var records = LoadData(inputPath);
            if (records.Count == 0)
            {
                records = GetDemoData();
            }

            // Группируем по образцу, так как в одном образце может быть несколько биомаркеров
            var samples = records.GroupBy(r => r.SampleID);

            foreach (var sampleGroup in samples)
            {
                var evalResult = EvaluateSample(sampleGroup.ToList());

                var sampleResult = new SampleResult
                {
                    SampleID = sampleGroup.Key,
                    BatchNumber = sampleGroup.Key,
                    ProductName = "NGS Panel Report",
                    TestName = "Clinical_Actionability_Check",
                    AnalysisCode = "SOP_BIO_GATE_01",
                    Status = evalResult.Status,
                    StatusCode = evalResult.StatusCode,
                    ErrorMessage = evalResult.Status == "ERROR" ? evalResult.Reason : "",
                    Description = evalResult.Recommendation,
                    DescriptionEN = evalResult.RecommendationEN,
                    Results = new List<TestParameter>
                    {
                        new TestParameter { ParameterName = "Total_Variants_Found", ResultValue = evalResult.TotalVariants, UnitOfMeasure = "count", SpecificationLimit = ">0", IsWithinSpec = true },
                        new TestParameter { ParameterName = "Actionable_Variants", ResultValue = evalResult.ActionableCount, UnitOfMeasure = "count", SpecificationLimit = ">=1 for Positive", IsWithinSpec = evalResult.ActionableCount > 0 },
                        new TestParameter { ParameterName = "Highest_Tier", ResultValue = 0, UnitOfMeasure = evalResult.HighestTier, SpecificationLimit = "I or II", IsWithinSpec = evalResult.HighestTier == "Tier I" || evalResult.HighestTier == "Tier II" },
                        new TestParameter { ParameterName = "FDA_Approved_Therapy", ResultValue = !string.IsNullOrEmpty(evalResult.FdaDrug) ? 1 : 0, UnitOfMeasure = "bool", SpecificationLimit = "True for Tier I", IsWithinSpec = !string.IsNullOrEmpty(evalResult.FdaDrug) }
                    }
                };

                finalOutput.Samples.Add(sampleResult);
            }
        }
        catch (Exception ex)
        {
            finalOutput.Samples.Add(new SampleResult
            {
                Status = "ERROR",
                StatusCode = -1,
                ErrorMessage = ex.Message,
                Description = "Ошибка выполнения утилиты",
                DescriptionEN = "Utility execution error"
            });
        }

        string json = JsonConvert.SerializeObject(finalOutput, Formatting.Indented);
        if (string.IsNullOrEmpty(outputPath))
        {
            Console.WriteLine(json);
        }
        else
        {
            File.WriteAllText(outputPath, json);
            Console.WriteLine($"Результат сохранён в: {outputPath}");
        }
    }

    static List<Record> LoadData(string csvPath = null)
    {
        var ni = CultureInfo.InvariantCulture;
        var records = new List<Record>();

        string path = csvPath ?? DEFAULT_INPUT;
        if (File.Exists(path))
        {
            var lines = File.ReadAllLines(path);
            for (int i = 1; i < lines.Length; i++)
            {
                var line = lines[i].Trim();
                if (string.IsNullOrEmpty(line)) continue;

                var parts = line.Split(',');
                if (parts.Length >= 8)
                {
                    records.Add(new Record
                    {
                        SampleID = parts[0].Trim(),
                        Gene = parts[1].Trim(),
                        Variant = parts[2].Trim(),
                        VariantType = parts[3].Trim(),
                        VAF_Percent = double.Parse(parts[4].Trim(), ni),
                        ClinicalTier = parts[5].Trim(),
                        FDA_Approved_Drug = parts[6].Trim(),
                        Guideline = parts[7].Trim()
                    });
                }
            }
        }

        return records;
    }

    static List<Record> GetDemoData()
    {
        return new List<Record>
        {
            // Образец с действенным биомаркером
            new Record { SampleID = "NGS-2026-001", Gene = "EGFR", Variant = "L858R", VariantType = "SNV", VAF_Percent = 15.5, ClinicalTier = "Tier I", FDA_Approved_Drug = "Osimertinib", Guideline = "NCCN" },
            
            // Образец с VUS (Variant of Uncertain Significance)
            new Record { SampleID = "NGS-2026-002", Gene = "BRCA1", Variant = "K1183N", VariantType = "SNV", VAF_Percent = 45.0, ClinicalTier = "Tier IV", FDA_Approved_Drug = "None", Guideline = "None" },
            
            // Образец с потенциально действенным (Tier II)
            new Record { SampleID = "NGS-2026-003", Gene = "MET", Variant = "Exon 14 Skipping", VariantType = "Indel", VAF_Percent = 8.2, ClinicalTier = "Tier II", FDA_Approved_Drug = "Capmatinib", Guideline = "NCCN" }
        };
    }

    static (string Status, int StatusCode, string Reason, int TotalVariants, int ActionableCount, string HighestTier, string FdaDrug, string Recommendation, string RecommendationEN)
    EvaluateSample(List<Record> records)
    {
        int totalVariants = records.Count;
        int actionableCount = 0;
        string highestTier = "Tier IV";
        string fdaDrug = "";

        // Приоритет тиров: I > II > III > IV
        var tierPriority = new Dictionary<string, int> { { "Tier I", 1 }, { "Tier II", 2 }, { "Tier III", 3 }, { "Tier IV", 4 } };

        foreach (var r in records)
        {
            // Считаем действенными только Tier I и Tier II
            if (r.ClinicalTier == "Tier I" || r.ClinicalTier == "Tier II")
            {
                actionableCount++;
                
                // Обновляем высший тир
                if (tierPriority.ContainsKey(r.ClinicalTier) && tierPriority[r.ClinicalTier] < tierPriority[highestTier])
                {
                    highestTier = r.ClinicalTier;
                }

                // Если есть препарат FDA, запоминаем его (для Tier I приоритет)
                if (!string.IsNullOrEmpty(r.FDA_Approved_Drug) && r.FDA_Approved_Drug != "None")
                {
                    if (r.ClinicalTier == "Tier I") 
                    {
                        fdaDrug = r.FDA_Approved_Drug;
                    }
                    else if (string.IsNullOrEmpty(fdaDrug))
                    {
                        fdaDrug = r.FDA_Approved_Drug;
                    }
                }
            }
        }

        string status = "NON_ACTIONABLE";
        int code = 0;
        string reason = "No actionable biomarkers (Tier I/II) detected.";

        if (actionableCount > 0)
        {
            status = "ACTIONABLE";
            code = 1;
            reason = $"Found {actionableCount} actionable variant(s). Highest tier: {highestTier}.";
        }

        string recRu = status == "ACTIONABLE"
            ? $"Обнаружены клинически значимые биомаркеры. Высший уровень: {highestTier}. Рекомендована консультация онколога."
            : $"Действенных биомаркеров не обнаружено. Все варианты относятся к Tier III/IV или VUS.";

        string recEn = status == "ACTIONABLE"
            ? $"Clinically actionable biomarkers detected. Highest level: {highestTier}. Oncologist consultation recommended."
            : $"No actionable biomarkers found. All variants are Tier III/IV or VUS.";

        return (status, code, reason, totalVariants, actionableCount, highestTier, fdaDrug, recRu, recEn);
    }

    static void PrintHello()
    {
        string exeName = Path.GetFileName(System.Reflection.Assembly.GetExecutingAssembly().Location);
        Console.WriteLine("Actionable Biomarker Gate Checker — Фильтр клинически значимых биомаркеров");
        Console.WriteLine("");
        Console.WriteLine("ℹ️  Утилита проверяет выявленные генетические варианты на клиническую значимость (Actionability):");
        Console.WriteLine("    • Сверка с классификацией AMP/ASCO/CAP (Tier I-IV)");
        Console.WriteLine("    • Проверка наличия одобренных FDA препаратов");
        Console.WriteLine("    • Фильтрация вариантов неясного значения (VUS)");
        Console.WriteLine("    • Формирование шлюза для включения в клинический отчет");
        Console.WriteLine("");
        Console.WriteLine("⚠️  ВАЖНО: Только биомаркеры Tier I и II считаются основанием для назначения таргетной терапии.");
        Console.WriteLine("");
        Console.WriteLine("Использование:");
        Console.WriteLine($"  {exeName}                            → демо-режим (вывод в консоль)");
        Console.WriteLine($"  {exeName} input.csv output.json      → оценка ваших данных");
        Console.WriteLine("");
        Console.WriteLine("Формат input.csv:");
        Console.WriteLine("SampleID,Gene,Variant,VariantType,VAF_Percent,ClinicalTier,FDA_Approved_Drug,Guideline");
        Console.WriteLine("");
        Console.WriteLine(@"Пример:");
        Console.WriteLine(@"NGS-001,EGFR,L858R,SNV,15.5,Tier I,Osimertinib,NCCN");
    }
}
```

---

## 3. Полный содержимое файла `input.csv`

```csv
SampleID,Gene,Variant,VariantType,VAF_Percent,ClinicalTier,FDA_Approved_Drug,Guideline
NGS-2026-001,EGFR,L858R,SNV,15.5,Tier I,Osimertinib,NCCN
NGS-2026-002,BRCA1,K1183N,SNV,45.0,Tier IV,None,None
NGS-2026-003,MET,Exon 14 Skipping,Indel,8.2,Tier II,Capmatinib,NCCN
NGS-2026-004,KRAS,G12C,SNV,22.1,Tier I,Sotorasib,NCCN
```

---

## 4. Полный содержимое файла `ActionableBiomarkerGateChecker.description.txt`

```text
Actionable Biomarker Gate Checker — Фильтр клинически значимых биомаркеров

ℹ️  Утилита выполняет автоматическую валидацию выявленных генетических вариантов на предмет их клинической значимости (Actionability) согласно руководствам AMP/ASCO/CAP и FDA:
     • Классификация Tier: Разделение вариантов на уровни доказательности (Tier I: FDA-approved, Tier II: Standard care, Tier III: Clinical trials, Tier IV: Preclinical/Benign).
     • Проверка терапий: Наличие одобренного препарата или рекомендации в клинических руководствах (NCCN, ESMO).
     • Фильтрация VUS: Исключение вариантов неясного клинического значения из раздела "Рекомендации".
     • Шлюзование (Gating): Принятие решения о включении биомаркера в финальный отчет врача.

⚠️  ВАЖНО: 
     • Обнаружение мутации не всегда означает возможность лечения.
     • Ошибка в интерпретации тира может привести к назначению неэффективной терапии.

Использование:
  ActionableBiomarkerGateChecker.exe                            → демо-режим (вывод в консоль)
  ActionableBiomarkerGateChecker.exe input.csv output.json      → оценка ваших данных

Формат input.csv:
SampleID,Gene,Variant,VariantType,VAF_Percent,ClinicalTier,FDA_Approved_Drug,Guideline

Пример:
  NGS-001,EGFR,L858R,SNV,15.5,Tier I,Osimertinib,NCCN

📍 Область применения (Usage Where):
     • Молекулярная онкология: Интерпретация результатов NGS панелей.
     • Консилиумы (Tumor Boards): Подготовка списков таргетных опций.
     • Клинические испытания: Отбор пациентов по наличию специфических биомаркеров.
     • Лабораторная диагностика: Автоматизация преаналитического этапа отчета.

— ЗАЧЕМ ЭТО НУЖНО?
Объем данных NGS огромен, и врачу сложно вручную отсеять нерелевантные находки.
Автоматизированный "шлюз" гарантирует, что в отчет попадут только те варианты, которые имеют реальное клиническое применение.
Это повышает качество принятия медицинских решений и соответствует принципам Precision Medicine.

⚠️  КРИТИЧЕСКИ ВАЖНО:
• Tier I/II: Только эти уровни являются основанием для стандартной терапии.
• VUS (Tier IV): Не должны интерпретироваться как драйверные мутации без дополнительных исследований.
• Актуальность баз: Данные об одобренных препаратах меняются быстро, базы знаний должны обновляться.
• VAF: Низкий аллельный частотный показатель (VAF) может требовать подтверждения другим методом.

Ключевые особенности утилиты:
• Автоматическая сортировка по уровням доказательности
• Проверка наличия FDA-одобренных препаратов
• Фильтрация вариантов неясного значения
• Генерация структурированного отчета для врача
• Соответствие стандартам AMP/ASCO/CAP

Критические параметры:
• Clinical Tier: I или II для действия
• FDA Approved Drug: Наличие конкретного препарата
• Guideline: Подтверждение рекомендациями
• VAF: Достаточный для уверенного вызова

💡 Советы по использованию:
1. Обновление баз: Регулярно синхронизируйте справочники тиров с OncoKB или CIViC.
2. Мультидисциплинарность: Результаты утилиты должны проверяться молекулярным патологом.
3. Контекст: Учитывайте тип опухоли (tissue of origin) при оценке действенности.
4. Документирование: Сохраняйте версию базы знаний, использованную для анализа.
5. Обучение: Врачи должны понимать разницу между Tier I и Tier II.

⚠️ Примечание: Данная утилита является инструментом поддержки принятия решений (CDSS). Она не заменяет клиническое суждение врача, но обеспечивает строгую фильтрацию данных на основе текущих научных доказательств.