Обновить README.md

2025-12-16 02:33:22 +03:00 · 2025-12-16 02:32:18 +03:00
1 changed files with 106 additions and 65 deletions
--- a/README.md
+++ b/README.md
@@ -1,74 +1,115 @@
-# FinalTry.exe — исследование коммуникаций (2025/2026)
+# DANO 2025/2026 — исследование FinalTry.exe
-## 1. Описание проекта
+Аналитический проект команды FinalTry.exe: исследуем связь пользовательских коммуникаций и заказов, проверяем форму зависимости (тренд, квадратичная регрессия) по общим и категорийным метрикам. Данные лежат в `dataset/ds.csv`, итог — собранная SQLite, статичные PNG и интерактивные HTML-графики.
 - Исследовательский репозиторий команды FinalTry.exe.
 - Задача: изучить связь между коммуникациями пользователей и их заказами, проверить гипотезы о форме зависимости (тренды, квадратика), посмотреть по категориям.
 - Результат: собранная SQLite-база, набор статичных и интерактивных графиков, сравнения по категориям/total.
-## 2. Структура репозитория
+## Table of Contents
- `dataset/` — исходный CSV (`ds.csv`) и собранный SQLite (`ds.sqlite`, таблица `communications`).
+- [Quickstart](#quickstart)
- `migrations/` + `migrate.py` — пошаговая сборка данных: CSV → SQLite, правка значений заказов.
+- [Repository Tree](#repository-tree)
- `preanalysis/` — утилиты EDA (нормализация, агрегаты по дням и клиентам).
+- [Repository Structure Explained](#repository-structure-explained)
- `main_hypot/` — основной пайплайн: подготовка клиентских фичей, облака, тренды, квадратичные регрессии, интерактивные графики.
+- [Reproduce the Analysis](#reproduce-the-analysis)
- `new_divided_scatters.py` — интерактивные облака для активных/пассивных/общих показов.
+- [Methodology](#methodology)
- `old_data/` — архивный подвал с ранними скриптами/данными; не входит в основной пайплайн, оставлен для истории и воспроизводимости.
+- [Results and Takeaways](#results-and-takeaways)
 - [FAQ (for the jury)](#faq-for-the-jury)
 - [Notes](#notes)
-## 3. Подготовка данных
+## Quickstart
 ```bash
-# 1) положите исходник
+# 1) создать окружение
-dataset/ds.csv
+python -m venv .venv
 source .venv/bin/activate  # win: .venv\Scripts\activate
-# 2) соберите SQLite
+# 2) установить зависимости
-python migrate.py
+pip install pandas numpy scipy statsmodels scikit-learn matplotlib seaborn altair vl-convert-python
-# или вручную:
+# альтернатива для Altair: pip install altair_saver && установка node
-python migrations/0001_csv_to_sqlite.py
+
-python migrations/0002_cap_orders_to_one.py
+# 3) подготовить данные
 cp <your-ds.csv> 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. Установка зависимостей
+## Repository Tree
-Обязательные пакеты:
+```
- pandas
+.
- numpy
+├── dataset/                # вход: ds.csv; выход: ds.sqlite
- scipy
+├── migrations/             # шаги подготовки данных (0001, 0002)
- statsmodels
+├── migrate.py              # исполнитель миграций
- scikit-learn
+├── preanalysis/            # EDA-утилиты (нормализация, агрегаты)
- matplotlib
+├── main_hypot/             # основной пайплайн графиков/регрессий
- seaborn
+│   ├── best_model_and_plots.py
- altair
+│   ├── category_quadreg.py
- vl-convert-python  *(для сохранения Altair в HTML; альтернатива — `altair_saver` + установленный node)*
+│   ├── quadreg.py
 │   └── new_plots.py
 ├── new_divided_scatters.py # интерактивные облака по типам показов
 ├── old_data/               # архив ранних скриптов/данных (не в основном пайплайне)
 └── README.md
 ```
-## 5. Запуск и работа
+## Repository Structure Explained (folder + file guide)
- Миграции:  
+- `dataset/`
-  ```bash
+  - `ds.csv` — входной CSV (кладёте сами).
-  python migrate.py          # прогнать все шаги
+  - `ds.sqlite` — результат миграций, таблица `communications`, источник для всех скриптов.
-  python migrate.py --list   # посмотреть статус
+- `migrations/`
-  ```
+  - `0001_csv_to_sqlite.py` — читает CSV чанками, нормализует дату, пишет таблицу, создаёт индексы.
- Базовые облака и тренды (PNG):  
+  - `0002_cap_orders_to_one.py` — каппинг заказов: все значения >1 приводятся к 1 по дневным категориям.
-  ```bash
+- `migrate.py` — менеджер миграций (`--list`, `--force`, настраиваемые пути); обновляет `migrations_state.json`.
-  python main_hypot/best_model_and_plots.py
+- `preanalysis/`
-  ```  
+  - `eda_utils.py` — нормализация пола/платформы, возрастные группы, суммарные метрики, флаги, агрегации по дням и клиентам.
-  Результаты: `main_hypot/orders_amt_total/`.
+- `main_hypot/`
- Общая квадратичная регрессия (PNG):  
+  - `best_model_and_plots.py` — загрузка клиентов из SQLite, фильтр выбросов, тренды LOWESS/Savitzky–Golay, плотностные облака; PNG в `main_hypot/orders_amt_total/`.
-  ```bash
+  - `quadreg.py` — накладывает квадратичную регрессию на общий график заказов; вывод в ту же папку.
-  python main_hypot/quadreg.py
+  - `category_quadreg.py` — агрегации по категориям/комбо, корреляции и квадратичные регрессии; PNG в `main_hypot/category_analysis/`.
-  ```  
+  - `new_plots.py` — интерактивные Altair-графики (total + категории); HTML в `main_hypot/new_plots/`.
-  Результаты: `main_hypot/orders_amt_total/`.
+- `new_divided_scatters.py` — интерактивные облака активных/пассивных/общих показов; HTML в `new_plots/final_result/`.
- Категорийные корреляции и квадратика (PNG):  
+- `old_data/` — архив ранних скриптов/данных, не участвует в текущем пайплайне.
  ```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. Примечания
+## Reproduce the Analysis
- Все скрипты опираются на структуру `dataset/ds.sqlite`; без миграций данные не загрузятся.
+1) **Подготовить данные:** положить `dataset/ds.csv`.  
- Если в `ds.csv` нет ожидаемых колонок или файл пустой, миграции упадут.
+2) **Собрать SQLite:** `python migrate.py` (или вручную 0001 → 0002). Итог: `dataset/ds.sqlite`.  
- Altair требует `vl-convert-python` (или node + altair_saver) для `Chart.save`.
+3) **Базовые графики:** `python main_hypot/best_model_and_plots.py` → PNG в `main_hypot/orders_amt_total/`.  
- Савицкий–Голай окна по умолчанию большие (≈501); на малых выборках стоит снижать окно, иначе будет ошибка.
+4) **Общая квадратика:** `python main_hypot/quadreg.py` → PNG в `main_hypot/orders_amt_total/`.  
- Проект исследовательский: код может быть не оптимизирован под продакшн, а `old_data/` — лишь исторический архив.
+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/` — архив, не трогает основной пайплайн.
Author	SHA1	Message	Date
ivanberat	b52fc42eb8	Обновить README.md	2025-12-16 02:33:22 +03:00
ivanberat	cc9aae7425	Обновить README.md	2025-12-16 02:32:18 +03:00