Hierarchical MMM (Flow & Stock) — MVP

Прототип системы прогнозирования лидов и поддержки решений по рекламному бюджету с разделением каналов на два типа:

• Flow — быстрые каналы (контекст/диджитал), эффект почти мгновенный, возможен короткий “хвост”.
• Stock — “долгие” каналы (например, брендированные автомобили), где эффект создаётся активными рекламными юнитами и имеет стохастическую природу.

Проект делает упор на:

• интерпретируемость,
• робастность,
• консервативные оценки снизу (для принятия решений),
• вероятностные коридоры неопределённости (для Stock).

---

Идея модели

1) Flow-каналы (быстрые)

Моделируем зависимость лидов от расходов с насыщением:

R(x) = a · ln(1 + b · E(x))

Где:

• x — расходы за неделю,
• E(x) — “эффективный бюджет” с учётом adstock (хвоста прошлых недель),
• a, b — параметры насыщения,
• λ (lambda) — коэффициент хвоста (подбирается по сетке).

Дополнительно строятся:

• средняя кривая,
• консервативная нижняя оценка (по точкам ниже средней),
• верхняя оценка (по точкам выше средней) — как “оптимистичный коридор”.

---

2) Stock-каналы (долгие)

Каждый рекламный юнит (машина) моделируется как случайная величина “касания” (контакты). Сумма по большому числу юнитов → применима ЦПТ (центральная предельная теорема).

• S — число активных рекламных юнитов (машин)
• X — суммарные касания за неделю (скрытая величина)
• X|S ≈ Normal(S·μ, S·σ²)

Далее лиды получаются через логарифмическую конверсию:

Y = a · ln(1 + b · X)

Из этого строятся:

• средняя кривая (матожидание),
• вероятностные коридоры ±1σ, ±2σ, ±3σ (68.27%, 95.45%, 99.73%).

Важно:

• μ фиксируется (нормировка масштаба), т.к. без наблюдения X параметр масштаба неидентифицируем;
• σ калибруется по росту разброса с увеличением S через дельта-метод.

---

Пайплайн (коротко)

1. Загрузка датасета по имени (из папки data/)
2. Сборка контекста (общий weekly DataFrame)
3. Расчёт сезонного коэффициента и очистка лидов от сезонности
4. Fit Flow моделей (подбор λ, a, b и нижних/верхних кривых)
5. Fit Stock моделей (CLT-модель + 1/2/3σ интервалы)
6. Построение графиков и вывод параметров в консоль

---

Структура проекта (ожидаемая)

• main.py — простой консольный интерфейс (без параметров командной строки)
• core/ — ядро (preprocessing, context_builder, seasonality, fit_* модели)
• pipelines/ — сценарии запуска (например, forecast_channel)
• data/ — датасеты (каждый датасет отдельной папкой)
• outputs/ — картинки и результаты

---

Запуск (через main.py)

1. Установите Python (см. требования ниже)

2. Установите зависимости:

   pip install -r requirements.txt

3. Запустите приложение:

   python main.py

Далее появится простой интерактивный режим:

• выбрать датасет из папки data/
• выбрать пайплайн (например, forecast_channel)
• получить в консоли параметры и на диске — графики (outputs/)

---

Требования

• Python: 3.9+ (рекомендуется 3.10)
• Зависимости — в requirements.txt

---

Ограничения (честно)

Это MVP-прототип. На маленьких датасетах (20–40 недель) возможны:

• нестабильные интервалы,
• слабая статистическая сила в хвостах,
• упрощённая сезонность.

В обмен получаем:

• интерпретируемость,
• отсутствие утечек по времени,
• робастность и консервативность.

---

Лицензия

MIT