ClassifierDriftMonitor

Classifier Drift Monitor

Liquid Biopsy жидкостная биопсия cfDNA ctDNA CTC exosomes NGS qPCR

Описание утилиты: Classifier Drift Monitor

Classifier Drift Monitor — Мониторинг дрейфа ML-классификаторов

ℹ️ Утилита выполняет непрерывный мониторинг стабильности ML-моделей в продакшене согласно требованиям FDA SaMD, EU AI Act и GMLP:
• PSI (Population Stability Index): Количественная оценка изменения распределения входных признаков и выходных предсказаний относительно базовой линии.
• KLD (Kullback-Leibler Divergence): Измерение информационного расстояния между текущим и эталонным распределениями.
• Mean Shift: Детекция систематического сдвига в предсказаниях модели.
• Градуированные алерты: Разделение на STABLE / WARNING / DRIFT_DETECTED для пропорционального реагирования.

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

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

Формат input.csv:
ModelName,ModelVersion,MonitoringWindow,PSI_Feature_Avg,PSI_Prediction,Max_PSI_Threshold,Warning_PSI_Threshold,KLD_Score,Max_KLD_Threshold,Prediction_Mean_Shift,Max_Mean_Shift,SampleSize_Current,Min_SampleSize,Baseline_Accuracy,Current_Proxy_Accuracy

Пример:
OncoClass,v3.2,W22,0.03,0.05,0.2,0.1,0.02,0.1,0.01,0.05,450,100,0.94,0.93

📍 Область применения (Usage Where):
• Клинические ML-системы: Непрерывный постмаркетинговый надзор за моделями.
• Регуляторный комплаенс: Документирование стабильности SaMD для FDA/EMA.
• MLOps: Автоматический триггер для пайплайна переобучения.
• Аудит AI: Подтверждение соответствия EU AI Act требованиям к high-risk AI systems.

— ЗАЧЕМ ЭТО НУЖНО?
ML-модели валидируются на исторических данных, но реальная популяция пациентов меняется.
Изменения в оборудовании, протоколах сбора данных или демографии вызывают дрейф.
Без систематического мониторинга деградация модели обнаруживается только после вреда пациентам.
Автоматизированный мониторинг обеспечивает проактивное управление жизненным циклом AI.

⚠️ КРИТИЧЕСКИ ВАЖНО:
• PSI Thresholds: 0.1 = warning, 0.2 = action (стандарт индустрии).
• Sample Size: Метрики дрейфа ненадежны при малых выборках (<100).
• Feature vs Prediction Drift: Дрейф признаков может предшествовать дрейфу предсказаний.
• Ground Truth: При отсутствии разметки используйте proxy-метрики для косвенной оценки.

Ключевые особенности утилиты:
• Мульти-метрическая оценка дрейфа (PSI + KLD + Mean Shift)
• Трехуровневая система алертов
• Поддержка мониторинга без ground truth
• Генерация отчетов для регуляторных органов
• Соответствие GMLP Principle 6 (Continuous Monitoring)

Критические параметры:
• PSI Features: < 0.1 (stable), 0.1-0.2 (warning), > 0.2 (drift)
• PSI Predictions: < 0.2
• KLD Score: < Threshold
• Mean Shift: Within tolerance
• Sample Size: ≥ Minimum

💡 Советы по использованию:
1. Базовая линия: Используйте валидационную выборку как эталон, а не тренировочную.
2. Окно мониторинга: Выбирайте размер окна балансированно (не слишком мало для шума, не слишком велико для задержки).
3. Послойный анализ: Анализируйте дрейф отдельно по подгруппам (возраст, пол, тип образца).
4. Автоматизация: Интегрируйте с CI/CD для автоматического запуска переобучения.
5. Документирование: Ведите журнал всех алертов и принятых действий.

⚠️ Примечание: Данная утилита является инструментом постмаркетингового надзора за ML-моделями. Она не заменяет периодическую полную ревалидацию, но обеспечивает своевременное обнаружение необходимости такой ревалидации.

input.csv

ModelName,ModelVersion,MonitoringWindow,PSI_Feature_Avg,PSI_Prediction,Max_PSI_Threshold,Warning_PSI_Threshold,KLD_Score,Max_KLD_Threshold,Prediction_Mean_Shift,Max_Mean_Shift,SampleSize_Current,Min_SampleSize,Baseline_Accuracy,Current_Proxy_Accuracy
OncoClassify_v3,v3.2.1,2026-W22,0.03,0.05,0.2,0.1,0.02,0.1,0.01,0.05,450,100,0.94,0.93
MCED_TissueOrigin_v2,v2.1.0,2026-W23,0.25,0.35,0.2,0.1,0.18,0.1,-0.12,0.05,380,100,0.89,0.76
VariantPathogenicity_v1,v1.4.2,2026-W23,0.08,0.06,0.2,0.1,0.04,0.1,0.02,0.05,520,100,0.91,0.90

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

Документ описывает контролируемый интерфейс и поведение утилиты ClassifierDriftMonitor для сценария Classifier Drift Monitor.

Предметные ограничения URS input.csv FS IQ/OQ/PQ

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

Ниже приведены ключевые фрагменты исходного описания. Перед продуктивным применением пределы должны быть сверены с утверждённой спецификацией, регистрационным досье и локальными SOP.

• PSI (Population Stability Index): Количественная оценка изменения распределения входных признаков и выходных предсказаний относительно базовой линии.
• KLD (Kullback-Leibler Divergence): Измерение информационного расстояния между текущим и эталонным распределениями.
⚠️ ВАЖНО:
⚠️ КРИТИЧЕСКИ ВАЖНО:
• Sample Size: Метрики дрейфа ненадежны при малых выборках (<100).
Критические параметры:
• PSI Features: < 0.1 (stable), 0.1-0.2 (warning), > 0.2 (drift)
• PSI Predictions: < 0.2
• KLD Score: < Threshold
• Sample Size: ≥ Minimum

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

ID	Требование	Критичность	Критерий приемки
URS-001	Утилита должна принимать файл input.csv для Classifier Drift Monitor с заголовками, определёнными в контракте данных.	High	Файл обрабатывается без ручного изменения заголовков.
URS-002	Утилита должна выполнять детерминированную оценку QC/ОКК без машинного обучения и без вероятностного принятия решения о соответствии.	High	При одинаковых входных данных, версии правил и конфигурации результат полностью воспроизводим.
URS-003	Утилита должна валидировать обязательные поля, типы данных, диапазоны, единицы измерения и предметную правдоподобность значений.	High	Ошибки схемы, преобразования и диапазона явно отражаются в результате.
URS-004	Утилита должна применять предметные пределы и правила из описания, утверждённой спецификации, регистрационного досье и локальных SOP.	High	Каждая проверка имеет результат PASS/WARNING/FAIL и понятное сообщение.
URS-005	Утилита должна формировать output.json с машинно-читаемыми результатами, исходными значениями, предупреждениями, отказами и критическими находками.	High	JSON пригоден для LIMS/ELN/MES-интеграции и QA/QC review.
URS-006	Утилита должна сохранять трассируемость между серией/образцом, входным файлом, применёнными правилами и итоговым статусом.	High	Выход содержит идентификаторы, список параметров и audit metadata.
URS-007	Документация должна поддерживать подготовку IQ/OQ/PQ, CSV/CSA и обсуждение с инспекторами или внутренним QA.	Medium	URS, FS, контракт input/output и тестовые сценарии поставляются вместе с утилитой.
URS-008	Утилита должна использоваться как decision-support инструмент QC, а не как замена утверждённым спецификациям и выпускному решению Qualified Person/QA.	Medium	В документации указан контроль change control и необходимость сверки пределов.

Контракт input.csv

#	Поле	Тип	Пример	Назначение
1	`ModelName`	string / controlled vocabulary	`OncoClassify_v3`	Контролируемый входной параметр для детерминированных QC-правил.
2	`ModelVersion`	string / controlled vocabulary	`v3.2.1`	Контролируемый входной параметр для детерминированных QC-правил.
3	`MonitoringWindow`	string / controlled vocabulary	`2026-W22`	Контролируемый входной параметр для детерминированных QC-правил.
4	`PSI_Feature_Avg`	decimal	`0.03`	Контролируемый входной параметр для детерминированных QC-правил.
5	`PSI_Prediction`	integer / decimal	`0.05`	Контролируемый входной параметр для детерминированных QC-правил.
6	`Max_PSI_Threshold`	decimal	`0.2`	Контролируемый входной параметр для детерминированных QC-правил.
7	`Warning_PSI_Threshold`	decimal	`0.1`	Контролируемый входной параметр для детерминированных QC-правил.
8	`KLD_Score`	decimal	`0.02`	Контролируемый входной параметр для детерминированных QC-правил.
9	`Max_KLD_Threshold`	decimal	`0.1`	Контролируемый входной параметр для детерминированных QC-правил.
10	`Prediction_Mean_Shift`	decimal	`0.01`	Контролируемый входной параметр для детерминированных QC-правил.
11	`Max_Mean_Shift`	decimal	`0.05`	Контролируемый входной параметр для детерминированных QC-правил.
12	`SampleSize_Current`	string / controlled vocabulary	`450`	Идентификатор образца или лабораторной пробы.
13	`Min_SampleSize`	string / controlled vocabulary	`100`	Идентификатор образца или лабораторной пробы.
14	`Baseline_Accuracy`	decimal	`0.94`	Контролируемый входной параметр для детерминированных QC-правил.
15	`Current_Proxy_Accuracy`	decimal	`0.93`	Контролируемый входной параметр для детерминированных QC-правил.

ModelName,ModelVersion,MonitoringWindow,PSI_Feature_Avg,PSI_Prediction,Max_PSI_Threshold,Warning_PSI_Threshold,KLD_Score,Max_KLD_Threshold,Prediction_Mean_Shift,Max_Mean_Shift,SampleSize_Current,Min_SampleSize,Baseline_Accuracy,Current_Proxy_Accuracy
OncoClassify_v3,v3.2.1,2026-W22,0.03,0.05,0.2,0.1,0.02,0.1,0.01,0.05,450,100,0.94,0.93
MCED_TissueOrigin_v2,v2.1.0,2026-W23,0.25,0.35,0.2,0.1,0.18,0.1,-0.12,0.05,380,100,0.89,0.76
VariantPathogenicity_v1,v1.4.2,2026-W23,0.08,0.06,0.2,0.1,0.04,0.1,0.02,0.05,520,100,0.91,0.90

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

ID	Поле	Правило	Критичность
VR-001	`ModelName`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	High
VR-002	`ModelVersion`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	High
VR-003	`MonitoringWindow`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	High
VR-004	`PSI_Feature_Avg`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-005	`PSI_Prediction`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-006	`Max_PSI_Threshold`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-007	`Warning_PSI_Threshold`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-008	`KLD_Score`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-009	`Max_KLD_Threshold`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-010	`Prediction_Mean_Shift`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-011	`Max_Mean_Shift`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-012	`SampleSize_Current`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-013	`Min_SampleSize`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-014	`Baseline_Accuracy`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium
VR-015	`Current_Proxy_Accuracy`	Поле должно соответствовать утверждённому справочнику/словарю или допустимой строковой форме.	Medium

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

ID	Функция	Реализация
FS-001	CLI execution	Поддержать режимы запуска: demo mode без аргументов и production mode input.csv output.json.
FS-002	CSV import	Прочитать input.csv в UTF-8/CSV-совместимом формате, проверить наличие заголовка и ожидаемых колонок.
FS-003	Schema validation	Проверить обязательные поля, количество колонок, неизвестные ключевые поля и пустые обязательные значения.
FS-004	Type conversion	Преобразовать числовые, флаговые и текстовые значения; некорректный формат фиксировать как ошибку строки.
FS-005	Domain rule engine	Применить правила для Classifier Drift Monitor, включая критические пределы из описания и утверждённой спецификации.
FS-006	Status aggregation	Сформировать итоговый статус: FAIL при критическом отказе, WARNING при некритическом отклонении, PASS при соответствии.
FS-007	JSON export	Записать output.json с детализацией проверок, исходными значениями, предупреждениями, отказами и critical findings.
FS-008	Audit support	Сохранять структуру результата пригодной для review, расследования отклонений и воспроизведения расчёта.
FS-009	Integration contract	Поддержать сценарий LIMS/ELN/MES → input.csv → utility → output.json → portal/admin review.
FS-010	Error handling	Возвращать явные сообщения для отсутствующего файла, пустого CSV, неверной схемы, ошибки записи output.json и некорректного формата.

Пример output.json

{
  "utilityId": "classifierdriftmonitor",
  "utilityFolder": "ClassifierDriftMonitor",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "ModelName",
      "value": "OncoClassify_v3",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "ModelVersion",
      "value": "v3.2.1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "MonitoringWindow",
      "value": "2026-W22",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "PSI_Feature_Avg",
      "value": "0.03",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "PSI_Prediction",
      "value": "0.05",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "Max_PSI_Threshold",
      "value": "0.2",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "Warning_PSI_Threshold",
      "value": "0.1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "KLD_Score",
      "value": "0.02",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "Max_KLD_Threshold",
      "value": "0.1",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "Prediction_Mean_Shift",
      "value": "0.01",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "Max_Mean_Shift",
      "value": "0.05",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "SampleSize_Current",
      "value": "450",
      "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": "ClassifierDriftMonitor.documentation.html"
  }
}

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

URS	FS	Тест	Подтверждение
URS-001	FS-001, FS-002	OQ-001	Проверить запуск и импорт валидного input.csv.
URS-002	FS-005, FS-006	OQ-004	Повторить один и тот же набор данных и сравнить output.json.
URS-003	FS-003, FS-004, FS-010	OQ-002, OQ-003	Проверить отсутствующие колонки и неверные типы.
URS-004	FS-005, FS-006	OQ-004, PQ-001	Проверить критические отклонения по реальным/граничным данным.
URS-005	FS-007, FS-009	OQ-005	Проверить JSON schema и пригодность для downstream-систем.
URS-006	FS-008	OQ-006	Проверить наличие идентификаторов и audit metadata.
URS-007	FS-008, FS-010	IQ-001, OQ-007	Проверить комплектность документации и control evidence.
URS-008	FS-005, FS-008	PQ-002	Проверить review workflow и запрет автоматической замены QA-решения.

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

ID	Сценарий	Ожидаемый результат
IQ-001	Проверить наличие executable, input.csv, документации и контрольной суммы.	Комплект поставки полон; версия зафиксирована.
OQ-001	Валидная строка из примера input.csv.	PASS или допустимый WARNING согласно правилам.
OQ-002	Удалить обязательную колонку из CSV.	Ошибка схемы или FAIL с указанием отсутствующей колонки.
OQ-003	Внести нечисловое значение в числовое поле.	Ошибка преобразования типа с указанием строки/поля.
OQ-004	Значение критического параметра вывести за предел.	FAIL и critical finding.
OQ-005	Проверить структуру output.json.	Все обязательные секции присутствуют, JSON валиден.
OQ-006	Проверить трассируемость серии/образца.	Идентификаторы входа и результатов совпадают.
PQ-001	Проверить 3–5 реальных партий/образцов пользователя.	Результат подтверждён QC/QA review.
PQ-002	Проверить workflow отклонения и ручного QA-решения.	Утилита поддерживает review, но не заменяет утверждённое решение.

QA/QC и change control

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

Входит в пакеты

Жидкостная биопсия

Пакет для QC и преданалитического контроля жидкостной биопсии: cfDNA/ctDNA, CTC, EV/exosomes, метилирование, NGS/qPCR/ddPCR, контроль образцов, контаминации, чувствительности и отчётности.

Открыть