https://github.com/anaxagor/applybn

Multi-purpose data analysis framework based on Bayesian networks and Causal models
https://github.com/anaxagor/applybn

bayesian-networks causal-models concept-analysis feature-extraction feature-selection outlier-detection oversampling tabular-data time-series

Last synced: 3 months ago
JSON representation

Multi-purpose data analysis framework based on Bayesian networks and Causal models

• Host: GitHub
• URL: https://github.com/anaxagor/applybn
• Owner: Anaxagor
• License: mit
• Created: 2024-05-21T15:55:29.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2025-11-21T11:43:32.000Z (6 months ago)
• Last Synced: 2025-11-21T13:19:51.688Z (6 months ago)
• Topics: bayesian-networks, causal-models, concept-analysis, feature-extraction, feature-selection, outlier-detection, oversampling, tabular-data, time-series
• Language: Python
• Homepage: https://anaxagor.github.io/applybn/
• Size: 80.7 MB
• Stars: 22
• Watchers: 6
• Forks: 4
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
APPLYBN



	



Создано с помощью инструментов и технологий:



	

	






applybn — это многоцелевой фреймворк с открытым исходным кодом, основанный на байесовских сетях и каузальных моделях.

Он представляет анализ данных, основанный на понятных и интерпретируемых алгоритмах байесовских сетей и каузальных моделей.

![image](https://github.com/user-attachments/assets/996f8e5a-1742-4849-a64f-58b97a4cf17d)

## Ключевые особенности

### 1. **Обнаружение аномалий во временных рядах и табличных данных**

#### **Табличные данные**

   - Метод сочетает в себе обнаружение на основе условных распределений байесовской сети и оценку на основе близости.

   - Метод позволяет выявлять как выбросы по плотности, так и выбросы, возникающие из-за нарушения зависимостей между признаками.

#### **Временные ряды**

   - Метод выявляет выбросы в многомерных временных рядах, используя динамические байесовские сети (DBN) для моделирования временных и межпеременных зависимостей.

   - Его ключевые преимущества заключаются в улавливании сложных временных взаимозависимостей, автоматизации классификации выбросов с помощью адаптивных стратегий анализа оценок.

### 2. **Генерация синтетических данных**

   - Фреймворк включает методы для генерации синтетических обучающих данных при обнаружении дисбаланса классов в наборе данных. Используя гибридные байесовские сети (с моделями гауссовых смесей), он генерирует сбалансированные синтетические данные, улучшая результаты обучения моделей.

   - Метод позволяет учитывать взаимодействия между переменными, что повышает качество синтетических данных.

### 3. **Отбор и извлечение признаков**

#### **Отбор признаков на основе причинно-следственного эффекта**

   - Этот метод количественно оценивает причинно-следственные эффекты с помощью теории информации и пост-нелинейных моделей, автоматически выбирая признаки с ненулевым причинным влиянием на ключевые показатели эффективности (KPI) путем анализа снижения неопределенности в энтропии.

   - Метод отличается интерпретируемостью и стабильностью, отдавая приоритет причинно-следственным связям, избегает ручной настройки пороговых значений и надежно работает даже с ограниченными или нелинейными промышленными данными, повышая надежность программных датчиков.

#### **Отбор признаков на основе нормализованной взаимной информации**

   - Метод сочетает отбор признаков с правилами Мика для выявления марковских покрытий, используя взаимную информацию для сохранения узлов со значительными зависимостями и отсеивания нерелевантных или избыточных признаков в байесовских сетях.

   - Его ключевые преимущества включают эффективную обработку высокоразмерных данных за счет сосредоточения на локальных структурах, повышенную точность по сравнению с традиционными методами.

#### **Извлечение признаков на основе байесовских сетей**

   - Метод работает путем вывода условных зависимостей между признаками с использованием байесовских сетей и добавления вероятностных параметров (λ), представляющих эти зависимости, в исходный набор данных.

   - Его преимущества включают повышенную точность классификации в различных областях, снижение зависимости от априорных знаний и низкую вычислительную сложность, что обеспечивает надежное и интерпретируемое обогащение признаков без ограничений, специфичных для предметной области.

### 4. **Объяснимый анализ**

#### **Причинно-следственный анализ для моделей машинного обучения**

   - Метод анализа компонентов модели - строится структурная каузальная модель (SCM) для анализа моделей глубокого обучения, что позволяет отсеивать неважные части (например, фильтры в CNN) путем оценки их причинной важности.

   - Метод объяснения влияния данных на прогнозы позволяет делать причинно-следственные выводы между признаками и показателями уверенности модели. Рассчитывая **средний причинный эффект (ACE)**, он помогает определить, какие признаки значительно влияют на неопределенность модели, предоставляя ценную информацию для улучшения или отладки моделей.

### 5. **Совместимость со Scikit-learn**

Все оценщики и преобразователи данных совместимы со scikit-learn.

## Направления прикладного использования

Ниже приведён обобщённый перечень направлений прикладного использования фреймворка applybn на основе его ключевых возможностей:

### Обнаружение аномалий

- Финансы и банковская сфера: выявление мошеннических транзакций и отклонений в поведении клиентов на основе табличных и временных данных.

- Промышленный мониторинг и предиктивное обслуживание: раннее обнаружение отклонений в работе оборудования (например, датчиков на производственной линии) с учётом сложных временных зависимостей.

- Кибербезопасность: детектирование нетипичных событий в логах и сетевом трафике, нарушений привычных зависимостей между признаками.

### Генерация синтетических данных

- Преодоление дисбаланса классов: дополнение малочисленных классов в датасете (например, при классификации редких заболеваний или редких отказов в оборудовании).

- Конфиденциальность и защита персональных данных: создание «псевдо‑данных» для разработки и тестирования без утраты статистических свойств оригинала.

### Отбор и извлечение признаков

- Классификация и прогнозирование в бизнес-аналитике: автоматический выбор только причинно значимых факторов, влияющих на ключевые метрики (KPI), без ручной настройки порогов.

- Биоинформатика и медицина: отбор генов или клинических маркёров на основе причинных эффектов и взаимной информации при ограниченных размерах выборки.

- Рекомендательные системы: выявление наиболее релевантных факторов поведения пользователей для повышения качества рекомендаций.

### Объяснимый анализ моделей (Explainable AI)

- Debug и оптимизация нейронных сетей: анализ важности компонентов (фильтров, слоёв) через структурную каузальную модель, отсечение несущественных элементов.

- Регулирование и отчётность: формализация вклада каждого признака в предсказание модели для соответствия требованиям «чёрного ящика» (например, в страховании или кредитовании).

### Интеграция в ML‑конвейеры

- Полная совместимость со Scikit‑learn: применение в пайплайнах вместе с другими пре- и пост‑обработчиками, перекрёстная валидация, grid‑search, имплементация в sklearn.Pipeline/imblearn.Pipeline.

- Конвейеры для задач классификации: объединение этапов синтетической генерации, отбора признаков, ресемплинга и обучения модели в единую цепочку обработки.

### Образовательные и исследовательские задачи

- Курсы по машинному обучению, демонстрация работы байесовских сетей и динамических каузальных моделей (DBN).

- Научные исследования в области каузального анализа: тестирование и сравнение методов отбора на основе причинно-следственных эффектов.

## Технические требования

OS: Linux/MacOS/Windows

Python version: 3.11/3.12

Требования к железу аналогичны требованиям Pytorch в зависимости от использования GPU/CPU/MPS.

## Установка

### Установка системных зависимостей

Перед установкой applybn убедитесь, что у вас установлены системные зависимости.

#### Linux

Для этого обновите индексы репозиториев

(это надо сделать обязательно, чтобы ставилась Java):

```bash#

sudo apt update

```

Установите необходимые пакеты для cv2:

```bash

sudo apt install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 

```

Установите Java (требуется для работы с временными рядами):

```bash

sudo apt install -y openjdk-21-jdk

```

#### Windows

# Установить JDK 21

```

winget install EclipseAdoptium.Temurin.21.JDK

```

# Обновить переменные окружения

```shell

$javaHome = "C:\Program Files\Eclipse Adoptium\jdk-21.0.2.13-hotspot"

[Environment]::SetEnvironmentVariable("JAVA_HOME", $javaHome, "Machine")

```

# Перезапустить терминал и проверить

```shell

java -version

```

### pip

Чтобы установить applybn с помощью pip, используйте следующую команду

```

pip install applybn

```

### from source

Чтобы начать работу с applybn, клонируйте репозиторий и установите необходимые зависимости.

1. Установите менеджер пакетов [uv](https://github.com/astral-sh/uv)

```bash

# On macOS and Linux.

curl -LsSf https://astral.sh/uv/install.sh | sh

```

```bash

# On Windows.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

```

2. Клонируйте репозиторий и установите зависимости с помощью uv

```bash

git clone https://github.com/Anaxagor/applybn.git

cd applybn

uv pip install -r pyproject.toml

```

2.1. Для запуска примеров установите проект в editable режиме

```bash

uv pip install -e .

```

3. (Опционально) Установите torch и torchvision с [официального сайта](https://pytorch.org/). Для использования torch "^2.5.0" на GPU необходима видеокарта с поддержкой CUDA 12. 

### Проблемы с установкой

Если вы столкнулись с проблемами при установке, мы рекомендуем использовать контейнер Docker.

#### Установка и работа в Docker

1. Установите [Docker](https://docs.docker.com/get-docker/).

2. Клонируйте репозиторий applybn:

```bash

git clone https://github.com/Anaxagor/applybn

cd applybn

```

3. Постройте Docker-образ:

```bash

docker build -t applybn:latest .

```

На Mac с чипом M1/M2 может потребоваться указать платформу:

```bash

docker build --platform linux/amd64 -t applybn:latest .

```

4. Запустите контейнер:

```bash

docker run --ipc=host -it --rm applybn:latest bash

```

5. Внутри контейнера вы можете запускать скрипты с примерами.

Обратите внимание, пожалуйста, что вы должны находиться в директории `/app` внутри контейнера.

Оттуда вы можете запускать примеры, например:

```bash

poetry run python examples/anomaly_detection/tabular.py

```

Или:

```bash

poetry run pytest -s tests

```

## Пример конвейера Scikit-learn

Пример, демонстрирующий, как использовать несколько компонентов из библиотеки `applybn` в Pipeline, совместимом со scikit-learn. Мы рассмотрим отбор признаков, генерацию признаков, ресемплирование для несбалансированных наборов данных и обнаружение аномалий.

```python

import pandas as pd

import numpy as np

import warnings

import logging

import sys

from sklearn.model_selection import train_test_split

from sklearn.preprocessing import KBinsDiscretizer

from imblearn.pipeline import Pipeline as ImbPipeline

from sklearn.linear_model import LogisticRegression

from applybn.feature_selection.ce_feature_selector import CausalFeatureSelector

from applybn.feature_extraction.bn_feature_extractor import BNFeatureGenerator

from applybn.imbalanced.over_sampling.bn_over_sampler import BNOverSampler

from applybn.anomaly_detection.static_anomaly_detector.tabular_detector import TabularDetector

warnings.filterwarnings('ignore')

logging.getLogger().setLevel(logging.CRITICAL)

logging.disable(logging.CRITICAL)

logging.getLogger('applybn').setLevel(logging.CRITICAL)

logging.getLogger('applybn').disabled = True

class NullWriter:

    def write(self, txt): pass

    def flush(self): pass

original_stderr = sys.stderr

sys.stderr = NullWriter()

class CausalFeatureSelector2(CausalFeatureSelector):

    def fit(self, X, y):

        super().fit(X, y)

        self.selected_features_mask_ = self.get_support()

        return self

        

    def transform(self, X):

        return X.iloc[:, self.selected_features_mask_]

def generate_example_data(n_samples=200, n_features=5, n_cat_features=2, target_name='target_class', imbalance_ratio=0.1, random_state=42):

    """Генерирует синтетический несбалансированный набор данных."""

    rng = np.random.RandomState(random_state)

    X_cont_data = rng.rand(n_samples, n_features - n_cat_features)

    cont_feature_names = [f'cont_feature_{j}' for j in range(n_features - n_cat_features)]

    X_cont_df = pd.DataFrame(X_cont_data, columns=cont_feature_names)

    

    X_cat_df = pd.DataFrame()

    for i in range(n_cat_features):

        cat_feature_name = f'cat_feature_{i}'

        temp_cont_for_cat = rng.rand(n_samples)

        n_bins_cat = rng.randint(2, 4)

        discretizer = KBinsDiscretizer(n_bins=n_bins_cat, encode='ordinal', strategy='uniform', subsample=None, random_state=rng)

        # Сохраняем категориальные признаки как целые числа

        X_cat_df[cat_feature_name] = discretizer.fit_transform(temp_cont_for_cat.reshape(-1, 1)).ravel().astype(int)

    X_df = pd.concat([X_cont_df, X_cat_df], axis=1)

    

    n_class1 = int(n_samples * imbalance_ratio)

    n_class0 = n_samples - n_class1

    y_array = np.array([0] * n_class0 + [1] * n_class1)

    rng.shuffle(y_array)

    y_series = pd.Series(y_array, name=target_name, dtype=int)

    return X_df, y_series

# --- Основной пример ---

TARGET_NAME = 'target_class_example'

# 1. Генерация данных

print("1. Генерация синтетических данных...")

X_df, y_s = generate_example_data(n_samples=250, n_features=6, n_cat_features=2, target_name=TARGET_NAME, imbalance_ratio=0.15, random_state=42)

X_train_df, X_test_df, y_train_s, y_test_s = train_test_split(X_df, y_s, test_size=0.3, random_state=42, stratify=y_s)

print(f"   Обучающие данные: {X_train_df.shape}, Тестовые данные: {X_test_df.shape}")

print(f"   Распределение целевой переменной (обучение):\n{y_train_s.value_counts(normalize=True).to_string()}\n")

# 2. Обработка данных с обнаружением аномалий

X_train_df = X_train_df.reset_index(drop=True)

y_train_s = y_train_s.reset_index(drop=True)

X_test_df = X_test_df.reset_index(drop=True)

y_test_s = y_test_s.reset_index(drop=True)

detector = TabularDetector(target_name=TARGET_NAME, additional_score="IF")

X_train_df[TARGET_NAME] = y_train_s

detector.fit(X_train_df)

scores = detector.predict_scores(X_train_df)

threshold = np.percentile(scores, 95)

mask = scores <= threshold # Выбираем 5% самых аномальных примеров

X_train_df = X_train_df[mask]

y_train_s = X_train_df[TARGET_NAME]

y_train_s = y_train_s.reset_index(drop=True)

X_train_df = X_train_df.drop(columns=[TARGET_NAME])

X_train_df = X_train_df.reset_index(drop=True)

# 3. Создание полного конвейера с отбором признаков, генерацией признаков, передискретизацией и классификацией

processing_pipeline = ImbPipeline([

    ('feature_selector', CausalFeatureSelector2(n_bins=3)),

    ('bn_features', BNFeatureGenerator()),

    ('oversampler', BNOverSampler(class_column=TARGET_NAME, strategy='max_class', shuffle=True)),

    ('classifier', LogisticRegression(solver='liblinear', random_state=42))

    

])

# 4. Обучение и оценка конвейера

print("\n2. Обучение полного конвейера...")

processing_pipeline.fit(X_train_df, y_train_s)

pipeline_score = processing_pipeline.score(X_test_df, y_test_s)

print(f"   Точность конвейера на тестовых данных: {pipeline_score:.4f}\n")

print("\n--- Пример завершен ---")

```

## Помощь и поддержка

### Документация с примерами

Документацию с примерами можно найти [здесь](https://anaxagor.github.io/applybn/).

### Связь

Не стесняйтесь создавать новые [задачи](https://github.com/Anaxagor/applybn/issues).

Если у вас есть вопросы или предложения, вы можете связаться с нами по следующим ресурсам:

* [Helpdesk в чате Telegram](https://t.me/+4FOcyF0Rri00ZGEy)

* ideeva@itmo.ru (Ирина Деева)

### Участие в разработке

Вклад в applybn приветствуется! Если вы заинтересованы в улучшении каких-либо функций или тестировании новых веток, пожалуйста, ознакомьтесь с разделом [Как внести вклад](https://anaxagor.github.io/applybn/development/contributing/) документации.

### Лицензия

applybn распространяется под лицензией MIT. Дополнительную информацию см. в файле `LICENSE`.

## Цитирование

```bibtex

@software{applybn,

  author = {Irina Deeva},

  title = {applybn},

  url = {https://github.com/Anaxagor/applybn},

  version = {0.1.0},

  date = {2025-05-03},

}

```

## Благодарности

Проект поддержан [Фондом содействия инновациям](https://fasie.ru/).