diff --git a/lab1/.gitignore b/lab1/.gitignore index dc41540..83afa59 100644 --- a/lab1/.gitignore +++ b/lab1/.gitignore @@ -18,3 +18,6 @@ __pycache__/ /presentation/latex/*.toc /presentation/latex/*.synctex.gz /presentation/latex/preview/ + +/report/build/ +/dist/stage/ diff --git a/lab1/ARCHIVE_README.md b/lab1/ARCHIVE_README.md new file mode 100644 index 0000000..b723362 --- /dev/null +++ b/lab1/ARCHIVE_README.md @@ -0,0 +1,529 @@ +# Архив лабораторной работы №1 + +**Тема:** классификация текстов на основе стилометрических характеристик. +**Материал:** реплики персонажей игры Stardew Valley. +**Задача:** по одной реплике определить, какому из 34 персонажей она +принадлежит, и проверить, какие стилометрические признаки несут этот сигнал. + +Это не авторская атрибуция: все реплики написаны одним автором. Мы различаем +**речевые маски персонажей** — намеренно созданные автором различия в лексике, +синтаксисе, пунктуации и разговорных маркерах. + +--- + +## 1. Что в архиве + +| Путь | Что это | +|---|---| +| `lab1/report/REPORT.pdf` | Итоговый отчёт, 21 страница. Главный документ. | +| `lab1/report/REPORT.docx` | Редактируемая версия отчёта. | +| `lab1/report/REPORT.md` | Исходник отчёта в Markdown. | +| `lab1/report/figures/` | Рисунки отчёта. | +| `lab1/presentation/stardew_stylometry.pdf` | Презентация для защиты. | +| `lab1/presentation/stardew_stylometry.pptx` | Редактируемая презентация. | +| `lab1/presentation/latex/` | LaTeX-исходник и PDF презентации. | +| `lab1/presentation/images/`, `generated/` | Исходные изображения и диаграммы. | +| `lab1/stylometry/` | Основной код проекта. | +| `lab1/scripts/` | Проверка окружения, запуск серий, сборка отчёта, упаковка. | +| `lab1/tests/` | 33 теста (`pytest`). | +| `lab1/configs/default.toml` | Конфигурация по умолчанию. | +| `lab1/data/dialogues.csv` | Корпус: 2005 реплик, cp1251, разделитель `;`. | +| `lab1/data/dialogues.xlsx` | Тот же корпус в Excel. | +| `lab1/data/stats_per_character.xlsx` | Статистика по персонажам. | +| `lab1/data/metadata/` | Метаданные персонажей для анализа ошибок. | +| `lab1/data/corpus_report_*.txt` | Отчёты о состоянии корпуса до/после очистки. | +| `lab1/FINAL_RESULTS.csv` | Сводная таблица финальных результатов. | +| `lab1/FINAL_REPORT.md` | Расширенная версия отчёта с деталями экспериментов. | +| `lab1/EXPERIMENTS.md` | Протокол экспериментов и команд. | +| `lab1/FEATURES.md` | Признаки, формулы, обоснование. | +| `lab1/METRICS_AND_CLASSIFIERS.md` | Метрики и классификаторы. | +| `lab1/TUNING.md` | Настройка гиперпараметров. | +| `lab1/RUNBOOK.md` | Подробная инструкция по запуску полной серии. | +| `lab1/RESULTS_ANALYSIS.md` | Анализ результатов и ошибок. | +| `lab1/FOLLOWUP_EXPERIMENTS.md` | Дополнительные эксперименты. | +| `lab1/PRESENTATION_OUTLINE.md` | Структура презентации. | +| `lab1/exports/nlp_lab1_final_results_20261026_120000.tar.gz` | Финальные результаты в компактном виде. | +| `lab1/requirements.txt` | Основные зависимости. | +| `lab1/requirements-report.txt` | Зависимости для пересборки отчёта. | + +Полный список файлов с размерами и SHA-256 — в `MANIFEST.txt`. +Контрольные суммы ключевых файлов — в `CHECKSUMS.sha256`. + +--- + +## 2. Требования + +### 2.1. Обязательные + +- Python **3.11+** (проверено на 3.14); +- Linux, macOS или Windows с WSL; +- около 1 ГБ свободного места с виртуальным окружением и NLTK; +- интернет — только для установки пакетов и скачивания NLTK. + +### 2.2. Для пересборки отчёта + +- `pandoc` 3.x; +- LibreOffice (`libreoffice --headless`); +- Python-пакеты `python-docx`, `PyMuPDF` (см. `requirements-report.txt`); +- шрифты с кириллицей: Times New Roman или Liberation Serif, Liberation Mono. + +### 2.3. Для пересборки LaTeX-презентации + +- XeLaTeX; +- пакеты Beamer, tcolorbox, TikZ, fontspec, babel-russian; +- шрифт Liberation Sans. + +--- + +## 3. Установка + +Все команды выполняются из каталога `lab1`: + +```bash +cd lab1 +``` + +### 3.1. Виртуальное окружение + +```bash +python -m venv .venv +source .venv/bin/activate +``` + +Windows PowerShell: + +```powershell +python -m venv .venv +.venv\Scripts\activate +``` + +Если окружение уже есть в корне проекта, можно использовать его: + +```bash +source ../.venv/bin/activate +``` + +### 3.2. Зависимости + +```bash +python -m pip install --upgrade pip +python -m pip install -r requirements.txt +``` + +Для пересборки отчёта дополнительно: + +```bash +python -m pip install -r requirements-report.txt +``` + +### 3.3. Ресурсы NLTK + +```bash +python scripts/download_nltk_data.py +``` + +Скрипт скачивает `punkt`, `punkt_tab`, `averaged_perceptron_tagger`, +`averaged_perceptron_tagger_eng`, `stopwords` в `lab1/nltk_data`. + +Без этих ресурсов POS-признаки отключатся, а результаты будут неполными. +Если машина без интернета, скопируйте готовый каталог `nltk_data` в `lab1/`. + +### 3.4. Проверка + +```bash +python scripts/check_environment.py +python -m pytest -q +``` + +Ожидается: + +```text +Окружение готово. +33 passed +``` + +`check_environment.py` печатает версии библиотек, SHA-256 корпуса, число +реплик, персонажей и словоупотреблений, проверяет токенизатор и POS-теггер. + +--- + +## 4. Быстрый запуск + +### 4.1. Аудит корпуса + +```bash +python -m stylometry.cli audit +``` + +Создаёт: + +- `data/processed/audit.md` — отчёт по корпусу; +- `data/processed/lines.csv` — нормализованные реплики; +- `data/processed/figures/class_distribution.png`. + +Проверьте: 2005 реплик, 34 персонажа, 38 207 словоупотреблений, точных +дублей нет. + +### 4.2. Ручные признаки + +```bash +python -m stylometry.cli features +``` + +Создаёт: + +- `features/stylometric.csv` — матрица 2005 × 454; +- `features/feature_dictionary.csv` — описание признаков. + +### 4.3. Одна модель + +```bash +python -m stylometry.cli run \ + --preset stylometry_pos_lsa \ + --model logreg \ + --folds 5 \ + --repeats 5 +``` + +Результаты появятся в `results/__/`: +`summary.md`, `summary.json`, `fold_metrics.csv`, `pooled_metrics.csv`, +`per_class_report.csv`, `confusion_matrix.csv`, `oof_predictions.csv`. + +### 4.4. Полная серия + +```bash +bash scripts/run_all_experiments.sh +``` + +Скрипт последовательно запускает все стадии и пишет лог в +`results/logs/run_all_.log`. Ориентировочное время — 1,5–3 часа +на обычном ноутбуке. Быстрый режим без финальных чисел: + +```bash +QUICK=1 bash scripts/run_all_experiments.sh +``` + +### 4.5. Финальные серии + +```bash +python scripts/run_final_experiments.py \ + --stages nested topic calibration ensemble extra \ + --out results/final +``` + +Эта команда воспроизводит вложенный выбор конфигурации, контроль содержания, +коррекцию приоров, ансамбли и дополнительные конфигурации. Именно эти +результаты сведены в `FINAL_RESULTS.csv` и в отчёте. + +--- + +## 5. Что делает каждый модуль + +| Модуль | Назначение | +|---|---| +| `stylometry/io.py` | Чтение CSV/XLSX, проверка колонок, SHA-256 корпуса. | +| `stylometry/cleaning.py` | Unicode-нормализация, плейсхолдеры, пробелы. | +| `stylometry/tokenization.py` | NLTK: токенизация, предложения, POS; резервный режим. | +| `stylometry/features/` | 454 ручных признака в 11 группах. | +| `stylometry/lsa.py` | TF-IDF + TruncatedSVD для word/content/fw/char/pos. | +| `stylometry/pipelines.py` | Объединение блоков признаков, модели, сетки параметров. | +| `stylometry/cv.py` | Повторная стратифицированная и вложенная кросс-валидация. | +| `stylometry/evaluation.py` | Macro-F1, accuracy, balanced accuracy, MCC, каппа, top-k, log loss, Brier, бутстрэп. | +| `stylometry/stats.py` | Мак-Немар, Уилкоксон, Фридман, поправка Холма. | +| `stylometry/delta.py` | Дельта Барроуза: MFW, z-нормирование, манхэттенское и косинусное расстояние. | +| `stylometry/verification.py` | Верификация «свой/чужой»: ROC-AUC, EER, TAR@FAR. | +| `stylometry/clustering.py` | Иерархическая и k-means кластеризация, ARI, NMI, силуэт. | +| `stylometry/plotting.py` | Диаграммы классов, scree, матрицы ошибок, PCA, t-SNE. | +| `stylometry/metadata.py` | Метаданные персонажей, анализ подгрупп. | +| `stylometry/cli.py` | Единая точка входа для всех команд. | +| `main.py` | Короткая обёртка над `stylometry.cli`. | + +### Группы ручных признаков + +1. Длина. +2. Лексика. +3. Словарное богатство. +4. Символы. +5. Пунктуация. +6. Функциональные слова. +7. Местоимения. +8. Части речи. +9. Синтаксис. +10. Читаемость. +11. Разговорные маркеры. + +Формулы и обоснование — в `FEATURES.md`. + +--- + +## 6. Данные и разметка + +### 6.1. Формат + +`data/dialogues.csv`: + +- кодировка cp1251; +- разделитель `;`; +- колонки `Реплика` и `Персонаж`; +- 2005 строк, 34 класса. + +`data/dialogues.xlsx` — тот же корпус для Excel. +`data/stats_per_character.xlsx` — число реплик и длины по персонажам. +`data/metadata/` — пол, возраст, вид и роль для анализа ошибок; в признаки +классификатора эти поля не подаются. + +### 6.2. Правила разметки + +1. Одна реплика — один объект. +2. Метка — имя говорящего. +3. Один объект относится ровно к одному классу. +4. Соответствие реплики и метки проверено вручную. +5. Служебные метки ``, ``, ``, ``, `