🏥 SYNT_ISIC: GUI для синтетической генерации дерматологических изображений

SYNT_ISIC — графическое приложение (PyQt5) для генерации синтетических дерматологических изображений под таксономию ISIC (MEL, NV, BCC, AKIEC, BKL, DF, VASC) с использованием DDPM (UNet2D) и встроенными методами объяснимости:

Time-SHAP — атрибуция вклада по временным шагам денойзинга (доказана консистентность по аксиомам Шэпли);
Causal Validation (CSI) — проверка интерпретаций через контрафактуальные интервенции (noise, blur, shuffle, const).

Приложение объединяет генерацию, интерпретацию, каузальную валидацию и экспорт XAI-оверлеев в едином пайплайне.
⚠️ Проект предназначен исключительно для исследовательских целей и не является медицинским изделием.

🎯 Архитектура - ⚡ Быстрый старт - 📐 XAI методы - 🔬 Использование

🎯 Основные возможности

Данный репозиторий предоставляет самодостаточное графическое приложение для генерации синтетических дерматологических изображений с использованием диффузионных моделей и выполнения объяснимого анализа с интеграцией:

🏗️ Ключевые компоненты

Diffusion backbone: DDPM + UNet2D с attention-блоками.
Explainability: Time-SHAP (temporal Shapley attribution), поддержка Integrated Gradients и SHAP.
Causal robustness: интервенции (noise/blur/shuffle/const) и метрика causal shift (CSI) с p-values.
Fairness: генерация синтетики для тёмных фототипов кожи (≈8000 образцов).
GUI: предпросмотр, логи, мониторинг CPU/GPU.
Reproducibility: фиксируемые seeds, стабильные пути I/O, экспорт CSV и heatmap-оверлеев.

🏗️ Архитектура системы

🔄 Пайплайн генерации с XAI

Сид → UNet2D → DDPM Scheduler → Синтетическое изображение → XAI анализ → Визуализация

Структура проекта:

SYNT_ISIC/
├── core/                  # Базовая библиотека: конфигурация, генерация, кеширование
├── diffusion/             # Обучающий код (справочный, не требуется для GUI)
├── xai/                   # Интеграция методов объяснимости
├── download_models.py     # Загрузчик предобученных чекпоинтов
├── main.py                # Точка входа PyQt5 GUI
├── run_isicgui.bat        # Windows запускатель
└── requirements.txt       # Python зависимости

Математические основы

1. Диффузионная модель (DDPM)

Прямой марковский процесс (добавление шума). Для шага $t=1,\dots,T$

$$ q(x_t\mid x_{t-1})=\mathcal N\big(\sqrt{\alpha_t},x_{t-1},(1-\alpha_t)\mathbf I\big),\qquad \alpha_t=1-\beta_t,\ \beta_t\in(0,1). $$

Замкнутая форма для любого $t$.

$$ q(x_t\mid x_0)=\mathcal N\big(\sqrt{\bar\alpha_t},x_0,(1-\bar\alpha_t)\mathbf I\big),\quad \bar\alpha_t:=\prod_{s=1}^t\alpha_s, $$

эквивалентная репараметризация:

$$ x_t=\sqrt{\bar\alpha_t},x_0+\sqrt{1-\bar\alpha_t}\varepsilon,\qquad \varepsilon\sim\mathcal N(0,\mathbf I). $$

Обратный (генеративный) процесс.

$$ p_\theta(x_{t-1}\mid x_t)=\mathcal N\big(\mu_\theta(x_t,t),\Sigma_\theta(x_t,t)\big). $$

Постериор прямого процесса

$$ q(x_{t-1}\mid x_t,x_0)=\mathcal N\big(\tilde\mu_t(x_t,x_0),\tilde\beta_t\mathbf I\big), $$

где

$$ \tilde\beta_t=\frac{1-\bar\alpha_{t-1}}{1-\bar\alpha_t},\beta_t,\qquad \tilde\mu_t=\frac{\sqrt{\bar\alpha_{t-1}}\beta_t}{1-\bar\alpha_t},x_0 +\frac{\sqrt{\alpha_t}(1-\bar\alpha_{t-1})}{1-\bar\alpha_t},x_t . $$

Параметризация через предсказание шума.

$$ \mu_\theta(x_t,t)=\frac{1}{\sqrt{\alpha_t}} \left(x_t-\frac{\beta_t}{\sqrt{1-\bar\alpha_t}};\varepsilon_\theta(x_t,t)\right),\qquad \hat x_0=\frac{x_t-\sqrt{1-\bar\alpha_t},\varepsilon_\theta(x_t,t)}{\sqrt{\bar\alpha_t}}. $$

Обычно $\Sigma_\theta=\tilde\beta_t\mathbf I$ (либо обучаемая дисперсия).

Функция потерь (упрощённая ELBO).

$$ \mathcal L_{\mathrm{simple}} =\mathbb E_{t\sim\mathcal U{1..T},x_0,\varepsilon} \big|,\varepsilon-\varepsilon_\theta(\sqrt{\bar\alpha_t}x_0+\sqrt{1-\bar\alpha_t}\varepsilon,t),\big|_2^2 . $$

Примечание (оптимизация Adam). Обновление параметров

$$ \theta_{к+1}=\theta_k-lr\frac{\hat m_k}{\sqrt{\hat v_k}+\varepsilon}, $$

2. UNet и временное внедрение

Дискретное время кодируется синусоидальным вектором

$$ \gamma(t)=\big[\sin(\omega_0 t),\cos(\omega_0 t),\ldots,\sin(\omega_k t),\cos(\omega_k t),\ldots\big],\qquad \omega_k=10000^{-2k/d}, $$

который после MLP встраивается в блоки UNet через модульно-сдвиговую модуляцию (FiLM) поверх нормализации:

$$ h \leftarrow \mathrm{GN}(h)\cdot(1+s(t)) + b(t). $$

В непрерывных вариантах возможно кодирование через $\tau\propto\log\mathrm{SNR}(t)$.

3. Методы объяснимости (XAI)

Integrated Gradients (IG). Для $f:\mathbb R^n\to\mathbb R$, входа $x$ и базовой точки $x'$

$$ \mathrm{IG}_i(x;x')=(x_i-x'_i)\int_0^1 \frac{\partial f\big(x'+\alpha(x-x')\big)}{\partial x_i},d\alpha,\qquad \sum_i\mathrm{IG}_i=f(x)-f(x')\ \ (\text{полнота}). $$

Значения Шэпли (SHAP). Для множества признаков $N={1,\dots,n}$ и функции ценности $v:\mathcal P(N)\to\mathbb R$

$$ \phi_i=\sum_{S\subseteq N\setminus{i}} \frac{|S|!,(n-|S|-1)!}{n!},[,v(S\cup{i})-v(S),], $$

удовлетворяют аксиомам эффективности, симметрии, нулевого (фиктивного) игрока и аддитивности.

4. Time-SHAP для шагов денойзинга

Игроки. Временные шаги ${1,\dots,T}$.

Оценочный функционал. Фиксируем

$$ F(x)=\mathrm{logit}_{y^*}(x), $$

логит целевого класса $y^*$ (устойчив к калибровке вероятностей).

Функция ценности. Для коалиции шагов $S\subseteq{1..T}$

$$ v(S)=\mathbb E\Big[F\big(\mathrm{Dec}(x_T;S)\big)\Big], $$

где $\mathrm{Dec}(x_T;S)$ — денойзинг, применяющий стохастические переходы только на шагах из $S$; для $\bar S$ используется нейтральная операция (заморозка/скип).

Значение Шэпли шага $t$.

$$ \phi_t=\sum_{S\subseteq {1..T}\setminus{t}} \frac{|S|!,(T-|S|-1)!}{T!},[,v(S\cup{t})-v(S),]. $$

Непредвзятая оценка (пермутациями)

Несмещённая оценка значений Шэпли для шага t вычисляется как среднее по случайным пермутациям шагов:

φ̂_t = (1 / M) * Σ_{m=1..M} [ v(Pref_{π_m}(t) ∪ {t}) – v(Pref_{π_m}(t)) ]

где:

Pref_{π}(t) — множество шагов, стоящих до t в пермутации π,
v(·) — функция ценности (например, ожидаемое значение logits после частичного денойзинга),
мат. ожидание φ̂_t совпадает с истинным значением φ_t (оценка несмещённая).

Пиксельный уровень. $\phi_{t,i,j}$ — вклад шага $t$ в пиксель $(i,j)$; агрегированная карта важности $A_{i,j}=\sum_{t=1}^T w_t,\phi_{t,i,j}$ (например, $w_t\equiv T^{-1}$).

Теоретическая корректность. Для определённого выше $v$ значения ${\phi_t}$ удовлетворяют аксиомам эффективности $\big(\sum_t\phi_t=v({1..T})-v(\varnothing)\big)$, симметрии, нулевого (фиктивного) шага $\big(v(S\cup{t})=v(S)\Rightarrow \phi_t=0\big)$ и аддитивности.

Сложность и концентрация. Если маржинальный вклад ограничен диапазоном длины $R$, то по Хёффдингу

$$ \Pr!\left(|\hat\phi_t-\phi_t|\ge\varepsilon\right)\le 2\exp!\left(-\frac{2M\varepsilon^2}{R^2}\right) \quad\Rightarrow\quad M\ \ge\ \frac{R^2}{2\varepsilon^2},\ln\frac{2}{\delta}. $$

5. Каузальная валидация атрибуций (CSI)

Пусть $\mathcal R_{\mathrm{top}}$ — маска топ-$p%$ пикселей по важности (по $A_{i,j}$), а $\mathcal R_{\mathrm{bottom}}$ — нижние $p%$. Интервенция $\mathsf{do}\delta(\cdot;\mathcal R)$ модифицирует только область $\mathcal R$ (шум $\mathcal N(0,\delta^2)$, гауссово размытие $g\delta!\ast!\cdot$, перестановка патчей или константа — медиана по $\mathcal R$).

Эффект на модели (логит-сдвиг).

$$ \Delta_F(x;\mathcal R,\delta)=\big|,F(x)-F\big(\mathsf{do}_\delta(x;\mathcal R)\big),\big|. $$

Causal Shift Index.

$$ \mathrm{CSI}=\mathbb E_x\big[\Delta_F(x;\mathcal R_{\mathrm{top}},\delta)\big]- \mathbb E_x\big[\Delta_F(x;\mathcal R_{\mathrm{bottom}},\delta)\big]. $$

Статистическая проверка. Значимость различий оценивается t-критерием Уэлча:

$$ t=\frac{\bar\Delta_{\mathrm{top}}-\bar\Delta_{\mathrm{bottom}}} {\sqrt{,s^2_{\mathrm{top}}/n_{\mathrm{top}}+s^2_{\mathrm{bottom}}/n_{\mathrm{bottom}},}}, $$

со степенями свободы по формуле Уэлча–Саттертуэйта; альтернативно — перестановочный/бутстреп-тест.

⚡ Установка и запуск

🚀 Быстрая установка

# Клонирование репозитория
git clone https://github.com/fims9000/SYNT_ISIC.git
cd SYNT_ISIC

# Создание окружения
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS/Linux  
source .venv/bin/activate

# Установка зависимостей
pip install --upgrade pip
pip install -r requirements.txt

# Загрузка предобученных моделей
python download_models.py

📊 Запуск приложения

Windows:

# Рекомендуемый способ - двойной клик
run_isicgui.bat

# Альтернативно
python main.py

macOS/Linux:

python main.py

Важно: Все пути разрешаются относительно корня проекта — запуск возможен из любой директории

📋 Функциональность GUI

🎛️ Панели управления

Верхняя панель

Элемент	Назначение	Особенности
Select Models	Выбор папки с чекпоинтами	Должна содержать `unet_<CLASS>_best.pth`
Select Output	Папка для сохранения	Автосоздание подпапок по классам
XAI Mode	Переключение наложений	Integrated Gradients + SHAP
Device	CPU/CUDA выбор	Мониторинг памяти GPU

Центральная область

Живой предпросмотр с пропорциональным масштабированием
Индикатор прогресса с детализацией по шагам денойзинга (i/N)
Текстовые логи процесса генерации

Боковые панели

Слева: Конфигурация классов ISIC (MEL, NV, BCC, AKIEC, BKL, DF, VASC)
Справа: Браузер файлов с деревом проекта и навигацией

🧠 Алгоритм генерации

Технические характеристики

Модель: UNet2D (sample_size=128, RGB, блоки внимания)
Планировщик: DDPMScheduler (1000 шагов обучения, squaredcos_cap_v2)
Инференс: 50 шагов по умолчанию (настраиваемо)
Сидирование: MD5-производные смещения для классов + глобальный базовый сид

Процесс денойзинга

for t in reversed(range(num_inference_steps)):
    # Предсказание шума моделью
    noise_pred = unet(latent_sample, t, encoder_hidden_states)
    # Обновление планировщиком
    latent_sample = scheduler.step(noise_pred, t, latent_sample)

Explainability (XAI): методы и валидация

Интегральные градиенты (IG) — основной метод

Идея: интегрируем градиенты вдоль прямой от базовой точки x' к входу x; получаем поканальную (пиксельную) атрибуцию.
Гарантии: выполняются аксиомы полноты (сумма атрибуций равна разнице ответов), чувствительности и инвариантности реализации.
Практика: базовая точка — чёрный/размытый фон или стартовый шум; 64–128 точек дискретизации пути; при необходимости — сглаживание по масштабу.
Ограничения: зависимость от выбора x'; возможная насыщаемость градиентов (смягчается сглаживанием и ограничением динамического диапазона).

SHAP (значения Шэпли, аппроксимация)

Идея: кооперативная игра признаков; вклад каждого признака определяется как средний маржинальный выигрыш при подключении к коалициям.
Гарантии: аксиомы эффективности, симметрии, нулевого (фиктивного) игрока и аддитивности.
Практика: аппроксимация пермутациями/коалициями (обычно 500–1000 сэмплов); для изображений признаки — суперпиксели или патчи.
Ограничения: стоимость линейна по числу сэмплов; чувствительность к выбору фонового распределения.

Time-SHAP (временная атрибуция для диффузионного денойзинга)

Идея: «игроки» — временные шаги денойзинга; оцениваем вклад каждого шага в качество результата.
Оценочный функционал: используем логит целевого класса (устойчив к калибровке вероятностей).
Выход: вклады шагов φ_t и пиксельно-временные карты φ_{t,i,j}; агрегированная важность строится суммированием по времени с весами (обычно равномерными).
Свойства: соблюдены аксиомы эффективности, симметрии, нулевого шага и аддитивности; аппроксимация по пермутациям с концентрацией ошибки по неравенствам Хёффдинга.
Стоимость: пропорциональна числу пермутаций × числу шагов.

Каузальная валидация интерпретаций (CSI)

Интервенции: noise (добавление шума), blur (гауссово размытие), shuffle (перестановка патчей), const (замена на константу/медиану). Применяются к маскам top/bottom по важности.
Метрика: изменение отклика модели на логитах между исходным и заинтервенированным изображением; CSI — разница средних изменений для top- и bottom-масок.
Статистика: значимость различий оцениваем t-критерием Уэлча; при необходимости — перестановочные или бутстреп-тесты.
Интерпретация: чем выше CSI и ниже p-value, тем более каузально-состоятельны объяснения.

Визуализация и экспорт

Тепловые карты с нормализацией (min–max или по перцентилям 1–99) и альфа-блендингом поверх исходного изображения.
Поддержка статичных и временных карт (A_{i,j}, φ_{t,i,j}); опциональное гауссово сглаживание.
Экспорт: изображения (PNG/JPEG) + CSV с метаданными (seed, класс, число шагов, число пермутаций, типы интервенций, CSI/p-value).

⚙️ Настройки XAI

# Периодичность XAI анализа
XAI_OVERLAY_INTERVAL = 10  # Каждое 10-е изображение

# Настройки экспорта  
XAI_SAVE_EVERY_N = 5       # Контролируется GUI спин-боксом

# Классификатор
backbone = ResNet18(num_classes=7)  # Адаптирован под ISIC классы

🤝 Инструкция по использованию

🎯 Пошаговое руководство

Подготовка окружения

pip install -r requirements.txt
python download_models.py

Запуск и настройка
- Запустите run_isicgui.bat (Windows) или python main.py
- Выберите папку checkpoints через "Select Models"
- Укажите папку вывода через "Select Output"
Конфигурация генерации
- Выберите устройство (CPU/CUDA)
- Активируйте XAI Mode при необходимости
- Настройте "XAI steps" для детального экспорта
Генерация изображений
- Отметьте нужные классы в левой панели
- Задайте количество изображений для каждого класса
- Нажмите "Start" для начала процесса
Анализ результатов
- Просматривайте изображения в центральной области
- Изучайте XAI наложения при активированном режиме
- Открывайте папки и файлы через правую панель

🏥 Для медицинских исследований

# Рекомендуемые настройки для исследований
RESEARCH_CONFIG = {
    'base_seed': 42,              # Воспроизводимость
    'inference_steps': 50,        # Качество vs скорость  
    'xai_overlay_interval': 10,   # Частота XAI анализа
    'device': 'cuda:0'            # При наличии GPU
}

⚙️ Конфигурация системы

🔒 Управление ресурсами

Память GPU: Автоматическая очистка кеша после каждого изображения
Воспроизводимость: Детерминистские генераторы с фиксированными сидами
Пути: Все разрешаются относительно main.py, независимо от CWD
Логирование: Полные логи процесса в нижней консольной панели

📁 Структура выходных данных

output_folder/
├── MEL/                    # Подпапка класса меланомы
│   ├── ISIC_0000001.png   # Синтетические изображения
│   └── ISIC_0000002.png
├── NV/                     # Подпапка невуса  
│   └── ISIC_0000003.png
├── synthetic_dataset.csv   # Метаданные всех изображений
└── xai_overlays/          # XAI результаты (если активированы)

🛠️ Устранение неполадок

🔧 Частые проблемы

Проблема	Причина	Решение
CUDA out of memory	Нехватка GPU памяти	Уменьшить batch size или использовать CPU
Медленные XAI наложения	SHAP ресурсоемкий	Отключить XAI Mode или увеличить интервал
Ошибки рендеринга	Headless окружение	Автосохранение работает всегда

📋 Системные требования

Python: 3.8–3.11
ОС: Windows 10/11, macOS 10.15+, Ubuntu 18.04+
RAM: Минимум 8GB, рекомендуется 16GB+
GPU: Опционально NVIDIA с CUDA 11.0+ для ускорения

📚 Дополнительная информация

🔬 О папке `diffusion/`

Содержит справочный код обучения диффузионных моделей:

Не требуется для работы GUI
Предназначен для научной воспроизводимости
Может использоваться для дообучения на новых данных

🎓 Научная основа

Приложение реализует методологию, описанную в статье:

Трофимов Ю.В., Аверкин А.Н., Лопатин М.А., Трусов И.А. "Объяснимые диффузионные модели для медицинской диагностики: временная атрибуция и каузальная валидация"

🎓 Исследовательское финансирование

🏛️ Государственная исследовательская инициатива

Работа выполнена в рамках государственного задания Министерства науки и высшего образования Российской Федерации (тема № 124112200072-2)

Данное исследование проводится в рамках государственного задания Минобрнауки России, направленного на разработку доверенных ИИ систем для критически важных приложений.

⚠️ Важные уведомления

🔒 Медицинская ответственность

🚨 ИССЛЕДОВАТЕЛЬСКИЙ ИНСТРУМЕНТ Данное приложение предназначено исключительно для исследовательских целей. Синтетические изображения требуют валидации медицинскими экспертами перед любым клиническим использованием.

📄 Лицензия и цитирование

При использовании в научных работах просьба ссылаться на соответствующие публикации по диффузионным моделям и методам объяснимости.

🎯 Генерируйте синтетические дерматологические данные с полной объяснимостью процесса

Исследования - Разработка - Валидация

Name		Name	Last commit message	Last commit date
core		core
diffusion		diffusion
xai		xai
.gitignore		.gitignore
CITATION.cff		CITATION.cff
README.md		README.md
download_models.bat		download_models.bat
download_models.py		download_models.py
main.py		main.py
requirements.txt		requirements.txt
run_isicgui.bat		run_isicgui.bat

Latest commit

History

Folders and files

Repository files navigation