Обновить README.md

README.md

@@ -1,74 +1,115 @@
-# 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)
+- [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
-```
-Итог: `dataset/ds.sqlite` с таблицей `communications`.
+# 2) установить зависимости
+pip install pandas numpy scipy statsmodels scikit-learn matplotlib seaborn altair vl-convert-python
+# альтернатива для Altair: pip install altair_saver && установка node
 
-## 4. Установка зависимостей
-Обязательные пакеты:
-- pandas
-- numpy
-- scipy
-- statsmodels
-- scikit-learn
-- matplotlib
-- seaborn
-- altair
-- vl-convert-python  *(для сохранения Altair в HTML; альтернатива — `altair_saver` + установленный node)*
+# 3) подготовить данные
+cp <your-ds.csv> dataset/ds.csv
+python migrate.py  # соберёт dataset/ds.sqlite
 
-## 5. Запуск и работа
-- Миграции:  
-  ```bash
-  python migrate.py          # прогнать все шаги
-  python migrate.py --list   # посмотреть статус
+# 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              # интерактив: активные/пассивные/общие
 ```
-- Базовые облака и тренды (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/`.
 
-## 6. Примечания
-- Все скрипты опираются на структуру `dataset/ds.sqlite`; без миграций данные не загрузятся.
-- Если в `ds.csv` нет ожидаемых колонок или файл пустой, миграции упадут.
-- Altair требует `vl-convert-python` (или node + altair_saver) для `Chart.save`.
-- Савицкий–Голай окна по умолчанию большие (≈501); на малых выборках стоит снижать окно, иначе будет ошибка.
-- Проект исследовательский: код может быть не оптимизирован под продакшн, а `old_data/` — лишь исторический архив.
+## 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
+```
+
+## 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/` — архив ранних скриптов/данных, не участвует в текущем пайплайне.
+
+## 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 и ограничение диапазонов осей.
+
+
+## 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/` — архив, не трогает основной пайплайн.