post-analysis-toolkit 1.0.8__tar.gz → 1.0.9__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {post_analysis_toolkit-1.0.8/post_analysis_toolkit.egg-info → post_analysis_toolkit-1.0.9}/PKG-INFO +15 -7
  2. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/MDE_METHODOLOGY.md +11 -9
  3. post_analysis_toolkit-1.0.8/PKG-INFO → post_analysis_toolkit-1.0.9/post_analysis_toolkit/README.md +14 -27
  4. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/REFERENCE.html +8 -7
  5. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/REFERENCE.md +17 -5
  6. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/__init__.py +1 -1
  7. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/synthetic_did.py +80 -1
  8. post_analysis_toolkit-1.0.8/post_analysis_toolkit/README.md → post_analysis_toolkit-1.0.9/post_analysis_toolkit.egg-info/PKG-INFO +35 -6
  9. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/pyproject.toml +1 -1
  10. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/MANIFEST.in +0 -0
  11. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/README.md +0 -0
  12. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/notebooks/did_its_template.ipynb +0 -0
  13. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/notebooks/synthetic_did_databricks_template.ipynb +0 -0
  14. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/causal_impact.py +0 -0
  15. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/compat.py +0 -0
  16. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/contracts.py +0 -0
  17. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/demo.py +0 -0
  18. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/did.py +0 -0
  19. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/its.py +0 -0
  20. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/mde.py +0 -0
  21. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/mde_resampling.py +0 -0
  22. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/observational.py +0 -0
  23. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/rdd.py +0 -0
  24. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/synthetic_control.py +0 -0
  25. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/triple_difference.py +0 -0
  26. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/utils.py +0 -0
  27. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/visualization.py +0 -0
  28. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/SOURCES.txt +0 -0
  29. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/dependency_links.txt +0 -0
  30. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/requires.txt +0 -0
  31. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/top_level.txt +0 -0
  32. {post_analysis_toolkit-1.0.8 → post_analysis_toolkit-1.0.9}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: post-analysis-toolkit
3
- Version: 1.0.8
3
+ Version: 1.0.9
4
4
  Summary: Reusable helpers for post-analysis, quasi-causal designs, and diagnostics.
5
5
  Author: OpenAI Codex
6
6
  Requires-Python: >=3.11
@@ -150,16 +150,17 @@ MDE относится к конкретному estimand и специфика
150
150
  генерирует оценки по схеме `delta + Normal(0, uncertainty_scale)`. Для
151
151
  регрессионных и observational-методов `uncertainty_scale` — SE. Для Event Study
152
152
  это SE конкретного коэффициента конкретного временного бина, поэтому MDE
153
- считается отдельно для каждого бина. Для
154
- Synthetic Control/Causal Impact/ITS — pre-fit или validation RMSE,
155
- нормированный на размер post-period.
153
+ считается отдельно для каждого бина. Для Synthetic Control и Causal Impact
154
+ используется pre-fit или validation RMSE, нормированный на размер post-period;
155
+ для ITS при доступной covariance matrix используется delta-method SE среднего
156
+ post-period gap, а validation RMSE остаётся fallback.
156
157
 
157
158
  В режиме `resampling` пакет создает псевдоданные: берет fitted/counterfactual
158
159
  значения без эффекта, добавляет ресэмплированные центрированные остатки и
159
160
  кандидатный эффект, а затем повторно запускает весь поддержанный оцениватель.
160
161
  Для Synthetic Control заново подбираются веса, для PSM заново строится matching,
161
- для Causal Impact заново обучается state-space модель, а для ITS заново
162
- оценивается регрессия. Такой режим заметно медленнее и требует явно задать
162
+ для Causal Impact заново обучается state-space модель, для ITS заново
163
+ оценивается регрессия, а для SDiD заново подбираются unit/time-веса. Такой режим заметно медленнее и требует явно задать
163
164
  разумное `n_simulations` и, при необходимости, `mde_effect_grid`.
164
165
 
165
166
  Power curve можно посмотреть в
@@ -1064,6 +1065,11 @@ display(sdid_result.figures["actual_vs_counterfactual"])
1064
1065
  `effect_ci`, `effect_relative_ci`, `effect_cumulative_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
1065
1066
  `mde_cumulative`, `mde_mode_resolved`.
1066
1067
 
1068
+ Для SDiD доступны `mde_mode="analytic"`, `"parametric"`, `"resampling"` и
1069
+ `"proxy"`. В `resampling` можно передать `mde_simulator`; если он не задан,
1070
+ пакет автоматически строит residual-bootstrap pipeline и повторно вызывает
1071
+ `diff-diff` для каждой симулированной панели.
1072
+
1067
1073
  В `details["unit_weights"]` и `details["time_weights"]` доступны полные
1068
1074
  списки весов. В `details["weight_concentration"]` пакет дополнительно
1069
1075
  показывает min/max, эффективное число доноров и pre-периодов, общее число
@@ -1083,7 +1089,9 @@ level-shift-adjusted `counterfactual_level_adjusted`/`gap_level_adjusted`.
1083
1089
  SDiD-формула дизайн-мощности: unit/time weights оцениваются на исходных
1084
1090
  данных, а MDE использует итоговую inferential SE. `parametric` делает быстрые
1085
1091
  симуляции оценок с той же SE, `proxy` использует level-shift-adjusted pre-fit
1086
- RMSE. Полный `resampling` MDE через повторную переоценку SDiD пока не включён.
1092
+ RMSE. `resampling` строит псевдопанели, добавляет эффект к treated-юнитам в
1093
+ post-периоде и заново оценивает SDiD вместе с unit/time-весами на каждом
1094
+ прогоне; это точнее, но существенно медленнее.
1087
1095
 
1088
1096
  `effect_ci` — доверительный интервал взвешенного ATT от `diff-diff`.
1089
1097
  `effect_relative_ci` и `effect_cumulative_ci` — plug-in преобразования этого
@@ -160,9 +160,9 @@ simulated_estimate = delta + Normal(0, uncertainty_scale)
160
160
  | DiD, DDD, RDD, PSM, Doubly Robust | Стандартная ошибка оценки эффекта (`SE`) |
161
161
  | Event Study | Стандартная ошибка коэффициента соответствующего временного бина (`SE`); MDE считается отдельно по каждому бину |
162
162
  | Synthetic Control | `pre-fit RMSE / sqrt(n_post)` |
163
- | Synthetic DiD | Plug-in analytic MDE или параметрические draws с масштабом inferential `SE`, предоставленной `diff-diff`; `proxy` использует level-shift-adjusted pre-fit RMSE |
163
+ | Synthetic DiD | Plug-in analytic MDE или параметрические draws с масштабом inferential `SE`, предоставленной `diff-diff`; `proxy` использует level-shift-adjusted pre-fit RMSE; `resampling` заново переоценивает SDiD на псевдопанелях |
164
164
  | Causal Impact | `validation RMSE / sqrt(n_post)` |
165
- | ITS | `validation RMSE / sqrt(n_post)` |
165
+ | ITS | Delta-method SE среднего post-period gap; при недоступной SE — `validation RMSE / sqrt(n_post)` |
166
166
 
167
167
  Для каждой точки `delta` выполняется `n_simulations` повторов. Затем считается
168
168
  доля повторов, для которых нулевая гипотеза отвергнута при заданном `alpha`.
@@ -180,9 +180,9 @@ MDE на основе параметрической симуляции.
180
180
  counterfactual/fitted values без эффекта, добавляет центрированные остатки,
181
181
  вставляет кандидатный эффект и заново запускает оцениватель. Поэтому этот режим
182
182
  может заново подбирать matching, веса Synthetic Control, state-space модель
183
- Causal Impact и регрессию ITS. Для методов с нестандартным пользовательским
184
- pipeline можно передать `mde_simulator` с сигнатурой
185
- `(effect, rng, n_simulations) -> array[estimate]`.
183
+ Causal Impact, регрессию ITS и unit/time-веса Synthetic DiD. Для методов с
184
+ нестандартным пользовательским pipeline можно передать `mde_simulator` с
185
+ сигнатурой `(effect, rng, n_simulations) -> array[estimate]`.
186
186
 
187
187
  Точный режим можно воспроизводить через `random_state`. Для более точной сетки
188
188
  эффектов используется параметр `mde_effect_grid`.
@@ -285,12 +285,14 @@ MDE-блок результата должен содержать:
285
285
  аналитической формы используется параметрическая симуляция. Режим
286
286
  `mde_mode="parametric"` можно включить явно, а `mde_mode="resampling"` запускает
287
287
  повторную генерацию данных и переоценку поддержанного pipeline. Значение
288
- `mde_mode="resampling"` для Synthetic DiD пока не реализует повторный вызов
289
- `diff-diff`; для SDiD доступны analytic plug-in, parametric и proxy-режимы.
288
+ Для Synthetic DiD `mde_mode="resampling"` также повторно вызывает
289
+ `diff-diff` и переоценивает unit/time-веса на каждой симулированной панели;
290
+ для SDiD доступны analytic plug-in, parametric, resampling и proxy-режимы.
290
291
 
291
292
  Для SDiD аналитический режим не означает наличие отдельной закрытой формулы
292
293
  дизайн-мощности Synthetic DiD. Unit- и time-веса сначала оцениваются на
293
294
  исходной панели, затем итоговая SE ATT от `diff-diff` подставляется в общую
294
295
  формулу `MDE = critical value × SE`. Это корректный быстрый plug-in расчёт при
295
- условии, что выбранный `variance_method` даёт осмысленную SE, но он не учитывает
296
- дополнительную неопределённость повторного подбора весов.
296
+ условии, что выбранный `variance_method` даёт осмысленную SE, но не учитывает
297
+ дополнительную неопределённость повторного подбора весов. Если нужна эта
298
+ неопределённость, используйте `mde_mode="resampling"`.
@@ -1,24 +1,3 @@
1
- Metadata-Version: 2.4
2
- Name: post-analysis-toolkit
3
- Version: 1.0.8
4
- Summary: Reusable helpers for post-analysis, quasi-causal designs, and diagnostics.
5
- Author: OpenAI Codex
6
- Requires-Python: >=3.11
7
- Description-Content-Type: text/markdown
8
- Requires-Dist: numpy>=2.4
9
- Requires-Dist: pandas<3,>=2.3
10
- Requires-Dist: scipy>=1.17
11
- Requires-Dist: statsmodels>=0.14
12
- Requires-Dist: scikit-learn>=1.9
13
- Requires-Dist: matplotlib>=3.11
14
- Requires-Dist: seaborn>=0.13
15
- Requires-Dist: causalimpact>=0.2.6
16
- Requires-Dist: diff-diff<4,>=3.11
17
- Provides-Extra: dev
18
- Requires-Dist: build>=1.2; extra == "dev"
19
- Requires-Dist: pytest>=9.1; extra == "dev"
20
- Requires-Dist: twine>=6.1; extra == "dev"
21
-
22
1
  # Post Analysis Toolkit
23
2
 
24
3
  `post_analysis_toolkit` - локальная библиотека для пост-анализа промо, rollout-ов и других квази-экспериментальных задач, где нужен воспроизводимый causal / quasi-causal пайплайн.
@@ -150,16 +129,17 @@ MDE относится к конкретному estimand и специфика
150
129
  генерирует оценки по схеме `delta + Normal(0, uncertainty_scale)`. Для
151
130
  регрессионных и observational-методов `uncertainty_scale` — SE. Для Event Study
152
131
  это SE конкретного коэффициента конкретного временного бина, поэтому MDE
153
- считается отдельно для каждого бина. Для
154
- Synthetic Control/Causal Impact/ITS — pre-fit или validation RMSE,
155
- нормированный на размер post-period.
132
+ считается отдельно для каждого бина. Для Synthetic Control и Causal Impact
133
+ используется pre-fit или validation RMSE, нормированный на размер post-period;
134
+ для ITS при доступной covariance matrix используется delta-method SE среднего
135
+ post-period gap, а validation RMSE остаётся fallback.
156
136
 
157
137
  В режиме `resampling` пакет создает псевдоданные: берет fitted/counterfactual
158
138
  значения без эффекта, добавляет ресэмплированные центрированные остатки и
159
139
  кандидатный эффект, а затем повторно запускает весь поддержанный оцениватель.
160
140
  Для Synthetic Control заново подбираются веса, для PSM заново строится matching,
161
- для Causal Impact заново обучается state-space модель, а для ITS заново
162
- оценивается регрессия. Такой режим заметно медленнее и требует явно задать
141
+ для Causal Impact заново обучается state-space модель, для ITS заново
142
+ оценивается регрессия, а для SDiD заново подбираются unit/time-веса. Такой режим заметно медленнее и требует явно задать
163
143
  разумное `n_simulations` и, при необходимости, `mde_effect_grid`.
164
144
 
165
145
  Power curve можно посмотреть в
@@ -1064,6 +1044,11 @@ display(sdid_result.figures["actual_vs_counterfactual"])
1064
1044
  `effect_ci`, `effect_relative_ci`, `effect_cumulative_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
1065
1045
  `mde_cumulative`, `mde_mode_resolved`.
1066
1046
 
1047
+ Для SDiD доступны `mde_mode="analytic"`, `"parametric"`, `"resampling"` и
1048
+ `"proxy"`. В `resampling` можно передать `mde_simulator`; если он не задан,
1049
+ пакет автоматически строит residual-bootstrap pipeline и повторно вызывает
1050
+ `diff-diff` для каждой симулированной панели.
1051
+
1067
1052
  В `details["unit_weights"]` и `details["time_weights"]` доступны полные
1068
1053
  списки весов. В `details["weight_concentration"]` пакет дополнительно
1069
1054
  показывает min/max, эффективное число доноров и pre-периодов, общее число
@@ -1083,7 +1068,9 @@ level-shift-adjusted `counterfactual_level_adjusted`/`gap_level_adjusted`.
1083
1068
  SDiD-формула дизайн-мощности: unit/time weights оцениваются на исходных
1084
1069
  данных, а MDE использует итоговую inferential SE. `parametric` делает быстрые
1085
1070
  симуляции оценок с той же SE, `proxy` использует level-shift-adjusted pre-fit
1086
- RMSE. Полный `resampling` MDE через повторную переоценку SDiD пока не включён.
1071
+ RMSE. `resampling` строит псевдопанели, добавляет эффект к treated-юнитам в
1072
+ post-периоде и заново оценивает SDiD вместе с unit/time-весами на каждом
1073
+ прогоне; это точнее, но существенно медленнее.
1087
1074
 
1088
1075
  `effect_ci` — доверительный интервал взвешенного ATT от `diff-diff`.
1089
1076
  `effect_relative_ci` и `effect_cumulative_ci` — plug-in преобразования этого
@@ -440,7 +440,7 @@ display(robust.summary)</code></pre>
440
440
  <h3>Как именно выполняются текущие симуляции</h3>
441
441
  <p>Для каждой точки сетки абсолютных эффектов <code>delta</code> пакет генерирует <code>n_simulations</code> оценок по схеме:</p>
442
442
  <pre><code>simulated_estimate = delta + Normal(0, uncertainty_scale)</code></pre>
443
- <p><code>uncertainty_scale</code> равен SE для DiD, Event Study, DDD, RDD, PSM и Doubly Robust. Для Event Study это стандартная ошибка конкретного коэффициента конкретного временного бина, поэтому MDE строится отдельно для каждого бина. Для Synthetic Control, Causal Impact и ITS он строится из ошибки префита: <code>pre-fit RMSE / sqrt(n_post)</code> или <code>validation RMSE / sqrt(n_post)</code>.</p>
443
+ <p><code>uncertainty_scale</code> равен SE для DiD, Event Study, DDD, RDD, PSM и Doubly Robust. Для Event Study это стандартная ошибка конкретного коэффициента конкретного временного бина, поэтому MDE строится отдельно для каждого бина. Для Synthetic Control и Causal Impact он строится из ошибки префита/валидации: <code>pre-fit RMSE / sqrt(n_post)</code> или <code>validation RMSE / sqrt(n_post)</code>. Для ITS <code>fit_its</code> передаёт delta-method SE среднего post-period gap; если она недоступна, используется validation RMSE как fallback.</p>
444
444
  <p>Для каждого <code>delta</code> считается доля симуляций, где нулевая гипотеза отвергнута. Это estimated power. В таблице есть и <code>effect_relative</code> — эффект относительно baseline. Например, <code>effect_absolute=2000</code>, <code>effect_relative=0.02</code>, <code>estimated_power=0.81</code> означает мощность около 81% при эффекте 2% от baseline. Таблица power curve доступна в <code>result.details["mde_power_curve"]</code>, а минимальный <code>delta</code>, достигший целевой мощности, записывается в <code>result.summary["mde_absolute"]</code>.</p>
445
445
  <p><strong>Ошибка прогноза:</strong> RMSE остаётся основной метрикой ошибки и noise scale для MDE. Для интерпретации используется относительный RMSE: RMSE, делённый на средний уровень метрики в предпериоде.</p>
446
446
  <p>Параметрический режим не создает новые строки исходного датафрейма и не переобучает полный pipeline на каждом повторе. Поэтому не выполняются повторный подбор доноров, matching, оптимизация весов Synthetic Control, state-space fit Causal Impact или полный пересчет ITS. Это быстрый MDE на основе параметрической симуляции.</p>
@@ -480,8 +480,7 @@ display(robust.summary)</code></pre>
480
480
  weight_col=None, label="classic_did",
481
481
  mde_mode="auto", alpha=0.05, power=0.80,
482
482
  alternative="two-sided", n_simulations=2000,
483
- random_state=None, mde_effect_grid=None,
484
- mde_simulator=None,
483
+ random_state=None, mde_effect_grid=None, mde_simulator=None,
485
484
  )</code></pre>
486
485
  <table>
487
486
  <thead><tr><th>Параметр</th><th>Тип / значения</th><th>Обязателен</th><th>Описание</th></tr></thead>
@@ -947,7 +946,7 @@ display(robust.summary)</code></pre>
947
946
  seed=42, zeta_omega=None, zeta_lambda=None, label="synthetic_did",
948
947
  mde_mode="auto", alpha=0.05, power=0.80,
949
948
  alternative="two-sided", n_simulations=2000,
950
- random_state=None, mde_effect_grid=None,
949
+ random_state=None, mde_effect_grid=None, mde_simulator=None,
951
950
  )</code></pre>
952
951
  <table>
953
952
  <thead><tr><th>Параметр</th><th>Тип / значения</th><th>Обязателен</th><th>Описание</th></tr></thead>
@@ -970,16 +969,18 @@ display(robust.summary)</code></pre>
970
969
  <table>
971
970
  <thead><tr><th>Параметр</th><th>Тип / значения</th><th>Описание</th></tr></thead>
972
971
  <tbody>
973
- <tr><td><code>mde_mode</code></td><td><code>auto</code>, <code>analytic</code>, <code>parametric</code>, <code>proxy</code></td><td>Для SDiD <code>auto</code> выбирает plug-in analytic по корректной SE от <code>diff-diff</code>; полный <code>resampling</code> с повторной переоценкой SDiD пока не реализован.</td></tr>
972
+ <tr><td><code>mde_mode</code></td><td><code>auto</code>, <code>analytic</code>, <code>parametric</code>, <code>resampling</code>, <code>proxy</code></td><td>Для SDiD <code>auto</code> выбирает plug-in analytic по корректной SE от <code>diff-diff</code>; <code>resampling</code> заново строит псевдопанели и переоценивает SDiD вместе с unit/time-весами.</td></tr>
974
973
  <tr><td><code>alpha</code></td><td>float от 0 до 1</td><td>Уровень ошибки первого рода; по умолчанию <code>0.05</code>.</td></tr>
975
974
  <tr><td><code>power</code></td><td>float от 0 до 1</td><td>Целевая мощность; по умолчанию <code>0.80</code>.</td></tr>
976
975
  <tr><td><code>alternative</code></td><td><code>two-sided</code>, <code>greater</code>, <code>less</code></td><td>Направление теста.</td></tr>
977
- <tr><td><code>n_simulations</code></td><td>int &gt; 0</td><td>Используется параметрическим или proxy-расчётом.</td></tr>
976
+ <tr><td><code>n_simulations</code></td><td>int &gt; 0</td><td>Число повторов для параметрического или resampling-MDE; в analytic/proxy-режимах симуляции не выполняются.</td></tr>
978
977
  <tr><td><code>random_state</code></td><td>int или None</td><td>Seed MDE-расчёта.</td></tr>
979
978
  <tr><td><code>mde_effect_grid</code></td><td>iterable чисел или None</td><td>Явная сетка абсолютных эффектов.</td></tr>
979
+ <tr><td><code>mde_simulator</code></td><td>callable или None</td><td>Необязательный simulator для resampling-режима; если не задан, SDiD строит residual-bootstrap pipeline автоматически.</td></tr>
980
980
  </tbody>
981
981
  </table>
982
982
  <p>В <code>summary</code> находятся <code>effect_absolute</code>, <code>effect_relative</code>, <code>effect_cumulative</code>, <code>effect_ci</code>, <code>effect_relative_ci</code>, <code>effect_cumulative_ci</code>, <code>std_error</code>, <code>p_value</code> и MDE-поля. В <code>details</code> доступны <code>series</code>, полные unit/time weights, <code>weight_concentration</code> с min/max, ESS, общим числом pre-периодов, числом положительных time weights и долями веса top-3/top-5 периодов, power curve и исходный результат <code>diff-diff</code>. Также возвращаются графики actual vs counterfactual и gap. <code>effect_relative_ci</code> выводится с символом <code>%</code>, остальные интервалы — в единицах outcome. <code>effective_pre_periods</code> — это ESS по time weights, а не буквальное число дат. В <code>details["series"]</code> сохраняются сырые <code>counterfactual</code>/<code>gap</code> и level-shift-adjusted <code>counterfactual_level_adjusted</code>/<code>gap_level_adjusted</code>; <code>effect_cumulative</code> и SDiD-графики используют adjusted gap. Относительный и кумулятивный интервалы — plug-in преобразования ATT-интервала и не учитывают дополнительную неопределённость baseline или level-shift alignment.</p>
983
+ <p>В режиме <code>mde_mode="resampling"</code> treated-строки симулируются вокруг level-shift-adjusted synthetic counterfactual, control-строки — вокруг unit-level baseline с календарным профилем контрольной группы. Остатки ресэмплируются, кандидатный эффект добавляется в post-периоде, а каждый draw заново проходит через <code>diff-diff</code> с повторной оценкой unit/time-весов. Это точнее параметрического MDE, но значительно медленнее.</p>
983
984
 
984
985
  <h3><code>check_synthetic_did_assumptions(...)</code></h3>
985
986
  <pre><code>check_synthetic_did_assumptions(
@@ -1030,7 +1031,7 @@ display(robust.summary)</code></pre>
1030
1031
  )</code></pre>
1031
1032
  <p>Для этих нативных проверок также возвращаются одноимённые графики в <code>figures</code>. По умолчанию <code>diff_diff_checks=()</code>, поэтому дополнительные переоценки не запускаются.</p>
1032
1033
  <p>Для SDiD <code>auto</code> и <code>analytic</code> используют plug-in MDE по inferential SE ATT от <code>diff-diff</code>. Это не отдельная закрытая формула дизайн-мощности SDiD: веса уже оценены на исходной панели. <code>parametric</code> использует ту же SE для draws, а <code>proxy</code> — level-shift-adjusted pre-fit RMSE.</p>
1033
- <p class="muted">Полный resampling-MDE с повторным переобучением SDiD пока не включён; для него используйте внешний симулятор и передавайте результат отдельным анализом.</p>
1034
+ <p>В режиме <code>mde_mode="resampling"</code> строится нулевая псевдопанель: treated-строки используют level-shift-adjusted synthetic counterfactual, control-строки — unit-level baseline с календарным профилем. Остатки ресэмплируются, кандидатный эффект добавляется в post-периоде, затем каждый draw заново переоценивается через <code>diff-diff</code> вместе с unit/time-весами. Это наиболее полный, но самый медленный режим MDE.</p>
1034
1035
  </section>
1035
1036
 
1036
1037
  <section class="doc-section" id="causal-impact">
@@ -396,8 +396,10 @@ simulated_estimate = delta + Normal(0, uncertainty_scale)
396
396
  `uncertainty_scale` равен SE для DiD, Event Study, DDD, RDD, PSM и Doubly
397
397
  Robust. Для Event Study это стандартная ошибка конкретного коэффициента
398
398
  конкретного временного бина, поэтому MDE строится отдельно для каждого бина.
399
- Для Synthetic Control, Causal Impact и ITS он строится из ошибки префита:
400
- `pre-fit RMSE / sqrt(n_post)` или `validation RMSE / sqrt(n_post)`.
399
+ Для Synthetic Control и Causal Impact он строится из ошибки префита/валидации:
400
+ `pre-fit RMSE / sqrt(n_post)` или `validation RMSE / sqrt(n_post)`. Для ITS
401
+ `fit_its` передаёт delta-method SE среднего post-period gap; если она
402
+ недоступна, используется validation RMSE как fallback.
401
403
 
402
404
  Для каждого `delta` считается доля симуляций, где нулевая гипотеза отвергнута.
403
405
  Это estimated power. В таблице также есть `effect_relative` — `delta`, делённый
@@ -1296,6 +1298,7 @@ fit_synthetic_did(
1296
1298
  n_simulations=2000,
1297
1299
  random_state=None,
1298
1300
  mde_effect_grid=None,
1301
+ mde_simulator=None,
1299
1302
  )
1300
1303
  ```
1301
1304
 
@@ -1317,13 +1320,14 @@ fit_synthetic_did(
1317
1320
 
1318
1321
  | Параметр | Тип / значения | Описание |
1319
1322
  |---|---|---|
1320
- | `mde_mode` | `auto`, `analytic`, `parametric`, `proxy` | Режим расчёта MDE. Для SDiD `auto` выбирает `analytic`, если `diff-diff` вернул корректную SE; полный `resampling` с повторной переоценкой SDiD пока не реализован. |
1323
+ | `mde_mode` | `auto`, `analytic`, `parametric`, `resampling`, `proxy` | Режим расчёта MDE. Для SDiD `auto` выбирает `analytic`, если `diff-diff` вернул корректную SE. `resampling` генерирует псевдопанели и заново переоценивает SDiD, включая unit/time-веса. |
1321
1324
  | `alpha` | `float` от 0 до 1 | Уровень ошибки первого рода. |
1322
1325
  | `power` | `float` от 0 до 1 | Целевая мощность. |
1323
1326
  | `alternative` | `two-sided`, `greater`, `less` | Направление теста. |
1324
1327
  | `n_simulations` | `int > 0` | Число симуляций для параметрического MDE. |
1325
1328
  | `random_state` | `int` или `None` | Seed MDE-расчёта. |
1326
1329
  | `mde_effect_grid` | iterable чисел или `None` | Явная сетка абсолютных эффектов. |
1330
+ | `mde_simulator` | callable или `None` | Необязательный пользовательский simulator с сигнатурой `(effect, rng, n_simulations) -> array[estimate]`; если не задан, для `resampling` пакет строит residual-bootstrap pipeline автоматически. |
1327
1331
 
1328
1332
  Функция возвращает `MethodResult`. В `summary` находятся единые поля
1329
1333
  `effect_absolute`, `effect_relative`, `effect_cumulative`, `effect_ci`,
@@ -1356,8 +1360,16 @@ API `diff-diff`; jackknife требует более одного treated unit.
1356
1360
  `analytic` можно задать явно. Это не закрытая SDiD-формула дизайн-мощности:
1357
1361
  unit/time weights всё равно оцениваются на исходных данных, а MDE использует
1358
1362
  их итоговую inferential SE. `parametric` делает быстрые симуляции оценок с той
1359
- же SE, `proxy` использует level-shift-adjusted pre-fit RMSE. Полный
1360
- `resampling` MDE через повторную переоценку SDiD пока не включён.
1363
+ же SE, `proxy` использует level-shift-adjusted pre-fit RMSE.
1364
+
1365
+ В режиме `mde_mode="resampling"` пакет строит нулевую row-level панель: для
1366
+ treated используется level-shift-adjusted synthetic counterfactual по датам, а
1367
+ для control — unit-level baseline с календарным профилем контрольной группы.
1368
+ Центрированные остатки ресэмплируются, кандидатный эффект добавляется только
1369
+ treated-юнитам в post-периоде, после чего каждый draw заново проходит через
1370
+ `diff-diff` и повторно оценивает unit/time-веса. Это наиболее близкая к полному
1371
+ pipeline оценка мощности, но она существенно медленнее `analytic` и
1372
+ `parametric`.
1361
1373
 
1362
1374
  ### `check_synthetic_did_assumptions(...)`
1363
1375
 
@@ -2,7 +2,7 @@ from post_analysis_toolkit.compat import ensure_runtime_compat
2
2
 
3
3
  ensure_runtime_compat()
4
4
 
5
- __version__ = "1.0.8"
5
+ __version__ = "1.0.9"
6
6
 
7
7
  from post_analysis_toolkit.causal_impact import (
8
8
  check_causal_impact_assumptions,
@@ -20,8 +20,12 @@ from post_analysis_toolkit.mde import (
20
20
  DEFAULT_N_SIMULATIONS,
21
21
  DEFAULT_POWER,
22
22
  calculate_mde,
23
+ resolve_mde_mode,
24
+ )
25
+ from post_analysis_toolkit.mde_resampling import (
26
+ close_method_result_figures,
27
+ make_residual_bootstrap_simulator,
23
28
  )
24
- from post_analysis_toolkit.mde_resampling import close_method_result_figures
25
29
  from post_analysis_toolkit.utils import (
26
30
  coerce_datetime,
27
31
  ensure_columns,
@@ -195,6 +199,7 @@ def fit_synthetic_did(
195
199
  n_simulations: int = DEFAULT_N_SIMULATIONS,
196
200
  random_state: int | None = None,
197
201
  mde_effect_grid: Iterable[float] | None = None,
202
+ mde_simulator=None,
198
203
  _prepared: bool = False,
199
204
  ) -> MethodResult:
200
205
  """Fit Synthetic DiD using the ``diff-diff`` implementation.
@@ -202,6 +207,11 @@ def fit_synthetic_did(
202
207
  ``treated_col`` must mark ever-treated units and remain constant within a
203
208
  unit. ``intervention_time`` separates the datetime panel into pre and post
204
209
  periods; the underlying estimator receives the explicit post-period list.
210
+
211
+ ``mde_mode="resampling"`` builds a residual-bootstrap null panel and
212
+ re-fits SDiD for every simulated draw, including re-estimation of unit and
213
+ time weights. A custom ``mde_simulator`` may be supplied when a different
214
+ data-generating process is required.
205
215
  """
206
216
  _require_diff_diff()
207
217
  # FPR runs reuse the same validated/coerced panel. The private flag keeps
@@ -261,6 +271,74 @@ def fit_synthetic_did(
261
271
  # estimated from the data). The same SE is also the natural scale for
262
272
  # parametric effect draws; ``proxy`` remains the RMSE-based fallback.
263
273
  fitted_se = float(fitted.se) if np.isfinite(fitted.se) and fitted.se >= 0 else None
274
+ if mde_simulator is None and resolve_mde_mode(mde_mode, analytic_available=False) == "resampling":
275
+ # ``diff-diff`` exposes the fitted treated and synthetic trajectories,
276
+ # but not row-level fitted values for every unit. Build a transparent
277
+ # row-level null here: treated rows use the level-shift-adjusted SDiD
278
+ # counterfactual by date; controls use their unit mean plus the
279
+ # control-group calendar-time deviation. Residuals around this null
280
+ # are then resampled and every draw is passed through a fresh SDiD fit,
281
+ # including re-estimation of unit/time weights.
282
+ intervention_ts = pd.Timestamp(intervention_time)
283
+ time_values = pd.to_datetime(work_df[time_col])
284
+ treated_mask = work_df[treated_col].astype(int).to_numpy() == 1
285
+ post_mask = (time_values >= intervention_ts).to_numpy(dtype=float)
286
+ adjusted_counterfactual_by_time = (
287
+ series.set_index(time_col)["counterfactual_level_adjusted"]
288
+ )
289
+ treated_prediction = time_values.map(adjusted_counterfactual_by_time).to_numpy(dtype=float)
290
+
291
+ control_df = work_df.loc[~treated_mask].copy()
292
+ if control_df.empty:
293
+ control_prediction = np.full(len(work_df), np.nan, dtype=float)
294
+ else:
295
+ control_unit_mean = control_df.groupby(unit_col)[outcome_col].mean()
296
+ control_time_mean = control_df.groupby(time_col)[outcome_col].mean()
297
+ control_overall_mean = float(control_df[outcome_col].mean())
298
+ control_prediction = (
299
+ work_df[unit_col].map(control_unit_mean).to_numpy(dtype=float)
300
+ + work_df[time_col].map(control_time_mean).to_numpy(dtype=float)
301
+ - control_overall_mean
302
+ )
303
+
304
+ baseline_prediction = np.where(treated_mask, treated_prediction, control_prediction)
305
+ # A missing unit/date mean should not make the whole simulator fail;
306
+ # retain the observed value as a last-resort row-level baseline.
307
+ observed_outcome = pd.to_numeric(work_df[outcome_col], errors="coerce").to_numpy(dtype=float)
308
+ baseline_prediction = np.where(
309
+ np.isfinite(baseline_prediction), baseline_prediction, observed_outcome
310
+ )
311
+ effect_mask = treated_mask.astype(float) * post_mask
312
+
313
+ def estimate_fn(simulated_df: pd.DataFrame) -> float:
314
+ simulated_result = fit_synthetic_did(
315
+ simulated_df,
316
+ outcome_col=outcome_col,
317
+ unit_col=unit_col,
318
+ time_col=time_col,
319
+ treated_col=treated_col,
320
+ intervention_time=intervention_time,
321
+ covariates=covariates,
322
+ variance_method=variance_method,
323
+ n_bootstrap=n_bootstrap,
324
+ seed=seed,
325
+ zeta_omega=zeta_omega,
326
+ zeta_lambda=zeta_lambda,
327
+ label="mde_resampling_synthetic_did",
328
+ mde_mode="none",
329
+ _prepared=True,
330
+ )
331
+ close_method_result_figures(simulated_result)
332
+ return float(simulated_result.summary.iloc[0]["effect_absolute"])
333
+
334
+ mde_simulator = make_residual_bootstrap_simulator(
335
+ work_df,
336
+ outcome_col,
337
+ baseline_prediction,
338
+ effect_mask,
339
+ estimate_fn,
340
+ )
341
+
264
342
  mde = calculate_mde(
265
343
  mde_mode=mde_mode,
266
344
  baseline=post_baseline,
@@ -273,6 +351,7 @@ def fit_synthetic_did(
273
351
  n_simulations=n_simulations,
274
352
  random_state=random_state,
275
353
  effect_grid=mde_effect_grid,
354
+ simulate_estimate=mde_simulator,
276
355
  )
277
356
  ci_low, ci_high = fitted.conf_int if fitted.conf_int is not None else (np.nan, np.nan)
278
357
  if np.isfinite(ci_low) and np.isfinite(ci_high) and np.isfinite(baseline) and baseline != 0:
@@ -1,3 +1,24 @@
1
+ Metadata-Version: 2.4
2
+ Name: post-analysis-toolkit
3
+ Version: 1.0.9
4
+ Summary: Reusable helpers for post-analysis, quasi-causal designs, and diagnostics.
5
+ Author: OpenAI Codex
6
+ Requires-Python: >=3.11
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: numpy>=2.4
9
+ Requires-Dist: pandas<3,>=2.3
10
+ Requires-Dist: scipy>=1.17
11
+ Requires-Dist: statsmodels>=0.14
12
+ Requires-Dist: scikit-learn>=1.9
13
+ Requires-Dist: matplotlib>=3.11
14
+ Requires-Dist: seaborn>=0.13
15
+ Requires-Dist: causalimpact>=0.2.6
16
+ Requires-Dist: diff-diff<4,>=3.11
17
+ Provides-Extra: dev
18
+ Requires-Dist: build>=1.2; extra == "dev"
19
+ Requires-Dist: pytest>=9.1; extra == "dev"
20
+ Requires-Dist: twine>=6.1; extra == "dev"
21
+
1
22
  # Post Analysis Toolkit
2
23
 
3
24
  `post_analysis_toolkit` - локальная библиотека для пост-анализа промо, rollout-ов и других квази-экспериментальных задач, где нужен воспроизводимый causal / quasi-causal пайплайн.
@@ -129,16 +150,17 @@ MDE относится к конкретному estimand и специфика
129
150
  генерирует оценки по схеме `delta + Normal(0, uncertainty_scale)`. Для
130
151
  регрессионных и observational-методов `uncertainty_scale` — SE. Для Event Study
131
152
  это SE конкретного коэффициента конкретного временного бина, поэтому MDE
132
- считается отдельно для каждого бина. Для
133
- Synthetic Control/Causal Impact/ITS — pre-fit или validation RMSE,
134
- нормированный на размер post-period.
153
+ считается отдельно для каждого бина. Для Synthetic Control и Causal Impact
154
+ используется pre-fit или validation RMSE, нормированный на размер post-period;
155
+ для ITS при доступной covariance matrix используется delta-method SE среднего
156
+ post-period gap, а validation RMSE остаётся fallback.
135
157
 
136
158
  В режиме `resampling` пакет создает псевдоданные: берет fitted/counterfactual
137
159
  значения без эффекта, добавляет ресэмплированные центрированные остатки и
138
160
  кандидатный эффект, а затем повторно запускает весь поддержанный оцениватель.
139
161
  Для Synthetic Control заново подбираются веса, для PSM заново строится matching,
140
- для Causal Impact заново обучается state-space модель, а для ITS заново
141
- оценивается регрессия. Такой режим заметно медленнее и требует явно задать
162
+ для Causal Impact заново обучается state-space модель, для ITS заново
163
+ оценивается регрессия, а для SDiD заново подбираются unit/time-веса. Такой режим заметно медленнее и требует явно задать
142
164
  разумное `n_simulations` и, при необходимости, `mde_effect_grid`.
143
165
 
144
166
  Power curve можно посмотреть в
@@ -1043,6 +1065,11 @@ display(sdid_result.figures["actual_vs_counterfactual"])
1043
1065
  `effect_ci`, `effect_relative_ci`, `effect_cumulative_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
1044
1066
  `mde_cumulative`, `mde_mode_resolved`.
1045
1067
 
1068
+ Для SDiD доступны `mde_mode="analytic"`, `"parametric"`, `"resampling"` и
1069
+ `"proxy"`. В `resampling` можно передать `mde_simulator`; если он не задан,
1070
+ пакет автоматически строит residual-bootstrap pipeline и повторно вызывает
1071
+ `diff-diff` для каждой симулированной панели.
1072
+
1046
1073
  В `details["unit_weights"]` и `details["time_weights"]` доступны полные
1047
1074
  списки весов. В `details["weight_concentration"]` пакет дополнительно
1048
1075
  показывает min/max, эффективное число доноров и pre-периодов, общее число
@@ -1062,7 +1089,9 @@ level-shift-adjusted `counterfactual_level_adjusted`/`gap_level_adjusted`.
1062
1089
  SDiD-формула дизайн-мощности: unit/time weights оцениваются на исходных
1063
1090
  данных, а MDE использует итоговую inferential SE. `parametric` делает быстрые
1064
1091
  симуляции оценок с той же SE, `proxy` использует level-shift-adjusted pre-fit
1065
- RMSE. Полный `resampling` MDE через повторную переоценку SDiD пока не включён.
1092
+ RMSE. `resampling` строит псевдопанели, добавляет эффект к treated-юнитам в
1093
+ post-периоде и заново оценивает SDiD вместе с unit/time-весами на каждом
1094
+ прогоне; это точнее, но существенно медленнее.
1066
1095
 
1067
1096
  `effect_ci` — доверительный интервал взвешенного ATT от `diff-diff`.
1068
1097
  `effect_relative_ci` и `effect_cumulative_ci` — plug-in преобразования этого
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "post-analysis-toolkit"
7
- version = "1.0.8"
7
+ version = "1.0.9"
8
8
  description = "Reusable helpers for post-analysis, quasi-causal designs, and diagnostics."
9
9
  readme = "post_analysis_toolkit/README.md"
10
10
  requires-python = ">=3.11"