post-analysis-toolkit 1.0.1__py3-none-any.whl

post_analysis_toolkit/MDE_METHODOLOGY.md

@@ -0,0 +1,272 @@
+# Методология расчета MDE в пост-анализах
+
+Этот документ фиксирует рабочий стандарт для Minimum Detectable Effect (MDE),
+или минимального обнаруживаемого эффекта, в пост-анализах.
+
+## 1. Что именно измеряет MDE
+
+MDE отвечает на вопрос:
+
+> Какой минимальный истинный эффект при текущем дизайне, размере данных,
+> уровне шума и выбранном методе мы обнаружим с заданной вероятностью?
+
+MDE не является универсальным числом для датасета. Он зависит одновременно от:
+
+- estimand: средней дневной разницы, эффекта в день интервенции, изменения
+  наклона, cumulative effect, ATT/ATE и т.д.;
+- метрики и ее масштаба;
+- предпериода и постпериода;
+- единицы анализа и единицы кластеризации;
+- дисперсии, автокорреляции и пропусков;
+- контрольной группы или donor pool;
+- спецификации модели и преобразования outcome;
+- `alpha`, `power` и типа теста.
+
+Поэтому MDE нужно считать для конкретной спецификации, а не один раз для
+всего пост-анализа.
+
+## 2. Зафиксированные значения по умолчанию
+
+Если пользователь не задал другие значения, используем:
+
+| Параметр | Значение по умолчанию | Смысл |
+|---|---:|---|
+| `alpha` | `0.05` | Допустимая вероятность ошибки первого рода |
+| `power` | `0.80` | Вероятность обнаружить эффект размера MDE |
+| `alternative` | `"two-sided"` | Двусторонняя проверка эффекта |
+| базовый тест | `t-test` | Используется, если метрика и дизайн допускают такую аппроксимацию |
+
+`alpha=0.05` означает 5%-ный уровень значимости, а `power=0.80` означает,
+что эффект размера MDE должен быть обнаружен примерно в 80% повторений при
+истинном наличии такого эффекта.
+
+## 3. Какие формы MDE нужно возвращать
+
+Для основного estimand возвращаем минимум три представления:
+
+1. `MDE absolute` — эффект в единицах исходной метрики. Например, `+12
+   заказов в день` или `+0.004` для доли заказов.
+2. `MDE relative` — абсолютный MDE, деленный на явно указанный baseline. В
+   процентах: `MDE_abs / baseline * 100%`.
+3. `MDE cumulative` — минимальный эффект за весь постпериод. Для additive
+   метрик это сумма дневных эффектов; для rate/ratio метрик нужно явно
+   указать, является ли cumulative estimand суммой числителей, средней
+   разницей или другой агрегированной величиной.
+
+Нельзя молча называть средний дневной MDE cumulative MDE. В результате должны
+быть явно указаны `estimand`, baseline и длина постпериода.
+
+## 4. Аналитический MDE
+
+Если оценка эффекта имеет корректную стандартную ошибку `SE`, базовая формула
+для двустороннего теста имеет вид:
+
+```text
+MDE_abs = (z_(1 - alpha/2) + z_power) * SE(effect)
+```
+
+При `alpha=0.05` и `power=0.80` множитель примерно равен `1.96 + 0.84 =
+2.80`.
+
+Для независимых средних непрерывной метрики:
+
+```text
+SE = SD * sqrt(1 / n_control + 1 / n_treated)
+```
+
+Но в пост-анализе нельзя автоматически использовать обычную формулу для
+независимых наблюдений. Если есть повторные измерения по пиццериям, городам,
+клиентам или дням, в `SE` должны быть учтены соответствующие зависимости:
+
+- cluster-robust SE для кластеризации;
+- HAC/Newey-West SE для временной автокорреляции;
+- design-specific variance для RDD, взвешивания и matching;
+- bootstrap или permutation distribution, если аналитическая дисперсия
+  ненадежна.
+
+Для DiD и DDD аналитический MDE считается для коэффициента interaction. Для
+ITS — отдельно для выбранного estimand уровня/наклона или линейной комбинации
+постпериодных эффектов. Для RDD — для скачка в cutoff при выбранных bandwidth,
+kernel и порядке полинома.
+
+## 5. Когда нужен proxy MDE
+
+`Proxy MDE` — это быстрая приблизительная оценка чувствительности, а не
+полноценный MDE конкретного дизайна. Она появляется, когда у выбранного
+estimand нет надежной стандартной ошибки, которую можно напрямую подставить в
+формулу.
+
+Типичные причины:
+
+- estimand построен как средний gap между фактом и сложным counterfactual;
+- counterfactual получен через Synthetic Control или Causal Impact;
+- модель использует временную зависимость, state-space компоненты или
+  matching;
+- итоговая оценка является нелинейной функцией нескольких шагов;
+- библиотека не предоставляет дисперсию именно для нужного агрегированного
+  estimand;
+- нужна быстрая диагностика до запуска дорогих симуляций.
+
+В текущей версии пакета proxy оценивается через масштаб ошибки прогноза:
+
+```text
+proxy_MDE ~= (z_alpha + z_power) * noise_scale / sqrt(n_post)
+```
+
+где `noise_scale` обычно равен pre-fit RMSE или validation RMSE. Такое число
+полезно как screening-сигнал, но его нельзя интерпретировать как строгий
+power calculation для Synthetic Control, Causal Impact, ITS, PSM или Doubly
+Robust.
+
+## 6. Симуляционный MDE как основной стандарт
+
+Основной режим MDE в пакете — расчет через симуляции. Это относится и к методам, где
+аналитическая формула потенциально существует: симуляция лучше отражает весь
+фактический pipeline и делает результаты сопоставимыми между методами.
+Аналитический MDE остается отдельной опцией для быстрых проверок и моделей, где
+его предпосылки явно выполнены. Общая схема такого расчета:
+
+### 6.1. Как работает текущая реализация
+
+В текущем `mde_mode="parametric"` используется параметрическая симуляция
+распределения оценки эффекта. Для каждой точки сетки эффектов `delta` пакет
+много раз получает случайную оценку: к этому эффекту добавляется случайная
+ошибка с заданным масштабом:
+
+```text
+simulated_estimate = delta + Normal(0, uncertainty_scale)
+```
+
+Где `uncertainty_scale` определяется так:
+
+| Группа методов | Масштаб неопределенности |
+|---|---|
+| DiD, DDD, RDD, PSM, Doubly Robust | Стандартная ошибка оценки эффекта (`SE`) |
+| Event Study | Стандартная ошибка коэффициента соответствующего временного бина (`SE`); MDE считается отдельно по каждому бину |
+| Synthetic Control | `pre-fit RMSE / sqrt(n_post)` |
+| Causal Impact | `validation RMSE / sqrt(n_post)` |
+| ITS | `validation RMSE / sqrt(n_post)` |
+
+Для каждой точки `delta` выполняется `n_simulations` повторов. Затем считается
+доля повторов, для которых нулевая гипотеза отвергнута при заданном `alpha`.
+Эта доля является оценкой мощности для данного `delta`. Power curve сохраняется
+в `result.details["mde_power_curve"]`, а первым значением `delta`, для которого
+мощность достигает `power`, считается MDE.
+
+Параметрическая реализация действительно выполняет симуляции, но не создает
+новые строки исходного датасета и не переобучает модель на каждом draw. В
+частности, она не повторяет заново подбор доноров, matching, оптимизацию весов,
+state-space fit или инженеринг ITS-фичей. Для сложных методов это быстрый
+MDE на основе параметрической симуляции.
+
+В режиме `mde_mode="resampling"` пакет генерирует псевдоданные из
+counterfactual/fitted values без эффекта, добавляет центрированные остатки,
+вставляет кандидатный эффект и заново запускает оцениватель. Поэтому этот режим
+может заново подбирать matching, веса Synthetic Control, state-space модель
+Causal Impact и регрессию ITS. Для методов с нестандартным пользовательским
+pipeline можно передать `mde_simulator` с сигнатурой
+`(effect, rng, n_simulations) -> array[estimate]`.
+
+Точный режим можно воспроизводить через `random_state`. Для более точной сетки
+эффектов используется параметр `mde_effect_grid`.
+
+1. Зафиксировать реальный pre-period, post-period, donor pool/контрольную
+   группу и все параметры метода.
+2. Оценить нулевую модель или counterfactual на предпериоде.
+3. Задать сетку потенциальных истинных эффектов, например `0%`, `5%`, `10%`,
+   `15%`, `20%`.
+4. Для каждого размера эффекта сгенерировать много псевдопостпериодов,
+   добавив эффект к counterfactual по заранее выбранной форме:
+   - постоянный level shift;
+   - изменение slope;
+   - эффект только на часть post-period;
+   - additive или multiplicative effect.
+5. Повторить оценку эффекта и выбранный тест. Если передан method-specific
+   callback, он должен полностью повторять pipeline, включая подбор/фиксацию
+   контроля. В текущем базовом API используется параметрическая симуляция
+   распределения оценки эффекта с SE или ошибкой проверки прогноза как масштабом
+   неопределенности.
+6. Считать долю симуляций, где нулевая гипотеза отвергнута при заданном
+   `alpha`.
+7. MDE — минимальный размер эффекта, для которого эта доля достигает `power`.
+8. Повторить расчет для absolute, relative и cumulative estimands.
+
+Ключевой принцип: симуляция должна повторять весь реальный pipeline. Если в
+боевом анализе donor pool подбирается заново, этот шаг нельзя молча заменить
+фиксированным контролем только ради меньшего времени выполнения.
+
+## 7. Число симуляций
+
+Число симуляций должно быть параметром функции. Рекомендуемый контракт:
+
+| Параметр | Значение по умолчанию | Допустимые режимы |
+|---|---:|---|
+| `mde_mode` | `"auto"` | `"auto"`, `"analytic"`, `"parametric"`, `"resampling"`, `"proxy"`; `"simulation"` — алиас `"parametric"` |
+| `n_simulations` | `2000` | положительное целое; используется в simulation-режиме |
+| `random_state` | `None` | `int` или `None`; seed сохраняется в metadata |
+
+Рекомендуемый стандарт:
+
+| Режим | `n_simulations` | Использование |
+|---|---:|---|
+| быстрый просмотр | `500` | локальная разработка и отладка |
+| рабочий расчет | `2000` | значение по умолчанию для интерактивного анализа |
+| финальный отчет | `5000` или больше | публикация результата и устойчивые оценки мощности |
+
+Если placebo/permutation-пулы маленькие, лучше использовать все допустимые
+перестановки, а не случайно генерировать больше повторов, чем позволяет
+дизайн. Для симуляций обязательно поддерживать `random_state`/`seed` и
+сохранять его в metadata.
+
+## 8. Интервалы неопределенности MDE
+
+Для симуляционного MDE нужно показывать не только точку, но и неопределенность
+из-за конечного числа симуляций. Доля обнаружений является биномиальной
+величиной; для нее следует сохранять число успешных обнаружений, число всех
+симуляций и интервал для estimated power. Границу MDE можно получать:
+
+- интерполяцией по сетке эффектов;
+- бинарным поиском по размеру эффекта при монотонной power curve;
+- с обязательной маркировкой, если power curve немонотонна или сетка слишком
+  редкая.
+
+## 9. Что должно быть в результате API
+
+MDE-блок результата должен содержать:
+
+- `estimand` и его описание;
+- `mde_absolute`, `mde_relative`, `mde_cumulative`;
+- `alpha`, `power`, `alternative`;
+- `method` и полную спецификацию модели;
+- `mde_type`: `analytic`, `simulation`, `proxy`;
+- `mde_simulation_kind`: `parametric_effect_draws` или `residual_bootstrap_pipeline`;
+- `n_simulations`, `random_state` для симуляционного режима;
+- baseline и denominator для relative MDE;
+- длину post-period и правило агрегации cumulative MDE;
+- таблицу power curve;
+- график power curve;
+- ограничения и предупреждения.
+
+## 10. Правила интерпретации
+
+- Если эффект меньше MDE, отсутствие статистической значимости не доказывает
+  отсутствие эффекта.
+- Если MDE больше практически важного эффекта, дизайн недостаточно чувствителен
+  для данного вопроса.
+- Если эффект статистически значим, но меньше заранее важного порога, нужно
+  отдельно обсуждать практическую значимость.
+- Relative MDE нельзя считать без явного baseline.
+- Для ratio/долевых метрик denominator и уровень агрегации должны быть частью
+  estimand, иначе relative/cumulative MDE может быть misleading.
+- Proxy MDE нельзя смешивать с analytic или simulation MDE в одной колонке без
+  поля `mde_type`.
+
+## 11. Статус реализации в пакете
+
+`fit_*`-функции пакета поддерживают `mde_mode="auto"` по умолчанию:
+аналитический расчет выбирается при наличии корректной SE, а для методов без
+аналитической формы используется параметрическая симуляция. Режим
+`mde_mode="parametric"` можно включить явно, а `mde_mode="resampling"` запускает
+повторную генерацию данных и переоценку поддержанного pipeline. Значение
+`mde_mode="simulation"` сохранено для обратной совместимости как алиас
+параметрического режима.