Mermutef/NLP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
32b61750bfb4192d757e9e591b5b96c0ebddda1b
NLP/lab1/ARCHIVE_README.md

22 KiB
Raw Blame History

Архив лабораторной работы №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:

cd lab1

3.1. Виртуальное окружение

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.venv\Scripts\activate

Если окружение уже есть в корне проекта, можно использовать его:

source ../.venv/bin/activate

3.2. Зависимости

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Для пересборки отчёта дополнительно:

python -m pip install -r requirements-report.txt

3.3. Ресурсы NLTK

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. Проверка

python scripts/check_environment.py
python -m pytest -q

Ожидается:

Окружение готово.
33 passed

check_environment.py печатает версии библиотек, SHA-256 корпуса, число реплик, персонажей и словоупотреблений, проверяет токенизатор и POS-теггер.

4. Быстрый запуск

4.1. Аудит корпуса

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. Ручные признаки

python -m stylometry.cli features

Создаёт:

  • features/stylometric.csv — матрица 2005 × 454;
  • features/feature_dictionary.csv — описание признаков.

4.3. Одна модель

python -m stylometry.cli run \
    --preset stylometry_pos_lsa \
    --model logreg \
    --folds 5 \
    --repeats 5

Результаты появятся в results/<preset>_<model>_<timestamp>/: summary.md, summary.json, fold_metrics.csv, pooled_metrics.csv, per_class_report.csv, confusion_matrix.csv, oof_predictions.csv.

4.4. Полная серия

bash scripts/run_all_experiments.sh

Скрипт последовательно запускает все стадии и пишет лог в results/logs/run_all_<timestamp>.log. Ориентировочное время — 1,5–3 часа на обычном ноутбуке. Быстрый режим без финальных чисел:

QUICK=1 bash scripts/run_all_experiments.sh

4.5. Финальные серии

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. Служебные метки <PLAYER>, <FARM>, <PET>, <SPOUSE>, <TIME>, <NOUN>, <NAME> заменены нейтральными словами; их число сохранено отдельным признаком.

6.3. Очистка и шум

Нормализуется только Unicode: варианты кавычек, тире, многоточий и пробелов. Пунктуация, регистр и стоп-слова сохраняются — это стилометрический сигнал.

Шумом считались точные дубликаты, технические артефакты, общие короткие формулы и плейсхолдеры. Корпус прошёл ручную фильтрацию; точные правила фильтрации не сохранились, поэтому исходное распределение восстановить нельзя. Это ограничение зафиксировано в отчёте.

6.4. Ограничение по объёму

Формальные требования: не менее 90 текстов по 30 предложений и примерно равные классы. В этом корпусе единица анализа — реплика (в среднем 19 слов), классы неравномерны (15–139 реплик). По согласованию с преподавателем эксперимент выполнен на уровне реплик; в отчёте раздел 2.5 честно описывает это отклонение. Для компенсации используются веса классов и macro-F1.

7. Метрики и результаты

Основная метрика — macro-F1: средняя F-мера по 34 классам, каждый персонаж весит одинаково. Дополнительно считаются accuracy, balanced accuracy, top-3/top-5, MCC, каппа Коэна, log loss, Brier, матрица ошибок, бутстрэп-интервалы.

Конфигурация Macro-F1
Мягкое голосование трёх моделей 0,3036 ± 0,0189
ExtraTrees, char_max_features=10000 0,2757 ± 0,0219
Вложенный выбор конфигурации 0,2746 ± 0,0233
ExtraTrees, полный набор 0,2499 ± 0,0209
Логистическая регрессия, lean + content-LSA 0,2466 ± 0,0191
Случайный лес, char_max_features=10000 0,2583 ± 0,0066
Только ручные признаки 0,1051 ± 0,0038
Случайный уровень 0,029

На отложенной выборке 80/20 мягкое голосование дало 0,3333.

Контроль содержания: после замены существительных, глаголов, прилагательных, наречий и числительных маркером CONTENT macro-F1 падает с 0,2483 до 0,1129. Остаток всё ещё выше случайного уровня, но основной сигнал — лексико-тематический.

8. Как пересобрать отчёт

Отчёт собирается из report/REPORT.md:

cd lab1
python scripts/build_report.py

Скрипт:

  1. вызывает pandoc и делает report/build/REPORT_raw.docx;
  2. оформляет стили, поля, колонтитулы, таблицы и рисунки;
  3. сохраняет report/REPORT.docx;
  4. конвертирует DOCX в report/REPORT.pdf через LibreOffice;
  5. проверяет, что в PDF есть все основные разделы.

Только DOCX:

python scripts/build_report.py --skip-pdf

Требования: pandoc, libreoffice, python-docx, PyMuPDF. Рисунки лежат в report/figures/; Markdown ссылается на них относительно report/.

9. Как пересобрать презентацию

9.1. PPTX

В архиве лежит финальная версия stardew_stylometry.pptx (30 слайдов) после ручных правок. Скрипт build_deck.py — генератор исходной версии презентации; он создаёт 32 слайда и перезапишет финальный файл, если его запустить. Не запускайте скрипт, если хотите сохранить ручные правки: для изменений открывайте PPTX в PowerPoint или LibreOffice.

Если нужно пересобрать исходную версию с нуля:

cd lab1/presentation
python build_deck.py

Скрипт использует python-pptx, Pillow и matplotlib. Диаграммы уже лежат в presentation/generated/; для их перегенерации нужны результаты серий (results/final/...), которых нет в архиве — сначала запустите эксперименты из раздела 4.

9.2. LaTeX/PDF

cd lab1/presentation/latex
xelatex stardew_stylometry.tex
xelatex stardew_stylometry.tex

Нужны XeLaTeX, Beamer, tcolorbox, TikZ и шрифт Liberation Sans. Готовый PDF — stardew_stylometry.pdf. Изображения подтягиваются из ../images/ и ../generated/.

10. Где смотреть результаты

  • lab1/report/REPORT.pdf — итоговый отчёт со всеми числами и выводами.
  • lab1/FINAL_RESULTS.csv — сводная таблица всех финальных конфигураций.
  • lab1/FINAL_REPORT.md — расширенное описание экспериментов.
  • lab1/RESULTS_ANALYSIS.md — анализ ошибок, классов-аттракторов и длины.
  • lab1/exports/nlp_lab1_final_results_20261026_120000.tar.gz — исходные summary.json, fold_metrics.csv, confusion_matrix.csv и предсказания финальных серий.
  • lab1/presentation/generated/ — диаграммы для отчёта и презентации.

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

check_environment.py не находит POS-теггер

Повторите:

python scripts/download_nltk_data.py

Проверьте, что каталог lab1/nltk_data существует и не пуст. Если сеть недоступна, скопируйте nltk_data с другой машины.

pytest не устанавливается

Убедитесь, что активировано виртуальное окружение и версия Python не ниже 3.11:

python --version
python -m pip install -r requirements.txt

python -m stylometry.cli не находит модуль

Команда должна выполняться из каталога lab1, а не из корня репозитория:

cd lab1
python -m stylometry.cli audit

LibreOffice не собирает PDF

Проверьте:

libreoffice --version

На сервере без графической сессии используйте именно --headless (это уже делает build_report.py). Если LibreOffice нет, отчёт можно открыть в Word/LibreOffice вручную и экспортировать в PDF.

Кириллица в PDF выглядит квадратами

Установите шрифты Liberation Serif/Sans и Liberation Mono. В отчёте используются Times New Roman (с запасным Liberation Serif) и Liberation Mono.

Полная серия идёт слишком долго

Запускайте в tmux или nohup, см. RUNBOOK.md, раздел 5.4. Для проверки работоспособности используйте QUICK=1.

12. Что исключено из архива

Чтобы архив оставался компактным и воспроизводимым, в него не включены:

  • .venv/ — виртуальное окружение;
  • .git/ — история репозитория;
  • nltk_data/ — скачивается скриптом;
  • data/processed/ — аудит и промежуточные таблицы;
  • features/ — матрица признаков (создаётся features);
  • results/ — промежуточные результаты серий;
  • большие exports/*.tar.gz — кроме компактного финального архива;
  • presentation/preview/ — PNG-превью слайдов;
  • __pycache__/, .pytest_cache/ — кэши;
  • presentation/stardew_stylometry.bak — резервная копия;
  • служебные файлы LaTeX (.aux, .log, .nav, .out, .snm, .toc).

Всё это восстанавливается командами из разделов 3–4.

13. Проверка целостности архива

sha256sum -c CHECKSUMS.sha256

MANIFEST.txt содержит список всех файлов архива с размерами и SHA-256. Если контрольные суммы совпали, архив распакован полностью.

Минимальная проверка после распаковки:

cd lab1
python scripts/check_environment.py
python -m pytest -q
python -m stylometry.cli audit

14. Атрибуция

Диалоги Stardew Valley принадлежат ConcernedApe. Корпус используется исключительно в учебных и исследовательских целях. Код проекта можно использовать и изменять для учебных задач.

15. Шпаргалка команд

# из lab1
python scripts/check_environment.py     # проверить окружение
python -m pytest -q                     # 33 теста
python -m stylometry.cli audit          # аудит корпуса
python -m stylometry.cli features       # 454 ручных признака
python -m stylometry.cli run \
    --preset stylometry_pos_lsa --model logreg --repeats 5
bash scripts/run_all_experiments.sh     # полная серия
python scripts/run_final_experiments.py \
    --stages nested topic calibration ensemble extra --out results/final
python scripts/build_report.py          # отчёт DOCX + PDF