post-analysis-toolkit 1.0.5__tar.gz → 1.0.8__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 (38) hide show
  1. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/MANIFEST.in +1 -0
  2. {post_analysis_toolkit-1.0.5/post_analysis_toolkit.egg-info → post_analysis_toolkit-1.0.8}/PKG-INFO +385 -2
  3. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/README.md +14 -0
  4. post_analysis_toolkit-1.0.8/notebooks/did_its_template.ipynb +6663 -0
  5. post_analysis_toolkit-1.0.8/notebooks/synthetic_did_databricks_template.ipynb +3285 -0
  6. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/MDE_METHODOLOGY.md +10 -0
  7. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/README.md +383 -1
  8. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/REFERENCE.html +275 -42
  9. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/REFERENCE.md +651 -38
  10. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/__init__.py +9 -1
  11. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/causal_impact.py +380 -38
  12. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/contracts.py +31 -6
  13. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/demo.py +57 -3
  14. post_analysis_toolkit-1.0.8/post_analysis_toolkit/did.py +2301 -0
  15. post_analysis_toolkit-1.0.8/post_analysis_toolkit/its.py +1183 -0
  16. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/observational.py +2 -0
  17. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/rdd.py +96 -3
  18. post_analysis_toolkit-1.0.8/post_analysis_toolkit/synthetic_control.py +1263 -0
  19. post_analysis_toolkit-1.0.8/post_analysis_toolkit/synthetic_did.py +1339 -0
  20. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/triple_difference.py +64 -10
  21. post_analysis_toolkit-1.0.8/post_analysis_toolkit/utils.py +1003 -0
  22. post_analysis_toolkit-1.0.8/post_analysis_toolkit/visualization.py +407 -0
  23. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8/post_analysis_toolkit.egg-info}/PKG-INFO +385 -2
  24. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit.egg-info/SOURCES.txt +2 -0
  25. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit.egg-info/requires.txt +1 -0
  26. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/pyproject.toml +2 -1
  27. post_analysis_toolkit-1.0.5/notebooks/did_its_template.ipynb +0 -3153
  28. post_analysis_toolkit-1.0.5/post_analysis_toolkit/did.py +0 -1168
  29. post_analysis_toolkit-1.0.5/post_analysis_toolkit/its.py +0 -696
  30. post_analysis_toolkit-1.0.5/post_analysis_toolkit/synthetic_control.py +0 -532
  31. post_analysis_toolkit-1.0.5/post_analysis_toolkit/utils.py +0 -327
  32. post_analysis_toolkit-1.0.5/post_analysis_toolkit/visualization.py +0 -235
  33. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/compat.py +0 -0
  34. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/mde.py +0 -0
  35. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit/mde_resampling.py +0 -0
  36. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit.egg-info/dependency_links.txt +0 -0
  37. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/post_analysis_toolkit.egg-info/top_level.txt +0 -0
  38. {post_analysis_toolkit-1.0.5 → post_analysis_toolkit-1.0.8}/setup.cfg +0 -0
@@ -3,3 +3,4 @@ include post_analysis_toolkit/REFERENCE.md
3
3
  include post_analysis_toolkit/REFERENCE.html
4
4
  include post_analysis_toolkit/MDE_METHODOLOGY.md
5
5
  include notebooks/did_its_template.ipynb
6
+ include notebooks/synthetic_did_databricks_template.ipynb
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: post-analysis-toolkit
3
- Version: 1.0.5
3
+ Version: 1.0.8
4
4
  Summary: Reusable helpers for post-analysis, quasi-causal designs, and diagnostics.
5
5
  Author: OpenAI Codex
6
6
  Requires-Python: >=3.11
@@ -13,6 +13,7 @@ Requires-Dist: scikit-learn>=1.9
13
13
  Requires-Dist: matplotlib>=3.11
14
14
  Requires-Dist: seaborn>=0.13
15
15
  Requires-Dist: causalimpact>=0.2.6
16
+ Requires-Dist: diff-diff<4,>=3.11
16
17
  Provides-Extra: dev
17
18
  Requires-Dist: build>=1.2; extra == "dev"
18
19
  Requires-Dist: pytest>=9.1; extra == "dev"
@@ -36,11 +37,12 @@ Requires-Dist: twine>=6.1; extra == "dev"
36
37
 
37
38
  - классический `Difference-in-Differences`
38
39
  - регрессионный `DiD`
39
- - `DiD` с `HC1` robust SE или cluster-robust SE
40
+ - `DiD` с cluster-robust SE по unit по умолчанию или `HC1` при явном `cluster_col=None`
40
41
  - `DiD` с `TWFE`
41
42
  - `DiD` с лог-трансформацией outcome
42
43
  - `DiD` с относительной индексацией outcome
43
44
  - `Synthetic Control`
45
+ - `Synthetic DiD (SDiD)` через `diff-diff`
44
46
  - `Causal Impact`
45
47
  - `Interrupted Time Series`
46
48
  - `Triple Difference`
@@ -52,6 +54,77 @@ Requires-Dist: twine>=6.1; extra == "dev"
52
54
  - базовые проверки устойчивости
53
55
  - встроенные `matplotlib`-графики
54
56
 
57
+ ### Стандартные ошибки и кластеризация
58
+
59
+ Для `fit_did_regression`, `fit_event_study` и `fit_triple_difference` по
60
+ умолчанию используется односторонняя cluster-robust ошибка. При
61
+ `cluster_col="auto"` (значение по умолчанию) пакет сначала использует
62
+ `unit_col`, а затем ищет стандартную колонку `unit`, `unit_id`, `pizzeria`,
63
+ `city` или `cluster`. Чтобы явно отключить кластеризацию и использовать HC1,
64
+ передайте `cluster_col=None`. Если в данных нет подходящей колонки, `auto`
65
+ безопасно откатывается к HC1; фактически выбранный режим смотрите в
66
+ `result.metadata["stderr_type"]`.
67
+
68
+ Односторонняя cluster covariance — CR1-style: statsmodels применяет
69
+ finite-sample correction, а p-value по умолчанию рассчитывается с нормальной
70
+ аппроксимацией (`use_t=False`). При небольшом числе кластеров можно выбрать
71
+ `se_type="cr2"` или `se_type="cr3"`: это leverage-adjusted варианты
72
+ кластерной covariance без внешних зависимостей.
73
+
74
+ Для регрессионных методов можно явно выбрать `se_type`: `"nonrobust"` (обычная
75
+ OLS SE без коррекции), `"hc1"`,
76
+ `"cluster"` (один уровень), `"cr2"`, `"cr3"`, `"wild_cluster"` или
77
+ `"two_way_cluster"` (Cameron–Gelbach–Miller, unit × time). `"auto"` сохраняет прежнее поведение: кластеризация по
78
+ `cluster_col`, если она задана/найдена, иначе HC1. В two-way режиме второй
79
+ уровень по умолчанию берётся из `time_col`; его можно переопределить
80
+ `time_cluster_col`. `wild_cluster` использует Rademacher wild cluster
81
+ bootstrap для эмпирической covariance; число повторов задаётся
82
+ `wild_bootstrap_reps` (по умолчанию 999), а seed — через `random_state`.
83
+ Это bootstrap-оценка SE, а не отдельный null-imposed bootstrap-тест p-value.
84
+
85
+ `fit_its` использует HAC/Newey–West (`hac_lags=7` по умолчанию), но также
86
+ поддерживает `se_type="hc1"`, `"cluster"`, `"cr2"`, `"cr3"`,
87
+ `"wild_cluster"` и `"two_way_cluster"` для панельных
88
+ данных. `fit_its`/`check_its_assumptions` принимают `cluster_col` и
89
+ `time_cluster_col`, а `run_its_robustness` по умолчанию перебирает
90
+ `hac_lags=(0, 3, 7, 14)`. Для RDD two-way режим требует явного
91
+ `time_cluster_col`; density-регрессия в проверке предпосылок остаётся HC1.
92
+
93
+ Панельный ITS передаётся в long-формате с одной строкой на `unit × date`.
94
+ Передайте `se_type="cluster"` и `cluster_col` с идентификатором юнита:
95
+
96
+ ```python
97
+ panel_its = fit_its(
98
+ panel_df,
99
+ outcome_col="orders_per_unit_day",
100
+ time_col="sale_date",
101
+ intervention_time="2026-06-14",
102
+ se_type="cluster",
103
+ cluster_col="pizzeria_id",
104
+ )
105
+ ```
106
+
107
+ Для такой панели holdout и rolling-метрики считаются по календарным датам
108
+ (среднее по юнитам), а график эффекта также показывает средний ряд по датам.
109
+ PSM и Doubly Robust используют IID-оценку по score/differences.
110
+ Synthetic Control не имеет модельной SE/p-value и использует placebo-диагностики,
111
+ SDiD — `variance_method="placebo"`, `"bootstrap"` или `"jackknife"` из
112
+ `diff-diff`, а Causal Impact — байесовские posterior-интервалы. При небольшом
113
+ числе кластеров, особенно при одном treated-кластере, кластерные p-value и FPR
114
+ могут быть нестабильны; их нужно сопоставлять с placebo и sensitivity.
115
+
116
+ В ITS `hac_lags` — максимальный лаг автокорреляции для HAC/Newey–West. Для
117
+ ежедневных данных `7` — разумная стартовая настройка при недельной сезонности,
118
+ но это не универсальное значение. На практике сравнивайте несколько соседних
119
+ значений (например, `0`, `3`, `7`, `14`) и проверяйте, меняется ли вывод об
120
+ эффекте; `run_its_robustness` делает такой перебор автоматически.
121
+
122
+ Для ITS `se_type="auto"` означает: если передан или автоматически найден
123
+ `cluster_col`, использовать one-way cluster; если кластер не задан — HAC.
124
+ При этом значение по умолчанию у `fit_its` и `check_its_assumptions` —
125
+ `se_type="hac"`, поэтому для автоматического выбора нужно указать
126
+ `se_type="auto"` явно.
127
+
55
128
  ## MDE и чувствительность
56
129
 
57
130
  Для всех MDE по умолчанию используются `alpha=0.05`, `power=0.80` и
@@ -178,15 +251,18 @@ parametric- или resampling-режиме эти legacy-поля остаютс
178
251
  from post_analysis_toolkit import (
179
252
  check_did_assumptions,
180
253
  check_doubly_robust_assumptions,
254
+ check_synthetic_did_assumptions,
181
255
  fit_did_regression,
182
256
  fit_event_study,
183
257
  fit_doubly_robust,
184
258
  fit_synthetic_control,
259
+ fit_synthetic_did,
185
260
  fit_causal_impact,
186
261
  fit_its,
187
262
  fit_psm,
188
263
  fit_rdd,
189
264
  fit_triple_difference,
265
+ run_synthetic_did_robustness,
190
266
  )
191
267
  ```
192
268
 
@@ -384,9 +460,30 @@ did_diag = check_did_assumptions(
384
460
  intervention_time="2026-02-07",
385
461
  unit_col="unit",
386
462
  cluster_col="unit",
463
+ twfe=True,
387
464
  )
388
465
  print(did_diag.checks)
389
466
 
467
+ # Можно сравнить несколько эмпирических FPR-процедур одновременно.
468
+ did_diag = check_did_assumptions(
469
+ did_df,
470
+ outcome_col="metric",
471
+ time_col="sale_date",
472
+ treated_col="treated_flag",
473
+ post_col="post_flag",
474
+ intervention_time="2026-02-07",
475
+ unit_col="unit",
476
+ cluster_col="unit",
477
+ twfe=True,
478
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
479
+ fpr_placebo_count=200,
480
+ fpr_block_length=7,
481
+ )
482
+ print(did_diag.details["fpr_results"])
483
+
484
+ # Важно: FPR-процедуры должны получать ту же спецификацию, что и оценка
485
+ # эффекта (например, twfe=True, одинаковые covariates/log_transform/relative).
486
+
390
487
  did_result = fit_did_regression(
391
488
  did_df,
392
489
  outcome_col="metric",
@@ -444,8 +541,12 @@ sc_diag = check_synthetic_control_assumptions(
444
541
  time_col="sale_date",
445
542
  treated_unit="Batumi",
446
543
  intervention_time="2026-02-08",
544
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
545
+ fpr_placebo_count=20,
546
+ fpr_block_length=7,
447
547
  )
448
548
  print(sc_diag.checks)
549
+ print(sc_diag.details["fpr_results"])
449
550
 
450
551
  sc_result = fit_synthetic_control(
451
552
  sc_df,
@@ -497,6 +598,18 @@ its_diag = check_its_assumptions(
497
598
  )
498
599
  print(its_diag.checks)
499
600
 
601
+ # Для ITS доступен time placebo; placebo_units
602
+ # неприменим, потому что это single-series метод без units.
603
+ its_diag = check_its_assumptions(
604
+ its_df,
605
+ outcome_col="metric",
606
+ time_col="sale_date",
607
+ intervention_time="2026-01-11",
608
+ fpr_method="time_placebo",
609
+ fpr_placebo_count=200,
610
+ )
611
+ print(its_diag.details["fpr_results"])
612
+
500
613
  its_result = fit_its(
501
614
  its_df,
502
615
  outcome_col="metric",
@@ -512,6 +625,26 @@ its_robust = run_its_robustness(
512
625
  intervention_time="2026-01-11",
513
626
  )
514
627
  print(its_robust.summary)
628
+
629
+ # Для panel ITS можно выбрать кластеризацию по unit и два уровня unit × time.
630
+ panel_its = fit_its(
631
+ panel_df,
632
+ outcome_col="outcome",
633
+ time_col="sale_date",
634
+ intervention_time="2026-02-01",
635
+ se_type="cluster",
636
+ cluster_col="unit",
637
+ )
638
+ panel_its_two_way = fit_its(
639
+ panel_df,
640
+ outcome_col="outcome",
641
+ time_col="sale_date",
642
+ intervention_time="2026-02-01",
643
+ se_type="two_way_cluster",
644
+ cluster_col="unit",
645
+ time_cluster_col="sale_date",
646
+ )
647
+ # Для HAC sensitivity автоматически перебираются 0, 3, 7 и 14 лагов.
515
648
  ```
516
649
 
517
650
  ### 4. End-to-end пример: PSM
@@ -739,6 +872,51 @@ did_robust = run_did_robustness(
739
872
  - с логами и без
740
873
  - с относительной индексацией и без
741
874
 
875
+ Для отдельной динамики эффекта используется Event Study. В его проверке
876
+ предпосылок FPR считается по joint Wald-тесту всех post-бинов (а не по
877
+ минимальному p-value отдельного бина):
878
+
879
+ ```python
880
+ from post_analysis_toolkit import check_event_study_assumptions, fit_event_study
881
+
882
+ event_diag = check_event_study_assumptions(
883
+ panel_df,
884
+ outcome_col="metric",
885
+ time_col="sale_date",
886
+ treated_col="treated_flag",
887
+ intervention_time="2026-02-25",
888
+ unit_col="unit",
889
+ cluster_col="unit",
890
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
891
+ fpr_placebo_count=200,
892
+ fpr_block_length=7,
893
+ )
894
+ event_result = fit_event_study(
895
+ panel_df,
896
+ outcome_col="metric",
897
+ time_col="sale_date",
898
+ treated_col="treated_flag",
899
+ intervention_time="2026-02-25",
900
+ unit_col="unit",
901
+ cluster_col="unit",
902
+ event_bin_size=7,
903
+ )
904
+ ```
905
+
906
+ В `event_result.details["event_study_summary"]` доступны
907
+ `joint_pre_p_value` и `joint_post_p_value`; FPR-таблица находится в
908
+ `event_diag.details["fpr_results"]`. MDE по каждому event-бину можно получить
909
+ уже на этапе проверки предпосылок:
910
+
911
+ ```python
912
+ display(event_diag.details["event_study_mde"])
913
+ ```
914
+
915
+ Для расчёта MDE на этом этапе используются те же параметры, что и в
916
+ `fit_event_study` (`mde_mode`, `power`, `alternative`, `n_simulations`,
917
+ `random_state`, `mde_effect_grid`, `mde_simulator`). По умолчанию `mde_mode="auto"`
918
+ выбирает аналитический MDE по стандартной ошибке каждого event-бина.
919
+
742
920
  ## Synthetic Control: пример
743
921
 
744
922
  ### Формат данных для функции
@@ -780,8 +958,21 @@ synth_diag = check_synthetic_control_assumptions(
780
958
  treated_unit="Batumi",
781
959
  intervention_time="2026-02-25",
782
960
  donor_units=["Tbilisi", "Kutaisi"],
961
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
962
+ fpr_placebo_count=20,
963
+ fpr_block_length=7,
783
964
  )
965
+ print(synth_diag.details["fpr_results"])
966
+
967
+ ```
968
+
969
+ Помимо in-space `placebo_units`, Synthetic Control поддерживает
970
+ `time_placebo` (фиктивные даты внутри предпериода) и `block_bootstrap`
971
+ (нулевые панели из общих временных блоков). Подробные результаты находятся в
972
+ `details["time_placebo_results"]` и `details["block_bootstrap_results"]`;
973
+ план доступных прогонов — в `details["fpr_plan"]`.
784
974
 
975
+ ```python
785
976
  synth_result = fit_synthetic_control(
786
977
  df=panel_df,
787
978
  outcome_col="metric",
@@ -812,11 +1003,164 @@ synth_robust = run_synthetic_control_robustness(
812
1003
  - `avg_post_effect`
813
1004
  - `avg_post_relative_effect`
814
1005
  - таблицу весов `details["weights"]`
1006
+ - `details["weight_concentration"]` с min/max весом, effective donors,
1007
+ числом доноров с положительным весом и долей веса крупнейшего донора
1008
+ - `details["fpr_results"]` с in-space FPR и permutation p-value
815
1009
 
816
1010
  Проверки устойчивости:
817
1011
 
818
1012
  - placebo по каждому донору
819
1013
  - leave-one-out по донорам
1014
+ - in-space placebo-калибровка FPR в `check_synthetic_control_assumptions`
1015
+ - `time_placebo` с фиктивными датами внутри предпериода
1016
+ - `block_bootstrap` с нулевыми панелями из общих временных блоков
1017
+
1018
+ Для Synthetic Control нет модельного p-value/SE. In-space FPR по очереди
1019
+ делает каждого донора псевдотритментом, сравнивает post/pre RMSPE-ratio с
1020
+ остальными донорами и возвращает permutation p-value исходной treated unit.
1021
+ `time_placebo` переносит дату вмешательства внутрь предпериода, а
1022
+ `block_bootstrap` создаёт нулевые панели, ресэмплируя общие временные блоки.
1023
+ В обоих случаях значимость всё равно определяется in-space permutation по
1024
+ RMSPE-ratio, а не обычной модельной SE. Число успешных `placebo_units`
1025
+ прогонов не может быть больше размера donor pool; для остальных методов
1026
+ ограничение задаётся числом допустимых дат или успешных bootstrap-прогонов.
1027
+ Для содержательной калибровки желательно иметь минимум три донора: при
1028
+ маленьком donor pool permutation p-value дискретен и FPR получается грубой
1029
+ диагностикой.
1030
+
1031
+ Концентрация donor weights не является автоматическим pass/fail-критерием.
1032
+ Если `top1_weight_share` близка к 100% или `effective_donors` близко к 1,
1033
+ нужно дополнительно проверить `leave_one_out_results` и устойчивость к
1034
+ расширению/очистке donor pool.
1035
+
1036
+ ## Synthetic DiD (SDiD)
1037
+
1038
+ Synthetic DiD сочетает DiD с unit- и time-весами synthetic control. В пакетe
1039
+ доступны три функции:
1040
+
1041
+ - `fit_synthetic_did(...)` — расчёт эффекта и synthetic counterfactual;
1042
+ - `check_synthetic_did_assumptions(...)` — pre-fit с учётом level shift, proxy-MDE и placebo FPR;
1043
+ - `run_synthetic_did_robustness(...)` — чувствительность к pre-window и placebo датам.
1044
+
1045
+ ```python
1046
+ from post_analysis_toolkit import fit_synthetic_did
1047
+
1048
+ sdid_result = fit_synthetic_did(
1049
+ df=panel_df,
1050
+ outcome_col="revenue",
1051
+ unit_col="pizzeria",
1052
+ time_col="sale_date",
1053
+ treated_col="treated_flag",
1054
+ intervention_time="2026-02-01",
1055
+ variance_method="placebo",
1056
+ )
1057
+ display(sdid_result.summary)
1058
+ display(sdid_result.details["unit_weights"])
1059
+ display(sdid_result.figures["actual_vs_counterfactual"])
1060
+ ```
1061
+
1062
+ `treated_col` должен быть бинарным и постоянным внутри unit. Основные поля
1063
+ `summary`: `effect_absolute`, `effect_relative`, `effect_cumulative`,
1064
+ `effect_ci`, `effect_relative_ci`, `effect_cumulative_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
1065
+ `mde_cumulative`, `mde_mode_resolved`.
1066
+
1067
+ В `details["unit_weights"]` и `details["time_weights"]` доступны полные
1068
+ списки весов. В `details["weight_concentration"]` пакет дополнительно
1069
+ показывает min/max, эффективное число доноров и pre-периодов, общее число
1070
+ pre-периодов, число периодов с положительным time weight, долю effective
1071
+ pre-периодов и долю веса трёх/пяти самых важных периодов. Это описательные
1072
+ метрики без автоматически заданных порогов; `effective_pre_periods` — это
1073
+ ESS по time weights, а не буквальное число использованных дат.
1074
+
1075
+ В `details["series"]` сохраняются сырые `counterfactual`/`gap` и
1076
+ level-shift-adjusted `counterfactual_level_adjusted`/`gap_level_adjusted`.
1077
+ `effect_cumulative` и графики SDiD используют adjusted gap, чтобы не включать
1078
+ допустимую постоянную разницу уровней в оценку инкрементального эффекта.
1079
+
1080
+ Для SDiD поддерживаются `variance_method="placebo"`, `"bootstrap"` и
1081
+ `"jackknife"`. Режим MDE `auto` при корректной SE от `diff-diff` выбирает
1082
+ аналитический plug-in расчёт; `analytic` можно задать явно. Это не закрытая
1083
+ SDiD-формула дизайн-мощности: unit/time weights оцениваются на исходных
1084
+ данных, а MDE использует итоговую inferential SE. `parametric` делает быстрые
1085
+ симуляции оценок с той же SE, `proxy` использует level-shift-adjusted pre-fit
1086
+ RMSE. Полный `resampling` MDE через повторную переоценку SDiD пока не включён.
1087
+
1088
+ `effect_ci` — доверительный интервал взвешенного ATT от `diff-diff`.
1089
+ `effect_relative_ci` и `effect_cumulative_ci` — plug-in преобразования этого
1090
+ интервала для относительного (со знаком `%`) и cumulative estimand; дополнительная
1091
+ неопределённость baseline и level-shift alignment в них не моделируется.
1092
+
1093
+ В `check_synthetic_did_assumptions(...)` параметр `fpr_placebo_count` задаёт
1094
+ число placebo-прогонов. Если передать `zeta_omega` или `zeta_lambda`, эта же
1095
+ регуляризация будет использована и в основном fit, и во всех placebo-fit —
1096
+ это позволяет честно сравнивать эмпирическую FPR между вариантами
1097
+ `zeta_lambda`.
1098
+
1099
+ Параметр `fpr_method` принимает одну строку или список методов: `time_placebo`
1100
+ (fake intervention даты внутри pre-period), `block_bootstrap` (ресэмплинг
1101
+ общих временных блоков без эффекта) и `placebo_units` (формирование placebo-
1102
+ treated групп контрольных пиццерий того же размера, что и исходная treated-
1103
+ группа). Можно передать несколько методов сразу,
1104
+ например `fpr_method=("time_placebo", "block_bootstrap", "placebo_units")`.
1105
+ Для block bootstrap длина блока задаётся `fpr_block_length` (по умолчанию 7).
1106
+ Сводка по каждому методу находится в `details["fpr_results"]`; при выборе
1107
+ нескольких методов добавляются method-specific строки в `checks` и график
1108
+ `figures["fpr_comparison"]`. `fpr_placebo_count` используется как число
1109
+ попыток для time placebo/block bootstrap и как максимум контрольных units для
1110
+ placebo units; фактический знаменатель находится в колонке `runs`, а размер
1111
+ placebo-группы — в `placebo_group_size`.
1112
+
1113
+ Практический порядок работы: сначала запустите
1114
+ `check_synthetic_did_assumptions(...)` и посмотрите одновременно на FPR и
1115
+ `details["weight_concentration"]`. Если FPR заметно выше заданного `alpha`, а
1116
+ `effective_pre_periods` мало и top-3 time weights забирают большую долю веса,
1117
+ повторите основной fit и проверку с явно заданным большим `zeta_lambda`:
1118
+
1119
+ ```python
1120
+ sdid_result = fit_synthetic_did(..., zeta_lambda=25_000.0)
1121
+ sdid_checks = check_synthetic_did_assumptions(
1122
+ ..., zeta_lambda=25_000.0,
1123
+ )
1124
+ ```
1125
+
1126
+ Это не универсальный порог: значение зависит от масштаба outcome и должно
1127
+ выбираться по sensitivity-таблице вместе с предметной интерпретацией. При
1128
+ изменении единиц outcome (например, переводе рублей в тысячи) `zeta_lambda`
1129
+ нужно масштабировать пропорционально. Если регуляризация зафиксирована, одно и
1130
+ то же значение следует передавать и в основной fit, и в FPR-проверку.
1131
+
1132
+ Не следует выбирать `zeta_lambda` только для того, чтобы получить FPR около 5%:
1133
+ регуляризация меняет time-weighted estimand. Сначала задайте сетку значений,
1134
+ сравните effective pre-periods, концентрацию top-3/top-5 весов, pre-fit и
1135
+ оценку эффекта, а затем зафиксируйте настройку до финального вывода.
1136
+
1137
+ В robustness можно опционально включить нативные проверки `diff-diff`:
1138
+
1139
+ ```python
1140
+ robust = run_synthetic_did_robustness(
1141
+ panel_df,
1142
+ outcome_col="revenue",
1143
+ unit_col="pizzeria",
1144
+ time_col="sale_date",
1145
+ treated_col="treated_flag",
1146
+ intervention_time="2026-02-01",
1147
+ diff_diff_checks=("in_time_placebo", "zeta_omega_sensitivity"),
1148
+ diff_diff_placebo_periods=["2025-12-15"],
1149
+ zeta_lambda_multipliers=(0.1, 1.0, 10.0, 100.0, 1_000.0, 10_000.0, 100_000.0),
1150
+ )
1151
+ ```
1152
+
1153
+ Доступные значения: `in_time_placebo`, `leave_one_out` (требует
1154
+ `variance_method="jackknife"`) и `zeta_omega_sensitivity`. По умолчанию
1155
+ `diff_diff_checks=()`, поэтому дополнительные нативные прогоны не выполняются.
1156
+ Параметр `zeta_lambda_multipliers` запускает отдельные полные SDiD-фиты для
1157
+ множителей автоматически выбранного `zeta_lambda`; по умолчанию он пустой,
1158
+ чтобы не увеличивать время расчёта. Результаты находятся в
1159
+ `details["zeta_lambda_sensitivity"]`, а графики — в
1160
+ `figures["zeta_lambda_sensitivity"]` и
1161
+ `figures["zeta_lambda_weight_concentration"]`. В таблице вместе с эффектом
1162
+ показываются ESS, доля effective pre-периодов, число положительных весов и
1163
+ накопленная доля top-3/top-5 time weights.
820
1164
 
821
1165
  ## Causal Impact: пример
822
1166
 
@@ -863,6 +1207,21 @@ ci_diag = check_causal_impact_assumptions(
863
1207
  donor_units=["Tbilisi", "Kutaisi"],
864
1208
  )
865
1209
 
1210
+ # Для Causal Impact доступны time placebo, block bootstrap и placebo units.
1211
+ ci_diag = check_causal_impact_assumptions(
1212
+ df=panel_df,
1213
+ outcome_col="metric",
1214
+ unit_col="unit",
1215
+ time_col="sale_date",
1216
+ treated_unit="Batumi",
1217
+ intervention_time="2026-02-25",
1218
+ donor_units=["Tbilisi", "Kutaisi"],
1219
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
1220
+ fpr_placebo_count=200,
1221
+ fpr_block_length=7,
1222
+ )
1223
+ print(ci_diag.details["fpr_results"])
1224
+
866
1225
  ci_result = fit_causal_impact(
867
1226
  df=panel_df,
868
1227
  outcome_col="metric",
@@ -1010,6 +1369,13 @@ its_result = fit_its(
1010
1369
  - placebo intervention dates
1011
1370
  - разные feature sets
1012
1371
 
1372
+ Для проверки эмпирической FPR у ITS доступен `fpr_method="time_placebo"`:
1373
+ пакет переоценивает модель на нескольких фиктивных датах вмешательства внутри
1374
+ предпериода. `placebo_units` для single-series ряда неприменим. Режим
1375
+ `block_bootstrap` для ITS не поддерживается; при его передаче будет `ValueError`.
1376
+ Число попыток задаётся `fpr_placebo_count`, а результаты сохраняются в
1377
+ `details["fpr_results"]`.
1378
+
1013
1379
  ## Стандартные проверки предпосылок
1014
1380
 
1015
1381
  Во всех `checks`-таблицах пакет теперь возвращает русские колонки:
@@ -1032,6 +1398,7 @@ its_result = fit_its(
1032
1398
  - хороший pre-fit
1033
1399
  - отсутствие contamination доноров
1034
1400
  - reasonable donor weights
1401
+ - in-space placebo FPR и permutation p-value
1035
1402
 
1036
1403
  ### Для Causal Impact
1037
1404
 
@@ -1131,6 +1498,9 @@ its_result = fit_its(
1131
1498
  - `fit_synthetic_control`
1132
1499
  - `check_synthetic_control_assumptions`
1133
1500
  - `run_synthetic_control_robustness`
1501
+ - `fit_synthetic_did`
1502
+ - `check_synthetic_did_assumptions`
1503
+ - `run_synthetic_did_robustness`
1134
1504
  - `fit_causal_impact`
1135
1505
  - `check_causal_impact_assumptions`
1136
1506
  - `run_causal_impact_robustness`
@@ -1148,6 +1518,19 @@ its_result = fit_its(
1148
1518
  `resampling` переобучает поддержанный расчет на каждом повторе
1149
1519
  - contamination и concurrent changes проверяются вручную, а не автоматически
1150
1520
 
1521
+ ## Планируемое развитие
1522
+
1523
+ Staggered Synthetic DiD пока не входит в публичный API. В roadmap предусмотрены
1524
+ два последовательных этапа:
1525
+
1526
+ 1. cohort-specific обёртка поверх `fit_synthetic_did` с отдельной оценкой по
1527
+ каждой дате начала воздействия и взвешенной агрегацией результатов;
1528
+ 2. современный staggered DiD estimator с корректными aggregate SE, p-value и
1529
+ confidence interval, а также явной диагностикой неоднородности эффектов.
1530
+
1531
+ До отдельной реализации и валидации эти функции не следует считать доступными
1532
+ или поддержанными в текущей версии пакета.
1533
+
1151
1534
  ## Версия
1152
1535
 
1153
1536
  Текущая версия пакета: `1.0.5`
@@ -46,6 +46,20 @@ python -m pip install post-analysis-toolkit
46
46
  - `notebooks/did_its_template.ipynb` — исполняемый шаблон DiD и ITS на искусственных данных.
47
47
  - `CHANGELOG.md` — история изменений.
48
48
 
49
+ ## Планируемое развитие
50
+
51
+ В будущих версиях планируется добавить staggered SDID поверх текущей
52
+ реализации Synthetic DiD в два этапа:
53
+
54
+ 1. cohort-specific обёртку: отдельная SDID-оценка для каждой когорты даты
55
+ воздействия и взвешенная агрегация cohort-эффектов;
56
+ 2. современный staggered DiD estimator с явно заданным estimand и корректной
57
+ aggregate SE, p-value и confidence interval, включая диагностику
58
+ неоднородности эффектов.
59
+
60
+ Это пока roadmap, а не доступный API: реализация и выбор точной методологии
61
+ будут сделаны отдельно после проверки на синтетических и реальных данных.
62
+
49
63
  ## Дополнительные материалы
50
64
 
51
65
  - [Статья о методологии в build.in](https://buildin.ai/82e65b2c-584b-423d-ad42-95492024aed8)