Metadata-Version: 2.1
Name: lancetnic
Version: 2.1.0
Summary: A tool for working with text data
Home-page: https://github.com/Lancet52/lancetnic
Author: Lancet52
Author-email: lancetFPV@yandex.ru
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# LANCETNIC 2.1.0

[![PyPI Package Version](https://img.shields.io/pypi/v/lancetnic.svg?style=flat-square)](https://pypi.org/project/lancetnic/)
[![PyPi status](https://img.shields.io/pypi/status/lancetnic.svg?style=flat-square)](https://pypi.python.org/pypi/lancetnic)
[![Downloads](https://static.pepy.tech/badge/lancetnic)](https://pepy.tech/project/lancetnic)
[![Downloads](https://img.shields.io/pypi/dm/lancetnic.svg?style=flat-square)](https://pypi.python.org/pypi/lancetnic)
[![MIT License](https://img.shields.io/pypi/l/lancetnic.svg?style=flat-square)](https://opensource.org/licenses/MIT)

### LANCETNIC - это библиотека, которая представляет базовый набор для решения задач:

- Классификации текстовых, числовых данных, а также их комбинаций.


### Библиотека предоставляет ряд инструментов для:
- Подготовки и векторизации данных перед обучением.
- Обучению модели.
- Визуализации метрик по окончании обучения, на основании которых принимается решение о точности обученной модели.
- Инференса модели на основе новых данных.

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


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

## 🚀 Установка:
Установка с помощью CUDA

Для работы с графическим процессором рекомендуется установить PyTorch с поддержкой CUDA (НЕОБЯЗАТЕЛЬНО):

```bash
pip install torch==2.5.1+cu124 torchaudio==2.5.1+cu124 torchvision==0.20.1+cu124 --index-url https://download.pytorch.org/whl/cu124
```

Затем установка lancetnic:

```bash
pip install lancetnic
```

## 👥 Авторы

- [Lancet52](https://github.com/Lancet52)

## 📄 Документация:

<div align="center">

## Задача классификации

<img src="lancetnic/docs/images/classification.png" alt="Классификация" width="500">
</div>

- ### Класс `TextClass()`
Позволяет работать с текстовыми данными.
```Python
from lancetnic import TextClass
```

| Атрибут         | Тип       | Допустимые значения | Описание |
|-----------------|-----------|---------------------|----------|
| `text_column`  | string   | Любое валидное название столбца | Название столбца с текстовыми данными |
| `label_column` | string   | Любое валидное название столбца | Название столбца с целевыми метками |
| `split_ratio`  | float    | (0.01, 0.99) | Доля данных для валидации (при val_path=None) |
| `random_state` | int      | (1, 99) | Фиксированный seed (по умолчанию: 42) |
           
### метод `train`

| Параметр       | Тип       | Значения | Описание |
|----------------|-----------|----------|----------|
| `model_name`   | class    | LancetMC/LancetMCA | Архитектура модели |
| `train_path`   | string   | Путь | Путь к обучающим данным (CSV) |
| `val_path`     | string   | Путь/None | Путь к валидационным данным |
| `num_epochs`   | int      | ≥1 | Количество эпох |
| `hidden_size`  | int      | ≥1 | Нейронов в слое (по умолчанию 256) |
| `num_layers`   | int      | ≥1 | Количество слоёв (по умолчанию 1) |
| `batch_size`   | int      | ≥1 | Размер батча (по умолчанию 128) |
| `learning_rate`| float    | (1e-5, 1e-1) | Learning rate (по умолчанию 0.001) |
| `dropout`      | float    | [0.0, 0.99) | Dropout (по умолчанию 0) |
| `optim_name`   | string   | Adam/RAdam/SGD/RMSprop/Adadelta | Оптимизатор |
| `crit_name`    | string   | CELoss | Функция потерь |

### метод `predict`

| Параметр       | Тип       | Значения | Описание |
|----------------|-----------|----------|----------|
| `model_path`   | string   | Путь | Путь к модели (.pth) |
| `text`         | string   | Текст | Текст для классификации |


### Пример для калссификации текста
```Python
from lancetnic.models import LancetMC
from lancetnic import TextClass

text_model = TextClass(
            text_column='description',  # Имя столбца, содержащего текстовые данные
            label_column='category',    # Имя столбца, содержащего метки
            split_ratio=0.2,            # Соотношение между обучением и валидацией (если val_path отсутствует)
            random_state=42             # Случайное начальное значение для воспроизводимости результатов
            )

text_model.train(model_name=LancetMC,   # Имя модели (доступен выбор из библиотеки)
                train_path="train.csv", # Путь к тренировочным данным (формат CSV)
                val_path=None,          # Путь к валидационным данным. Может отсутсвовать: None
                num_epochs=50,          # Количество эпох обучения
                hidden_size=256,        # Размер скрытого слова (количество нейронов в слое)
                num_layers=1,           # Количество скрытых слоев
                batch_size=256,         # Размер пакетов (батчей) для обучения
                learning_rate=0.001,    # Скорость обучения для оптимизатора
                dropout=0,              # Процент отключенных нейронов (0-1)
                optim_name='Adam',      # Оптимизатор ('Adam', 'SGD', 'RAdam', и др.)
                crit_name='CELoss'      # Функция потерь ('CELoss' и др.)
                )
```
### Инференс модели
```Python
from lancetnic import TextClass

text_model = TextClass()
text_pred = text_model.predict(
                model_path="model.pth", # Путь до модели
                text="Sample text to classify" # Текст для классификации
                )
```

- ### Класс `TextScalarClass()`
```Python
from lancetnic import TextScalarClass
```

| Атрибут         | Тип       | Допустимые значения | Описание |
|-----------------|-----------|---------------------|----------|
| `text_column`  | string   | Название столбца или None | Столбец с текстом (None если только числа) |
| `data_column`  | list     | Список столбцов | Числовые признаки |
| `label_column` | string   | Любое валидное название столбца | Целевые метки |
| `split_ratio`  | float    | (0.01, 0.99) | Доля для валидации |
| `random_state` | int      | (1, 99) | Random seed (по умолчанию 42) |

### метод `train`

| Параметр       | Тип       | Значения | Описание |
|----------------|-----------|----------|----------|
| `model_name`   | class    | LancetMC/LancetMCA | Архитектура модели |
| `train_path`   | string   | Путь | Путь к обучающим данным (CSV) |
| `val_path`     | string   | Путь/None | Путь к валидационным данным |
| `num_epochs`   | int      | ≥1 | Количество эпох |
| `hidden_size`  | int      | ≥1 | Нейронов в слое (по умолчанию 256) |
| `num_layers`   | int      | ≥1 | Количество слоёв (по умолчанию 1) |
| `batch_size`   | int      | ≥1 | Размер батча (по умолчанию 128) |
| `learning_rate`| float    | (1e-5, 1e-1) | Learning rate (по умолчанию 0.001) |
| `dropout`      | float    | [0.0, 0.99) | Dropout (по умолчанию 0) |
| `optim_name`   | string   | Adam/RAdam/SGD/RMSprop/Adadelta | Оптимизатор |
| `crit_name`    | string   | CELoss | Функция потерь |

### метод `predict`

| Параметр       | Тип       | Значения | Описание |
|----------------|-----------|----------|----------|
| `model_path`   | string   | Путь | Путь к модели (.pth) |
| `text`         | string   | Текст | Текст для классификации |
| `numeric`      | list     | Числа | Числовые признаки (только TextScalarClass) |

### Пример классификации комбинированных текстовых и числовых элементов
```Python
from lancetnic.models import LancetMC
from lancetnic import TextScalarClass

mixed_model = TextScalarClass(
                text_column='description',      # Имя столбца содержащего текст (отсутствует, если в НД только числовые данные)
                data_column=['feat1', 'feat2'], # Список столбцов содержащих числовые характеристики
                label_column='target',          # Имя столбца, содержащего метки
                split_ratio=0.2,                # Соотношение между обучением и валидацией (если val_path отсутствует)
                random_state=42                 # Случайное начальное значение для воспроизводимости результатов
                )

mixed_model.train(model_name=LancetMC,  # Имя модели (доступен выбор из библиотеки)
                train_path="train.csv", # Путь к тренировочным данным (формат CSV)
                val_path=None,          # Путь к валидационным данным. Может отсутсвовать: None
                num_epochs=50,          # Количество эпох обучения
                hidden_size=256,        # Размер скрытого слова (количество нейронов в слое)
                num_layers=1,           # Количество скрытых слоев
                batch_size=256,         # Размер пакетов (батчей) для обучения
                learning_rate=0.001,    # Скорость обучения для оптимизатора
                dropout=0,              # Процент отключенных нейронов (0-1)
                optim_name='Adam',      # Оптимизатор ('Adam', 'SGD', 'RAdam', и др.)
                crit_name='CELoss'      # Функция потерь ('CELoss' и др.)
                )
```

### Классификация массива данных
```Python
from lancetnic import TextScalarClass

mixed_model = TextScalarClass()
mixed_pred = mixed_model.predict(
                model_path="mixed_model.pth",   # Путь до модели
                text="Product description",     # Текстовые данные (может отсутсвовать None)
                numeric=[0.5, 1.2]              # Числовые данные в виде списка
                )
```


## Модели для задачи классификации

- LancetMC
```Python
from lancetnic.models import LancetMC
```
- LancetMCA
```Python
from lancetnic.models import LancetMC
```
- ScalpelMC
```Python
from lancetnic.models import ScalpelMC
```

 Сравнительная таблица стоковых моделей

| Характеристика | LancetMC | LancetMCA | ScalpelMC |
|----------------|----------|-----------|-----------|
| **Архитектура** | LSTM | LSTM + Attention | Fully Connected Network |
| **Назначение** | Многоклассовая классификация последовательностей | Многоклассовая классификация с вниманием | Многоклассовая классификация статических данных |
| **Механизм внимания** | ❌ | ✅ | ❌ |
| **Обучение** | Медленнее | Самый медленный | Быстрое |
| **Применение** | Временные ряды | Длинные последовательности, временные ряды | Табличные данные, простейшие признаки |

## По окончании обучения в создется папка с проектом
```markdown
📁 runs/
├── 📁 train_0/ # Проект
│ ├── 📦 best_model.pt # Модель с лучшими весами
│ ├── 📦 last_model.pt # Модель с весами на последней эпохи обучения
│ ├── 📊 result.csv # Данные по каждой эпохе обучения
│ ├── 🖼️ confusion_matrix_best_model.png # Матрица ошибок для best_model.pt
│ ├── 🖼️ confusion_matrix_last_model.png # Матрица ошибок для last_model.pt
│ ├── 🖼️ dataset_counts.png # Количество датасета
│ ├── 🖼️ f1_score.png # Метрика F1 score
│ ├── 🖼️ train_val_acc.png # График train/val accuracy
│ ├── 🖼️ train_val_loss.png # График train/val loss
│ ├── ⚙️ hyperparams.yaml
├── 📁 train_1/
...
```
