post-analysis-toolkit 1.0.7__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 (39) hide show
  1. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/PKG-INFO +337 -14
  2. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/README.md +14 -0
  3. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/notebooks/did_its_template.ipynb +2572 -480
  4. post_analysis_toolkit-1.0.9/notebooks/synthetic_did_databricks_template.ipynb +3285 -0
  5. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/MDE_METHODOLOGY.md +16 -7
  6. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/README.md +336 -13
  7. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/REFERENCE.html +189 -52
  8. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/REFERENCE.md +483 -43
  9. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/__init__.py +1 -1
  10. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/causal_impact.py +352 -38
  11. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/contracts.py +31 -6
  12. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/demo.py +57 -3
  13. post_analysis_toolkit-1.0.9/post_analysis_toolkit/did.py +2301 -0
  14. post_analysis_toolkit-1.0.9/post_analysis_toolkit/its.py +1183 -0
  15. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/observational.py +2 -0
  16. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/rdd.py +96 -3
  17. post_analysis_toolkit-1.0.9/post_analysis_toolkit/synthetic_control.py +1263 -0
  18. post_analysis_toolkit-1.0.9/post_analysis_toolkit/synthetic_did.py +1418 -0
  19. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/triple_difference.py +64 -10
  20. post_analysis_toolkit-1.0.9/post_analysis_toolkit/utils.py +1003 -0
  21. post_analysis_toolkit-1.0.9/post_analysis_toolkit/visualization.py +407 -0
  22. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/PKG-INFO +337 -14
  23. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/pyproject.toml +1 -1
  24. post_analysis_toolkit-1.0.7/notebooks/synthetic_did_databricks_template.ipynb +0 -1628
  25. post_analysis_toolkit-1.0.7/post_analysis_toolkit/did.py +0 -1168
  26. post_analysis_toolkit-1.0.7/post_analysis_toolkit/its.py +0 -696
  27. post_analysis_toolkit-1.0.7/post_analysis_toolkit/synthetic_control.py +0 -532
  28. post_analysis_toolkit-1.0.7/post_analysis_toolkit/synthetic_did.py +0 -621
  29. post_analysis_toolkit-1.0.7/post_analysis_toolkit/utils.py +0 -334
  30. post_analysis_toolkit-1.0.7/post_analysis_toolkit/visualization.py +0 -235
  31. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/MANIFEST.in +0 -0
  32. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/compat.py +0 -0
  33. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/mde.py +0 -0
  34. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit/mde_resampling.py +0 -0
  35. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/SOURCES.txt +0 -0
  36. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/dependency_links.txt +0 -0
  37. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/requires.txt +0 -0
  38. {post_analysis_toolkit-1.0.7 → post_analysis_toolkit-1.0.9}/post_analysis_toolkit.egg-info/top_level.txt +0 -0
  39. {post_analysis_toolkit-1.0.7 → 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.7
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
@@ -37,7 +37,7 @@ Requires-Dist: twine>=6.1; extra == "dev"
37
37
 
38
38
  - классический `Difference-in-Differences`
39
39
  - регрессионный `DiD`
40
- - `DiD` с `HC1` robust SE или cluster-robust SE
40
+ - `DiD` с cluster-robust SE по unit по умолчанию или `HC1` при явном `cluster_col=None`
41
41
  - `DiD` с `TWFE`
42
42
  - `DiD` с лог-трансформацией outcome
43
43
  - `DiD` с относительной индексацией outcome
@@ -54,6 +54,77 @@ Requires-Dist: twine>=6.1; extra == "dev"
54
54
  - базовые проверки устойчивости
55
55
  - встроенные `matplotlib`-графики
56
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
+
57
128
  ## MDE и чувствительность
58
129
 
59
130
  Для всех MDE по умолчанию используются `alpha=0.05`, `power=0.80` и
@@ -79,16 +150,17 @@ MDE относится к конкретному estimand и специфика
79
150
  генерирует оценки по схеме `delta + Normal(0, uncertainty_scale)`. Для
80
151
  регрессионных и observational-методов `uncertainty_scale` — SE. Для Event Study
81
152
  это SE конкретного коэффициента конкретного временного бина, поэтому MDE
82
- считается отдельно для каждого бина. Для
83
- Synthetic Control/Causal Impact/ITS — pre-fit или validation RMSE,
84
- нормированный на размер 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.
85
157
 
86
158
  В режиме `resampling` пакет создает псевдоданные: берет fitted/counterfactual
87
159
  значения без эффекта, добавляет ресэмплированные центрированные остатки и
88
160
  кандидатный эффект, а затем повторно запускает весь поддержанный оцениватель.
89
161
  Для Synthetic Control заново подбираются веса, для PSM заново строится matching,
90
- для Causal Impact заново обучается state-space модель, а для ITS заново
91
- оценивается регрессия. Такой режим заметно медленнее и требует явно задать
162
+ для Causal Impact заново обучается state-space модель, для ITS заново
163
+ оценивается регрессия, а для SDiD заново подбираются unit/time-веса. Такой режим заметно медленнее и требует явно задать
92
164
  разумное `n_simulations` и, при необходимости, `mde_effect_grid`.
93
165
 
94
166
  Power curve можно посмотреть в
@@ -389,9 +461,30 @@ did_diag = check_did_assumptions(
389
461
  intervention_time="2026-02-07",
390
462
  unit_col="unit",
391
463
  cluster_col="unit",
464
+ twfe=True,
392
465
  )
393
466
  print(did_diag.checks)
394
467
 
468
+ # Можно сравнить несколько эмпирических FPR-процедур одновременно.
469
+ did_diag = check_did_assumptions(
470
+ did_df,
471
+ outcome_col="metric",
472
+ time_col="sale_date",
473
+ treated_col="treated_flag",
474
+ post_col="post_flag",
475
+ intervention_time="2026-02-07",
476
+ unit_col="unit",
477
+ cluster_col="unit",
478
+ twfe=True,
479
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
480
+ fpr_placebo_count=200,
481
+ fpr_block_length=7,
482
+ )
483
+ print(did_diag.details["fpr_results"])
484
+
485
+ # Важно: FPR-процедуры должны получать ту же спецификацию, что и оценка
486
+ # эффекта (например, twfe=True, одинаковые covariates/log_transform/relative).
487
+
395
488
  did_result = fit_did_regression(
396
489
  did_df,
397
490
  outcome_col="metric",
@@ -449,8 +542,12 @@ sc_diag = check_synthetic_control_assumptions(
449
542
  time_col="sale_date",
450
543
  treated_unit="Batumi",
451
544
  intervention_time="2026-02-08",
545
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
546
+ fpr_placebo_count=20,
547
+ fpr_block_length=7,
452
548
  )
453
549
  print(sc_diag.checks)
550
+ print(sc_diag.details["fpr_results"])
454
551
 
455
552
  sc_result = fit_synthetic_control(
456
553
  sc_df,
@@ -502,6 +599,18 @@ its_diag = check_its_assumptions(
502
599
  )
503
600
  print(its_diag.checks)
504
601
 
602
+ # Для ITS доступен time placebo; placebo_units
603
+ # неприменим, потому что это single-series метод без units.
604
+ its_diag = check_its_assumptions(
605
+ its_df,
606
+ outcome_col="metric",
607
+ time_col="sale_date",
608
+ intervention_time="2026-01-11",
609
+ fpr_method="time_placebo",
610
+ fpr_placebo_count=200,
611
+ )
612
+ print(its_diag.details["fpr_results"])
613
+
505
614
  its_result = fit_its(
506
615
  its_df,
507
616
  outcome_col="metric",
@@ -517,6 +626,26 @@ its_robust = run_its_robustness(
517
626
  intervention_time="2026-01-11",
518
627
  )
519
628
  print(its_robust.summary)
629
+
630
+ # Для panel ITS можно выбрать кластеризацию по unit и два уровня unit × time.
631
+ panel_its = fit_its(
632
+ panel_df,
633
+ outcome_col="outcome",
634
+ time_col="sale_date",
635
+ intervention_time="2026-02-01",
636
+ se_type="cluster",
637
+ cluster_col="unit",
638
+ )
639
+ panel_its_two_way = fit_its(
640
+ panel_df,
641
+ outcome_col="outcome",
642
+ time_col="sale_date",
643
+ intervention_time="2026-02-01",
644
+ se_type="two_way_cluster",
645
+ cluster_col="unit",
646
+ time_cluster_col="sale_date",
647
+ )
648
+ # Для HAC sensitivity автоматически перебираются 0, 3, 7 и 14 лагов.
520
649
  ```
521
650
 
522
651
  ### 4. End-to-end пример: PSM
@@ -744,6 +873,51 @@ did_robust = run_did_robustness(
744
873
  - с логами и без
745
874
  - с относительной индексацией и без
746
875
 
876
+ Для отдельной динамики эффекта используется Event Study. В его проверке
877
+ предпосылок FPR считается по joint Wald-тесту всех post-бинов (а не по
878
+ минимальному p-value отдельного бина):
879
+
880
+ ```python
881
+ from post_analysis_toolkit import check_event_study_assumptions, fit_event_study
882
+
883
+ event_diag = check_event_study_assumptions(
884
+ panel_df,
885
+ outcome_col="metric",
886
+ time_col="sale_date",
887
+ treated_col="treated_flag",
888
+ intervention_time="2026-02-25",
889
+ unit_col="unit",
890
+ cluster_col="unit",
891
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
892
+ fpr_placebo_count=200,
893
+ fpr_block_length=7,
894
+ )
895
+ event_result = fit_event_study(
896
+ panel_df,
897
+ outcome_col="metric",
898
+ time_col="sale_date",
899
+ treated_col="treated_flag",
900
+ intervention_time="2026-02-25",
901
+ unit_col="unit",
902
+ cluster_col="unit",
903
+ event_bin_size=7,
904
+ )
905
+ ```
906
+
907
+ В `event_result.details["event_study_summary"]` доступны
908
+ `joint_pre_p_value` и `joint_post_p_value`; FPR-таблица находится в
909
+ `event_diag.details["fpr_results"]`. MDE по каждому event-бину можно получить
910
+ уже на этапе проверки предпосылок:
911
+
912
+ ```python
913
+ display(event_diag.details["event_study_mde"])
914
+ ```
915
+
916
+ Для расчёта MDE на этом этапе используются те же параметры, что и в
917
+ `fit_event_study` (`mde_mode`, `power`, `alternative`, `n_simulations`,
918
+ `random_state`, `mde_effect_grid`, `mde_simulator`). По умолчанию `mde_mode="auto"`
919
+ выбирает аналитический MDE по стандартной ошибке каждого event-бина.
920
+
747
921
  ## Synthetic Control: пример
748
922
 
749
923
  ### Формат данных для функции
@@ -785,8 +959,21 @@ synth_diag = check_synthetic_control_assumptions(
785
959
  treated_unit="Batumi",
786
960
  intervention_time="2026-02-25",
787
961
  donor_units=["Tbilisi", "Kutaisi"],
962
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
963
+ fpr_placebo_count=20,
964
+ fpr_block_length=7,
788
965
  )
966
+ print(synth_diag.details["fpr_results"])
967
+
968
+ ```
969
+
970
+ Помимо in-space `placebo_units`, Synthetic Control поддерживает
971
+ `time_placebo` (фиктивные даты внутри предпериода) и `block_bootstrap`
972
+ (нулевые панели из общих временных блоков). Подробные результаты находятся в
973
+ `details["time_placebo_results"]` и `details["block_bootstrap_results"]`;
974
+ план доступных прогонов — в `details["fpr_plan"]`.
789
975
 
976
+ ```python
790
977
  synth_result = fit_synthetic_control(
791
978
  df=panel_df,
792
979
  outcome_col="metric",
@@ -817,11 +1004,35 @@ synth_robust = run_synthetic_control_robustness(
817
1004
  - `avg_post_effect`
818
1005
  - `avg_post_relative_effect`
819
1006
  - таблицу весов `details["weights"]`
1007
+ - `details["weight_concentration"]` с min/max весом, effective donors,
1008
+ числом доноров с положительным весом и долей веса крупнейшего донора
1009
+ - `details["fpr_results"]` с in-space FPR и permutation p-value
820
1010
 
821
1011
  Проверки устойчивости:
822
1012
 
823
1013
  - placebo по каждому донору
824
1014
  - leave-one-out по донорам
1015
+ - in-space placebo-калибровка FPR в `check_synthetic_control_assumptions`
1016
+ - `time_placebo` с фиктивными датами внутри предпериода
1017
+ - `block_bootstrap` с нулевыми панелями из общих временных блоков
1018
+
1019
+ Для Synthetic Control нет модельного p-value/SE. In-space FPR по очереди
1020
+ делает каждого донора псевдотритментом, сравнивает post/pre RMSPE-ratio с
1021
+ остальными донорами и возвращает permutation p-value исходной treated unit.
1022
+ `time_placebo` переносит дату вмешательства внутрь предпериода, а
1023
+ `block_bootstrap` создаёт нулевые панели, ресэмплируя общие временные блоки.
1024
+ В обоих случаях значимость всё равно определяется in-space permutation по
1025
+ RMSPE-ratio, а не обычной модельной SE. Число успешных `placebo_units`
1026
+ прогонов не может быть больше размера donor pool; для остальных методов
1027
+ ограничение задаётся числом допустимых дат или успешных bootstrap-прогонов.
1028
+ Для содержательной калибровки желательно иметь минимум три донора: при
1029
+ маленьком donor pool permutation p-value дискретен и FPR получается грубой
1030
+ диагностикой.
1031
+
1032
+ Концентрация donor weights не является автоматическим pass/fail-критерием.
1033
+ Если `top1_weight_share` близка к 100% или `effective_donors` близко к 1,
1034
+ нужно дополнительно проверить `leave_one_out_results` и устойчивость к
1035
+ расширению/очистке donor pool.
825
1036
 
826
1037
  ## Synthetic DiD (SDiD)
827
1038
 
@@ -851,18 +1062,85 @@ display(sdid_result.figures["actual_vs_counterfactual"])
851
1062
 
852
1063
  `treated_col` должен быть бинарным и постоянным внутри unit. Основные поля
853
1064
  `summary`: `effect_absolute`, `effect_relative`, `effect_cumulative`,
854
- `effect_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
1065
+ `effect_ci`, `effect_relative_ci`, `effect_cumulative_ci`, `std_error`, `p_value`, `mde_absolute`, `mde_relative`,
855
1066
  `mde_cumulative`, `mde_mode_resolved`.
856
1067
 
1068
+ Для SDiD доступны `mde_mode="analytic"`, `"parametric"`, `"resampling"` и
1069
+ `"proxy"`. В `resampling` можно передать `mde_simulator`; если он не задан,
1070
+ пакет автоматически строит residual-bootstrap pipeline и повторно вызывает
1071
+ `diff-diff` для каждой симулированной панели.
1072
+
857
1073
  В `details["unit_weights"]` и `details["time_weights"]` доступны полные
858
1074
  списки весов. В `details["weight_concentration"]` пакет дополнительно
859
- показывает min/max и эффективное число доноров и pre-периодов. Это
860
- описательные метрики без автоматически заданных порогов.
1075
+ показывает min/max, эффективное число доноров и pre-периодов, общее число
1076
+ pre-периодов, число периодов с положительным time weight, долю effective
1077
+ pre-периодов и долю веса трёх/пяти самых важных периодов. Это описательные
1078
+ метрики без автоматически заданных порогов; `effective_pre_periods` — это
1079
+ ESS по time weights, а не буквальное число использованных дат.
1080
+
1081
+ В `details["series"]` сохраняются сырые `counterfactual`/`gap` и
1082
+ level-shift-adjusted `counterfactual_level_adjusted`/`gap_level_adjusted`.
1083
+ `effect_cumulative` и графики SDiD используют adjusted gap, чтобы не включать
1084
+ допустимую постоянную разницу уровней в оценку инкрементального эффекта.
861
1085
 
862
1086
  Для SDiD поддерживаются `variance_method="placebo"`, `"bootstrap"` и
863
- `"jackknife"`. Режим MDE `auto` разрешается в параметрическую симуляцию;
864
- `parametric` и `proxy` доступны напрямую. Аналитический MDE и полный
865
- повторный resampling MDE пока не включены.
1087
+ `"jackknife"`. Режим MDE `auto` при корректной SE от `diff-diff` выбирает
1088
+ аналитический plug-in расчёт; `analytic` можно задать явно. Это не закрытая
1089
+ SDiD-формула дизайн-мощности: unit/time weights оцениваются на исходных
1090
+ данных, а MDE использует итоговую inferential SE. `parametric` делает быстрые
1091
+ симуляции оценок с той же SE, `proxy` использует level-shift-adjusted pre-fit
1092
+ RMSE. `resampling` строит псевдопанели, добавляет эффект к treated-юнитам в
1093
+ post-периоде и заново оценивает SDiD вместе с unit/time-весами на каждом
1094
+ прогоне; это точнее, но существенно медленнее.
1095
+
1096
+ `effect_ci` — доверительный интервал взвешенного ATT от `diff-diff`.
1097
+ `effect_relative_ci` и `effect_cumulative_ci` — plug-in преобразования этого
1098
+ интервала для относительного (со знаком `%`) и cumulative estimand; дополнительная
1099
+ неопределённость baseline и level-shift alignment в них не моделируется.
1100
+
1101
+ В `check_synthetic_did_assumptions(...)` параметр `fpr_placebo_count` задаёт
1102
+ число placebo-прогонов. Если передать `zeta_omega` или `zeta_lambda`, эта же
1103
+ регуляризация будет использована и в основном fit, и во всех placebo-fit —
1104
+ это позволяет честно сравнивать эмпирическую FPR между вариантами
1105
+ `zeta_lambda`.
1106
+
1107
+ Параметр `fpr_method` принимает одну строку или список методов: `time_placebo`
1108
+ (fake intervention даты внутри pre-period), `block_bootstrap` (ресэмплинг
1109
+ общих временных блоков без эффекта) и `placebo_units` (формирование placebo-
1110
+ treated групп контрольных пиццерий того же размера, что и исходная treated-
1111
+ группа). Можно передать несколько методов сразу,
1112
+ например `fpr_method=("time_placebo", "block_bootstrap", "placebo_units")`.
1113
+ Для block bootstrap длина блока задаётся `fpr_block_length` (по умолчанию 7).
1114
+ Сводка по каждому методу находится в `details["fpr_results"]`; при выборе
1115
+ нескольких методов добавляются method-specific строки в `checks` и график
1116
+ `figures["fpr_comparison"]`. `fpr_placebo_count` используется как число
1117
+ попыток для time placebo/block bootstrap и как максимум контрольных units для
1118
+ placebo units; фактический знаменатель находится в колонке `runs`, а размер
1119
+ placebo-группы — в `placebo_group_size`.
1120
+
1121
+ Практический порядок работы: сначала запустите
1122
+ `check_synthetic_did_assumptions(...)` и посмотрите одновременно на FPR и
1123
+ `details["weight_concentration"]`. Если FPR заметно выше заданного `alpha`, а
1124
+ `effective_pre_periods` мало и top-3 time weights забирают большую долю веса,
1125
+ повторите основной fit и проверку с явно заданным большим `zeta_lambda`:
1126
+
1127
+ ```python
1128
+ sdid_result = fit_synthetic_did(..., zeta_lambda=25_000.0)
1129
+ sdid_checks = check_synthetic_did_assumptions(
1130
+ ..., zeta_lambda=25_000.0,
1131
+ )
1132
+ ```
1133
+
1134
+ Это не универсальный порог: значение зависит от масштаба outcome и должно
1135
+ выбираться по sensitivity-таблице вместе с предметной интерпретацией. При
1136
+ изменении единиц outcome (например, переводе рублей в тысячи) `zeta_lambda`
1137
+ нужно масштабировать пропорционально. Если регуляризация зафиксирована, одно и
1138
+ то же значение следует передавать и в основной fit, и в FPR-проверку.
1139
+
1140
+ Не следует выбирать `zeta_lambda` только для того, чтобы получить FPR около 5%:
1141
+ регуляризация меняет time-weighted estimand. Сначала задайте сетку значений,
1142
+ сравните effective pre-periods, концентрацию top-3/top-5 весов, pre-fit и
1143
+ оценку эффекта, а затем зафиксируйте настройку до финального вывода.
866
1144
 
867
1145
  В robustness можно опционально включить нативные проверки `diff-diff`:
868
1146
 
@@ -876,12 +1154,21 @@ robust = run_synthetic_did_robustness(
876
1154
  intervention_time="2026-02-01",
877
1155
  diff_diff_checks=("in_time_placebo", "zeta_omega_sensitivity"),
878
1156
  diff_diff_placebo_periods=["2025-12-15"],
1157
+ zeta_lambda_multipliers=(0.1, 1.0, 10.0, 100.0, 1_000.0, 10_000.0, 100_000.0),
879
1158
  )
880
1159
  ```
881
1160
 
882
1161
  Доступные значения: `in_time_placebo`, `leave_one_out` (требует
883
1162
  `variance_method="jackknife"`) и `zeta_omega_sensitivity`. По умолчанию
884
- `diff_diff_checks=()`, поэтому дополнительные прогоны не выполняются.
1163
+ `diff_diff_checks=()`, поэтому дополнительные нативные прогоны не выполняются.
1164
+ Параметр `zeta_lambda_multipliers` запускает отдельные полные SDiD-фиты для
1165
+ множителей автоматически выбранного `zeta_lambda`; по умолчанию он пустой,
1166
+ чтобы не увеличивать время расчёта. Результаты находятся в
1167
+ `details["zeta_lambda_sensitivity"]`, а графики — в
1168
+ `figures["zeta_lambda_sensitivity"]` и
1169
+ `figures["zeta_lambda_weight_concentration"]`. В таблице вместе с эффектом
1170
+ показываются ESS, доля effective pre-периодов, число положительных весов и
1171
+ накопленная доля top-3/top-5 time weights.
885
1172
 
886
1173
  ## Causal Impact: пример
887
1174
 
@@ -928,6 +1215,21 @@ ci_diag = check_causal_impact_assumptions(
928
1215
  donor_units=["Tbilisi", "Kutaisi"],
929
1216
  )
930
1217
 
1218
+ # Для Causal Impact доступны time placebo, block bootstrap и placebo units.
1219
+ ci_diag = check_causal_impact_assumptions(
1220
+ df=panel_df,
1221
+ outcome_col="metric",
1222
+ unit_col="unit",
1223
+ time_col="sale_date",
1224
+ treated_unit="Batumi",
1225
+ intervention_time="2026-02-25",
1226
+ donor_units=["Tbilisi", "Kutaisi"],
1227
+ fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
1228
+ fpr_placebo_count=200,
1229
+ fpr_block_length=7,
1230
+ )
1231
+ print(ci_diag.details["fpr_results"])
1232
+
931
1233
  ci_result = fit_causal_impact(
932
1234
  df=panel_df,
933
1235
  outcome_col="metric",
@@ -1075,6 +1377,13 @@ its_result = fit_its(
1075
1377
  - placebo intervention dates
1076
1378
  - разные feature sets
1077
1379
 
1380
+ Для проверки эмпирической FPR у ITS доступен `fpr_method="time_placebo"`:
1381
+ пакет переоценивает модель на нескольких фиктивных датах вмешательства внутри
1382
+ предпериода. `placebo_units` для single-series ряда неприменим. Режим
1383
+ `block_bootstrap` для ITS не поддерживается; при его передаче будет `ValueError`.
1384
+ Число попыток задаётся `fpr_placebo_count`, а результаты сохраняются в
1385
+ `details["fpr_results"]`.
1386
+
1078
1387
  ## Стандартные проверки предпосылок
1079
1388
 
1080
1389
  Во всех `checks`-таблицах пакет теперь возвращает русские колонки:
@@ -1097,6 +1406,7 @@ its_result = fit_its(
1097
1406
  - хороший pre-fit
1098
1407
  - отсутствие contamination доноров
1099
1408
  - reasonable donor weights
1409
+ - in-space placebo FPR и permutation p-value
1100
1410
 
1101
1411
  ### Для Causal Impact
1102
1412
 
@@ -1216,6 +1526,19 @@ its_result = fit_its(
1216
1526
  `resampling` переобучает поддержанный расчет на каждом повторе
1217
1527
  - contamination и concurrent changes проверяются вручную, а не автоматически
1218
1528
 
1529
+ ## Планируемое развитие
1530
+
1531
+ Staggered Synthetic DiD пока не входит в публичный API. В roadmap предусмотрены
1532
+ два последовательных этапа:
1533
+
1534
+ 1. cohort-specific обёртка поверх `fit_synthetic_did` с отдельной оценкой по
1535
+ каждой дате начала воздействия и взвешенной агрегацией результатов;
1536
+ 2. современный staggered DiD estimator с корректными aggregate SE, p-value и
1537
+ confidence interval, а также явной диагностикой неоднородности эффектов.
1538
+
1539
+ До отдельной реализации и валидации эти функции не следует считать доступными
1540
+ или поддержанными в текущей версии пакета.
1541
+
1219
1542
  ## Версия
1220
1543
 
1221
1544
  Текущая версия пакета: `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)