diff --git a/README.md b/README.md index ec1fd74..129492c 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,121 @@ -# FinalTry.exe — исследование коммуникаций (2025/2026) +# DANO 2025/2026 — исследование FinalTry.exe -## 1. Описание проекта -- Исследовательский репозиторий команды FinalTry.exe. -- Задача: изучить связь между коммуникациями пользователей и их заказами, проверить гипотезы о форме зависимости (тренды, квадратика), посмотреть по категориям. -- Результат: собранная SQLite-база, набор статичных и интерактивных графиков, сравнения по категориям/total. +Аналитический проект команды FinalTry.exe: исследуем связь пользовательских коммуникаций и заказов, проверяем форму зависимости (тренд, квадратичная регрессия) по общим и категорийным метрикам. Данные лежат в `dataset/ds.csv`, итог — собранная SQLite, статичные PNG и интерактивные HTML-графики. -## 2. Структура репозитория -- `dataset/` — исходный CSV (`ds.csv`) и собранный SQLite (`ds.sqlite`, таблица `communications`). -- `migrations/` + `migrate.py` — пошаговая сборка данных: CSV → SQLite, правка значений заказов. -- `preanalysis/` — утилиты EDA (нормализация, агрегаты по дням и клиентам). -- `main_hypot/` — основной пайплайн: подготовка клиентских фичей, облака, тренды, квадратичные регрессии, интерактивные графики. -- `new_divided_scatters.py` — интерактивные облака для активных/пассивных/общих показов. -- `old_data/` — архивный подвал с ранними скриптами/данными; не входит в основной пайплайн, оставлен для истории и воспроизводимости. +## Table of Contents +- [Quickstart](#quickstart) +- [Repository Tree](#repository-tree) +- [Repository Structure Explained](#repository-structure-explained) +- [Reproduce the Analysis](#reproduce-the-analysis) +- [Methodology](#methodology) +- [Hypotheses](#hypotheses) +- [Results and Takeaways](#results-and-takeaways) +- [FAQ (for the jury)](#faq-for-the-jury) +- [Notes](#notes) -## 3. Подготовка данных +## Quickstart ```bash -# 1) положите исходник -dataset/ds.csv +# 1) создать окружение +python -m venv .venv +source .venv/bin/activate # win: .venv\Scripts\activate -# 2) соберите SQLite -python migrate.py -# или вручную: -python migrations/0001_csv_to_sqlite.py -python migrations/0002_cap_orders_to_one.py +# 2) установить зависимости +pip install pandas numpy scipy statsmodels scikit-learn matplotlib seaborn altair vl-convert-python +# альтернатива для Altair: pip install altair_saver && установка node + +# 3) подготовить данные +cp dataset/ds.csv +python migrate.py # соберёт dataset/ds.sqlite + +# 4) запустить ключевые скрипты +python main_hypot/best_model_and_plots.py # базовые облака/тренды (PNG) +python main_hypot/quadreg.py # общая квадратика (PNG) +python main_hypot/category_quadreg.py # категории: корреляции + квадратика (PNG) +python main_hypot/new_plots.py # интерактивные HTML-графики +python new_divided_scatters.py # интерактив: активные/пассивные/общие ``` -Итог: `dataset/ds.sqlite` с таблицей `communications`. -## 4. Установка зависимостей -Обязательные пакеты: -- pandas -- numpy -- scipy -- statsmodels -- scikit-learn -- matplotlib -- seaborn -- altair -- vl-convert-python *(для сохранения Altair в HTML; альтернатива — `altair_saver` + установленный node)* +## Repository Tree +``` +. +├── dataset/ # вход: ds.csv; выход: ds.sqlite +├── migrations/ # шаги подготовки данных (0001, 0002) +├── migrate.py # исполнитель миграций +├── preanalysis/ # EDA-утилиты (нормализация, агрегаты) +├── main_hypot/ # основной пайплайн графиков/регрессий +│ ├── best_model_and_plots.py +│ ├── category_quadreg.py +│ ├── quadreg.py +│ └── new_plots.py +├── new_divided_scatters.py # интерактивные облака по типам показов +├── old_data/ # архив ранних скриптов/данных (не в основном пайплайне) +└── README.md +``` -## 5. Запуск и работа -- Миграции: - ```bash - python migrate.py # прогнать все шаги - python migrate.py --list # посмотреть статус - ``` -- Базовые облака и тренды (PNG): - ```bash - python main_hypot/best_model_and_plots.py - ``` - Результаты: `main_hypot/orders_amt_total/`. -- Общая квадратичная регрессия (PNG): - ```bash - python main_hypot/quadreg.py - ``` - Результаты: `main_hypot/orders_amt_total/`. -- Категорийные корреляции и квадратика (PNG): - ```bash - python main_hypot/category_quadreg.py - ``` - Результаты: `main_hypot/category_analysis/`. -- Интерактивные графики Altair (HTML): - ```bash - python main_hypot/new_plots.py - python new_divided_scatters.py - ``` - Результаты: `main_hypot/new_plots/` и `new_plots/final_result/`. +## Repository Structure Explained (folder + file guide) +- `dataset/` + - `ds.csv` — входной CSV (кладёте сами). + - `ds.sqlite` — результат миграций, таблица `communications`, источник для всех скриптов. +- `migrations/` + - `0001_csv_to_sqlite.py` — читает CSV чанками, нормализует дату, пишет таблицу, создаёт индексы. + - `0002_cap_orders_to_one.py` — каппинг заказов: все значения >1 приводятся к 1 по дневным категориям. +- `migrate.py` — менеджер миграций (`--list`, `--force`, настраиваемые пути); обновляет `migrations_state.json`. +- `preanalysis/` + - `eda_utils.py` — нормализация пола/платформы, возрастные группы, суммарные метрики, флаги, агрегации по дням и клиентам. +- `main_hypot/` + - `best_model_and_plots.py` — загрузка клиентов из SQLite, фильтр выбросов, тренды LOWESS/Savitzky–Golay, плотностные облака; PNG в `main_hypot/orders_amt_total/`. + - `quadreg.py` — накладывает квадратичную регрессию на общий график заказов; вывод в ту же папку. + - `category_quadreg.py` — агрегации по категориям/комбо, корреляции и квадратичные регрессии; PNG в `main_hypot/category_analysis/`. + - `new_plots.py` — интерактивные Altair-графики (total + категории); HTML в `main_hypot/new_plots/`. +- `new_divided_scatters.py` — интерактивные облака активных/пассивных/общих показов; HTML в `new_plots/final_result/`. +- `old_data/` — архив ранних скриптов/данных, не участвует в текущем пайплайне. -## 6. Примечания -- Все скрипты опираются на структуру `dataset/ds.sqlite`; без миграций данные не загрузятся. -- Если в `ds.csv` нет ожидаемых колонок или файл пустой, миграции упадут. -- Altair требует `vl-convert-python` (или node + altair_saver) для `Chart.save`. -- Савицкий–Голай окна по умолчанию большие (≈501); на малых выборках стоит снижать окно, иначе будет ошибка. -- Проект исследовательский: код может быть не оптимизирован под продакшн, а `old_data/` — лишь исторический архив. +## Reproduce the Analysis +1) **Подготовить данные:** положить `dataset/ds.csv`. +2) **Собрать SQLite:** `python migrate.py` (или вручную 0001 → 0002). Итог: `dataset/ds.sqlite`. +3) **Базовые графики:** `python main_hypot/best_model_and_plots.py` → PNG в `main_hypot/orders_amt_total/`. +4) **Общая квадратика:** `python main_hypot/quadreg.py` → PNG в `main_hypot/orders_amt_total/`. +5) **Категории:** `python main_hypot/category_quadreg.py` → PNG/корреляции в `main_hypot/category_analysis/`. +6) **Интерактив:** + - `python main_hypot/new_plots.py` → HTML в `main_hypot/new_plots/`; + - `python new_divided_scatters.py` → HTML в `new_plots/final_result/`. +Все скрипты читают `dataset/ds.sqlite`; без него упадут. + +## Methodology +- **Модели/метрики:** AUC для вероятности заказа, R² по тренду, p-value и коэффициенты b1/b2 квадратичной регрессии `y ~ 1 + x + x²`. +- **Тренды:** сглаживание LOWESS или Savitzky–Golay для выявления формы зависимости. +- **Квадратичная форма:** базовый способ поймать нелинейность и насыщение/спад заказов при росте показов. +- **Очистка:** фильтрация выбросов по IQR и ограничение диапазонов осей. + +## Hypotheses +- **H0:** заказы не зависят от среднего числа показов. +- **H1:** больше показов → больше заказов (монотонный рост). +- **H_add:** для некоторых категорий (например, avia/hotel) при высоких показах эффект насыщается или разворачивается вниз (негативный b2). +Проверка: визуальные тренды, квадратичная регрессия, AUC/R² и значимость коэффициентов. + +## Results and Takeaways +- Пайплайн выдаёт: очищенные облака, трендовые линии, квадратичные кривые и метрики AUC/R²/p-values. +- Для total и категорий видны зоны насыщения/редкого спроса, что помогает подобрать лимиты показов. +- Комбинации категорий (например, avia+hotel) позволяют увидеть перекрёстный спрос. +- Плотностные альфы показывают концентрации клиентов и помогают читать облака без шума. +- Корреляционные матрицы подсвечивают связки «показы → клики → заказы» внутри категорий. +Бизнес-применение: +1) Тестировать потолки показов в сегментах с убывающей отдачей. +2) Приоритизировать категории с устойчивым положительным b1/b2. +3) Для насыщенных категорий использовать частоту/каппинг или смену креативов. +4) Отдельно мониторить avia/hotel-комбинации для выявления сезонности/пересечений спроса. +5) Использовать AUC для оценки пригодности скорингов/сегментов на заказ. + +## FAQ (for the jury) +- **Что такое корреляция?** Мера линейной связи (-1…1) между двумя величинами. +- **Почему корреляция ≠ причинность?** Связь может быть опосредована или вызвана третьим фактором; нужны эксперименты/каузальные методы. +- **Что означает AUC?** Площадь под ROC-кривой: шанс, что модель верно ранжирует случайную пару (позитив/негатив). +- **Что означает R²?** Доля объяснённой вариации целевой величины моделью. +- **Почему binarize orders (0/1)?** Для расчёта AUC по факту наличия заказа, независимо от суммы. +- **Ограничения исследования?** Зависимость от структуры `ds.csv`, чувствительность Savitzky–Golay к размеру выборки, отсутствуют продакшн-оптимизации. +- **Чем отличается avia+hotel?** Комбинированная категория для ловли перекрёстного спроса; может показывать насыщение или иной профиль b2. + +## Notes +- Altair сохранение требует `vl-convert-python` или `altair_saver` + node. +- Savitzky–Golay окно по умолчанию большое (~501); на малых выборках уменьшайте, иначе будет ошибка. +- `old_data/` — архив, не трогает основной пайплайн.