Документация Post Analysis Toolkit

Установка

В ноутбуке или Python-скрипте

%pip install post-analysis-toolkit

Один раз на персональном Databricks-кластере

В настройках кластера откройте Libraries, добавьте библиотеку из PyPI с именем post-analysis-toolkit и установите её. После запуска кластера пакет будет доступен во всех его ноутбуках и Python-задачах.

Объекты результатов

Как связаны функции и result-объекты

Практическое правило:

• Если функция начинается с check_, почти всегда сначала смотри diag.checks.
• Если функция начинается с fit_, почти всегда сначала смотри result.summary.
• Если функция начинается с run_ и заканчивается на _robustness, сначала смотри robust.summary, потом уже детальные таблицы и графики.

Типовой паттерн использования

diag = check_did_assumptions(...)
display(diag.checks)

result = fit_did_regression(...)
display(result.summary)
display(result.details["coefficients"])

robust = run_did_robustness(...)
display(robust.summary)

Стандартные ошибки и кластеризация

Для регрессионных DiD, Event Study, DDD и RDD кластеризация включена по умолчанию: cluster_col="auto" сначала использует unit_col, а затем ищет стандартную колонку unit, unit_id, pizzeria, city или cluster. Явное cluster_col=None отключает кластеризацию и включает HC1. Если подходящая колонка не найдена, auto откатывается к HC1. Для регрессионных методов можно выбрать se_type="hc1", "cluster", "cr2", "cr3", "wild_cluster" или "two_way_cluster" (Cameron–Gelbach–Miller, unit × time); второй уровень задаётся time_cluster_col или по умолчанию берётся из time_col.

Параметр cluster_col выбирает колонку, по которой группируются наблюдения, а se_type — тип covariance estimator. Значение "auto" выбирает прежнее поведение, а cluster_col=None при se_type="auto" явно оставляет HC1. При небольшом числе кластеров cluster-robust p-value и FPR могут быть нестабильны; сопоставляйте их с placebo/FPR и sensitivity-проверками. Фактический режим можно проверить в result.metadata["stderr_type"], а для ITS также посмотреть result.metadata["hac_lags"]. One-way cluster covariance — CR1-style с finite-sample correction; p-value по умолчанию использует normal approximation (use_t=False). CR2 применяет (I-H_g)^(-1/2), CR3 — (I-H_g)^(-1) к cluster scores. Wild-cluster bootstrap использует Rademacher residual flips и число повторов wild_bootstrap_reps (по умолчанию 999); это оценка covariance, а не отдельный null-imposed bootstrap-тест p-value.

Для se_type="wild_cluster" во всех регрессионных fit_* доступны wild_bootstrap_reps (по умолчанию 999) и random_state. Параметр wild_bootstrap_reps также доступен в соответствующих check_*_assumptions и run_*_robustness и передаётся во внутренние переоценки.

Для check_rdd_assumptions диагностические density-регрессии остаются HC1, а continuity-регрессии используют выбранный se_type. Двухсторонняя covariance-оценка использует inclusion–exclusion и при необходимости PSD-проекцию как численную страховку.

Как выбирать hac_lags в ITS

hac_lags — максимальный лаг автокорреляции, учитываемый в HAC/Newey–West ковариации. Значение 7 разумно как стартовая настройка для ежедневных данных с недельной сезонностью, но не является универсальным. Слишком маленькое значение может занизить SE при длинной зависимости, а слишком большое — сделать интервалы чрезмерно широкими и нестабильными.

Практический выбор: начать с ожидаемого сезонного периода, проверить соседние значения (например, 0, 3, 7, 14) в sensitivity-анализе и убедиться, что вывод об эффекте не меняется. run_its_robustness делает такой перебор автоматически. При явном se_type="auto" ITS выбирает cluster, если найден cluster_col, иначе HAC; значение по умолчанию для ITS — se_type="hac", поэтому auto нужно указывать явно.

Общие соглашения по данным

• time_col должен корректно парситься через pandas.to_datetime.
• Бинарные флаги ожидаются в формате 0/1.
• Outcome и covariates должны быть числовыми.
• Для PSM и Doubly Robust категориальные covariates нужно заранее закодировать.
• Графики, которые возвращает пакет, это matplotlib figures.

Графики actual_vs_counterfactual и gap_series отмечают дату интервенции, подсвечивают постпериод и подписывают оси временем и единицами outcome. Для панельного ITS линии строятся по среднему значению по календарной дате.

Расшифровка output-таблиц

После вызова fit_* основные результаты находятся в result.summary. Набор колонок зависит от метода, а MDE-поля имеют общий смысл.

Ключевые поля по методам

MDE и чувствительность

Стандартные настройки

По умолчанию используются alpha=0.05, power=0.80 и двусторонний тест alternative="two-sided". Если метрика и дизайн допускают аналитическую оценку, базовый ориентир — t-test через корректную стандартную ошибку.

MDE относится к конкретному estimand. В результате нужно отдельно показывать абсолютный, относительный и cumulative MDE.

Где смотреть MDE

MDE находится в result.summary соответствующей fit_*-функции.

Поля с префиксом proxy_mde — это быстрый screening, а не строгий MDE конкретного сложного дизайна.

Режимы MDE

Как именно выполняются текущие симуляции

Для каждой точки сетки абсолютных эффектов delta пакет генерирует n_simulations оценок по схеме:

simulated_estimate = delta + Normal(0, uncertainty_scale)

uncertainty_scale равен SE для DiD, Event Study, DDD, RDD, PSM и Doubly Robust. Для Event Study это стандартная ошибка конкретного коэффициента конкретного временного бина, поэтому MDE строится отдельно для каждого бина. Для Synthetic Control и Causal Impact он строится из ошибки префита/валидации: pre-fit RMSE / sqrt(n_post) или validation RMSE / sqrt(n_post). Для ITS fit_its передаёт delta-method SE среднего post-period gap; если она недоступна, используется validation RMSE как fallback.

Для каждого delta считается доля симуляций, где нулевая гипотеза отвергнута. Это estimated power. В таблице есть и effect_relative — эффект относительно baseline. Например, effect_absolute=2000, effect_relative=0.02, estimated_power=0.81 означает мощность около 81% при эффекте 2% от baseline. Таблица power curve доступна в result.details["mde_power_curve"], а минимальный delta, достигший целевой мощности, записывается в result.summary["mde_absolute"].

Ошибка прогноза: RMSE остаётся основной метрикой ошибки и noise scale для MDE. Для интерпретации используется относительный RMSE: RMSE, делённый на средний уровень метрики в предпериоде.

Параметрический режим не создает новые строки исходного датафрейма и не переобучает полный pipeline на каждом повторе. Поэтому не выполняются повторный подбор доноров, matching, оптимизация весов Synthetic Control, state-space fit Causal Impact или полный пересчет ITS. Это быстрый MDE на основе параметрической симуляции.

Режим mde_mode="resampling" создает псевдоданные вокруг fitted/counterfactual значений без эффекта, ресэмплирует центрированные остатки, добавляет кандидатный эффект и заново запускает оцениватель. Для нестандартного pipeline можно передать mde_simulator с сигнатурой (effect, rng, n_simulations) -> array[estimate].

Для воспроизводимости используется random_state; для собственной сетки эффектов — mde_effect_grid.

Для параметрического и resampling-режимов число повторов задается параметром n_simulations: 500 для отладки, 2000 для рабочего расчета и 5000+ для финального отчета. В результатах нужно сохранять alpha, power, alternative, n_simulations, random_state, power curve и три формы MDE.

Difference-in-Differences (DiD)

Формат данных для функции

compute_classic_did(...)

compute_classic_did(
    df, outcome_col, treated_col, post_col,
    weight_col=None, label="classic_did",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None, mde_simulator=None,
)

Возвращает summary с 2x2 cell means и эффектом, а также details["cell_means"].

Параметры MDE

fit_did_regression(...)

fit_did_regression(
    df, outcome_col, time_col, treated_col, post_col,
    covariates=None, cluster_col="auto", unit_col=None,
    twfe=False, log_transform=False, relative=False,
    weight_col=None, label="did_regression",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None, se_type="auto", time_cluster_col=None,
)

Возвращает summary по эффекту, коэффициенты и analysis frame.

Параметры MDE

check_did_assumptions(...)

fpr_placebo_count задаёт число placebo-прогонов для эмпирической FPR; по умолчанию 20. fpr_method принимает time_placebo, block_bootstrap и placebo_units; можно передать список методов. Для block bootstrap длина блока задаётся fpr_block_length. placebo_units требует unit_col и формирует placebo-treated группы того же размера, что и фактическая treated-группа. Размер группы выводится в placebo_group_size. Результаты находятся в details["fpr_results"], а при нескольких методах добавляется figures["fpr_comparison"].

До тяжёлого цикла пакет строит details["fpr_plan"] с доступным структурным максимумом и заранее предупреждает, если запрос превышает его. В сводке сохраняются failed/skipped прогоны и timing-поля; подробности ошибок доступны в details["fpr_run_log"] и не печатаются автоматически.

check_did_assumptions(
    df, outcome_col, time_col, treated_col, post_col,
    intervention_time, unit_col=None, cluster_col="auto",
    event_bin_size=7, fpr_placebo_count=20, label="did_assumptions",
    alpha=0.05, fpr_method="time_placebo", fpr_block_length=7,
    se_type="auto", time_cluster_col=None, wild_bootstrap_reps=999,
    covariates=None, twfe=False, log_transform=False,
    relative=False, weight_col=None,
)

Для корректной калибровки FPR передавайте те же параметры спецификации, что и в оценке эффекта. Например, если эффект считается через TWFE, используйте twfe=True и в check_did_assumptions: placebo-прогоны тогда переоценивают ту же модель, меняя только placebo-дату или placebo-назначение treatment.

Что проверяет: визуальную форму предпериода, разницу наклонов и корреляцию на предпериоде, joint-test лидов через event study, стабильность состава и явные параллельные изменения. Передавайте в check_did_assumptions ту же спецификацию (twfe, ковариаты, преобразования и веса), что и в оценку эффекта: она повторяется во всех placebo-прогонах. При placebo_units размер placebo-treated группы автоматически совпадает с числом фактических treated units; он выводится в placebo_group_size.

Возвращает локализованные проверки, event-study таблицы и диагностические графики. FPR можно считать через time_placebo, block_bootstrap и, при наличии unit_col, placebo_units; несколько методов передаются списком, а сводка сохраняется в details["fpr_results"].

run_did_robustness(...)

run_did_robustness(
    df, outcome_col, time_col, treated_col, post_col,
    intervention_time=None, unit_col=None, cluster_col="auto",
    twfe_options=(False, True), log_options=(False, True),
    relative_options=(False, True), placebo_offsets_days=(28, 21, 14),
    pre_period_days_options=(None, 28, 56, 84),
    se_type="auto", time_cluster_col=None,
)

Как проверяет устойчивость: перебирает спецификации twfe / log / relative, сравнивает эффект между ними и делает placebo-прогоны на предпериоде с псевдо-датами интервенции.

Event Study

Формат данных для функции

Event Study — самостоятельная регрессионная оценка динамики эффекта. Она возвращает отдельную оценку для каждого временного бина относительно пропущенного эталонного бина. Средний и кумулятивный post-эффект дополнительно доступны в result.details["aggregate_effect"] и выводятся вертикальной таблицей в шаблоне ноутбука.

fit_event_study(...)

fit_event_study(
    df, outcome_col, time_col, treated_col, intervention_time,
    unit_col=None, cluster_col="auto", event_bin_size=7, reference_bin=-1,
    covariates=None, label="event_study", mde_mode="auto",
    alpha=0.05, power=0.80, alternative="two-sided",
    n_simulations=2000, random_state=None, mde_effect_grid=None,
    mde_simulator=None, se_type="auto", time_cluster_col=None,
)

Параметры MDE

В summary одна строка соответствует одному event-бину и содержит эффект, доверительный интервал, p-value и MDE. В details["aggregate_effect"] находятся средний, относительный и кумулятивный post-эффекты. В details["event_study_summary"] лежит общий joint-тест лидов и joint-тест всех post-бинов (joint_post_wald_stat, joint_post_p_value). Малый p-value joint post-теста означает, что эффект обнаружен хотя бы в одном post-бине; его практическую величину нужно смотреть по aggregate-метрикам, CI и MDE. Для pre-бинов нет универсального порога у max_abs_pre_coef: дополнительно используйте относительные поля max_abs_pre_coef_relative/avg_abs_pre_coef_relative, CI и baseline.

check_event_study_assumptions(...) и run_event_study_robustness(...)

check_event_study_assumptions проверяет reference-бин, число pre/post-бинов, joint-тест pre-period коэффициентов, joint-тест post-бинов и максимальный абсолютный pre-period коэффициент. FPR считается по joint Wald-тесту всех post-бинов, а не по минимальному p-value отдельного бина. На этом же этапе MDE рассчитывается отдельно для каждого event-бина и сохраняется в details["event_study_mde"]; для вывода доступны mde_absolute, mde_relative и mde_cumulative. Параметры mde_mode, power, alternative, n_simulations, random_state, mde_effect_grid и mde_simulator совпадают с fit_event_study; при mde_mode="auto" используется аналитический MDE, если доступна SE. fpr_method принимает time_placebo, block_bootstrap и placebo_units; можно передать несколько методов сразу. Число попыток задаётся fpr_placebo_count, длина блока — fpr_block_length. Результаты находятся в details["fpr_results"], а при нескольких методах добавляется figures["fpr_comparison"]. run_event_study_robustness повторяет оценку для разных размеров event-бина, reference-бинов и окон предпериода. Результаты sensitivity лежат в robust.summary и robust.details["sensitivity"].

check_event_study_assumptions(
    panel_df, outcome_col="revenue", time_col="sale_date",
    treated_col="treated_flag", intervention_time="2026-02-01",
    unit_col="pizzeria", cluster_col="pizzeria",
    fpr_method=("time_placebo", "block_bootstrap", "placebo_units"),
    fpr_placebo_count=200, fpr_block_length=7,
    mde_mode="auto", power=0.80,
    se_type="auto", time_cluster_col=None,
)

MDE из диагностического результата можно вывести отдельно: display(event_diag.details["event_study_mde"]).

Triple Difference (DDD)

Формат данных для функции

fit_triple_difference(...)

fit_triple_difference(
    df, outcome_col, time_col, treated_col, post_col, subgroup_col,
    covariates=None, cluster_col="auto", unit_col=None,
    twfe=False, log_transform=False, relative=False,
    label="triple_difference",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None, se_type="auto", time_cluster_col=None,
)

Параметры MDE

check_triple_difference_assumptions(...)

check_triple_difference_assumptions(
    df, outcome_col, time_col, treated_col, post_col, subgroup_col,
    intervention_time, unit_col, cluster_col="auto",
    event_bin_size=7, label="triple_difference_assumptions",
    se_type="auto", time_cluster_col=None,
)

Что проверяет: полноту ячеек subgroup внутри unit x time, тренды subgroup gap на предпериоде, event-study лиды для этого gap, стабильность состава и параллельные изменения.

run_triple_difference_robustness(...)

run_triple_difference_robustness(
    df, outcome_col, time_col, treated_col, post_col, subgroup_col,
    intervention_time=None, unit_col=None, cluster_col="auto",
    twfe_options=(False, True), log_options=(False, True),
    relative_options=(False, True), placebo_offsets_days=(28, 21, 14),
    pre_period_days_options=(None, 28, 56, 84),
)

Как проверяет устойчивость: перебирает DDD-спецификации twfe / log / relative, сравнивает стабильность тройного коэффициента и делает placebo-прогоны на предпериоде.

Synthetic Control

Формат данных для функции

fit_synthetic_control(...)

fit_synthetic_control(
    df, outcome_col, unit_col, time_col, treated_unit, intervention_time,
    donor_units=None, max_controls=10, nonnegative_weights=True,
    label="synthetic_control",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None,
)

Возвращает summary, веса, выровненные ряды, описательную таблицу концентрации весов и два графика: actual/counterfactual и gap.

details["weight_concentration"] содержит donor_weight_min, donor_weight_max, effective_donors, positive_donors и top1_weight_share. Это описательные метрики без автоматического pass/fail-порога.

Параметры MDE

check_synthetic_control_assumptions(...)

check_synthetic_control_assumptions(
    df, outcome_col, unit_col, time_col, treated_unit,
    intervention_time, donor_units=None, max_controls=10,
    fpr_placebo_count=20, alpha=0.05,
    fpr_method="placebo_units", fpr_block_length=7,
)

В checks также выводятся donor_weight_min, donor_weight_max, effective_donors, positive_donors и top1_weight_share. Это описательные метрики без жёсткого автоматического порога: при высокой концентрации нужно дополнительно смотреть details["weights"] и leave-one-out результаты robustness-прогона.

Что проверяет: размер и чистоту donor pool, качество pre-fit synthetic ряда, риск загрязнения donor pool treated-изменениями и эмпирическую FPR через выбранные placebo-процедуры. В details["fpr_results"] находится сводка по методам; details["placebo_results"] содержит in-space placebo units, details["time_placebo_results"] — фиктивные даты внутри предпериода, а details["block_bootstrap_results"] — прогон на null-панелях из временных блоков. Для калибровки желательно иметь не меньше трёх доноров: при маленьком donor pool permutation p-value дискретен, а FPR является грубой диагностикой. Перед запуском строится details["fpr_plan"] с доступным максимумом, timing и ошибки доступны в details["fpr_run_log"] без автоматической печати.

run_synthetic_control_robustness(...)

run_synthetic_control_robustness(
    df, outcome_col, unit_col, time_col, treated_unit,
    intervention_time, donor_units=None, max_controls=10,
)

Как проверяет устойчивость: строит in-space placebo на донорах, считает leave-one-out варианты и проверяет, не держится ли вывод на одном доноре.

Synthetic DiD (SDiD)

Synthetic DiD объединяет временную логику DiD с unit- и time-весами synthetic control. Реализация использует пакет diff-diff и рассчитана на блочный дизайн: treated_col должен быть постоянным внутри unit, а intervention_time разделяет панель на предпериод и постпериод. См. руководство Synthetic DiD и API SyntheticDiD.

Формат данных для функции

Обязательна одна строка на комбинацию unit x time. Treatment — бинарный флаг, постоянный для каждого unit.

fit_synthetic_did(...)

fit_synthetic_did(
    df, outcome_col, unit_col, time_col, treated_col, intervention_time,
    covariates=None, variance_method="placebo", n_bootstrap=200,
    seed=42, zeta_omega=None, zeta_lambda=None, label="synthetic_did",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None, mde_simulator=None,
)

Параметры MDE

В summary находятся effect_absolute, effect_relative, effect_cumulative, effect_ci, effect_relative_ci, effect_cumulative_ci, std_error, p_value и MDE-поля. В details доступны series, полные unit/time weights, weight_concentration с min/max, ESS, общим числом pre-периодов, числом положительных time weights и долями веса top-3/top-5 периодов, power curve и исходный результат diff-diff. Также возвращаются графики actual vs counterfactual и gap. effect_relative_ci выводится с символом %, остальные интервалы — в единицах outcome. effective_pre_periods — это ESS по time weights, а не буквальное число дат. В details["series"] сохраняются сырые counterfactual/gap и level-shift-adjusted counterfactual_level_adjusted/gap_level_adjusted; effect_cumulative и SDiD-графики используют adjusted gap. Относительный и кумулятивный интервалы — plug-in преобразования ATT-интервала и не учитывают дополнительную неопределённость baseline или level-shift alignment.

В режиме mde_mode="resampling" treated-строки симулируются вокруг level-shift-adjusted synthetic counterfactual, control-строки — вокруг unit-level baseline с календарным профилем контрольной группы. Остатки ресэмплируются, кандидатный эффект добавляется в post-периоде, а каждый draw заново проходит через diff-diff с повторной оценкой unit/time-весов. Это точнее параметрического MDE, но значительно медленнее.

check_synthetic_did_assumptions(...)

check_synthetic_did_assumptions(
    df, outcome_col, unit_col, time_col, treated_col,
    intervention_time, covariates=None,
    variance_method="placebo", n_bootstrap=200, seed=42,
    fpr_placebo_count=20, alpha=0.05,
    zeta_omega=None, zeta_lambda=None,
    fpr_method="time_placebo", fpr_block_length=7,
    save_fpr_weights=False, fpr_n_jobs=1,
)

Проверяет качество pre-fit (RMSE, relative RMSE, WAPE, R², корреляцию) после удаления постоянного level shift, требует визуальной проверки pre-trend, считает proxy-MDE и эмпирическую FPR по placebo-дизайнам. В checks также выводятся описательные unit_weight_min/max, effective_donors, time_weight_min/max, effective_pre_periods, pre_periods_total, time_weight_positive_periods, effective_pre_periods_share, time_weight_top3_share и time_weight_top5_share; пороги для них автоматически не применяются. effective_pre_periods — это ESS по time weights, а не буквальное число дат. Полные списки весов находятся в details["unit_weights"] и details["time_weights"]. Число placebo-прогонов задаётся fpr_placebo_count; его значение, alpha, сырой RMSE и level shift сохраняются в metadata. Параметры zeta_omega и zeta_lambda позволяют зафиксировать регуляризацию для основного fit и всех placebo-fit, чтобы сравнивать эмпирическую FPR между вариантами регуляризации. Параметр fpr_method принимает один метод или список: time_placebo, block_bootstrap и placebo_units. Несколько методов можно включить одновременно; для block bootstrap длина блока задаётся fpr_block_length. fpr_n_jobs задаёт число worker-потоков для независимых FPR-refit (по умолчанию 1); общая подготовка панели выполняется один раз и переиспользуется. Сводка находится в details["fpr_results"], а при нескольких методах добавляется figures["fpr_comparison"].

До запуска цикла доступен details["fpr_plan"] с максимально возможным числом прогонов и причиной ограничений; при превышении структурного максимума пакет предупреждает заранее. В details["fpr_results"] сохраняются failed/skipped прогоны и время, а подробный журнал ошибок находится в details["fpr_run_log"]. При save_fpr_weights=True появляется details["fpr_weight_diagnostics"] с unit/time-весами каждого успешного прогона. Разрешённые значения zeta_omega/zeta_lambda сохраняются в metadata и повторно используются во всех FPR refit.

Практический workflow: сравните FPR с alpha и концентрацию time weights в details["weight_concentration"]. Высокая FPR вместе с малым effective_pre_periods и большой долей top-3 time weights — повод повторить fit и FPR-проверку с явно заданным большим zeta_lambda. Значение зависит от масштаба outcome и не является универсальным порогом; при смене единиц outcome его нужно масштабировать пропорционально. Зафиксированное значение передавайте и в основной fit, и в FPR-проверку. Не выбирайте регуляризацию только по близости FPR к 5%: она меняет time-weighted estimand, поэтому сначала сравните pre-fit, ESS, концентрацию весов и величину эффекта.

run_synthetic_did_robustness(...)

run_synthetic_did_robustness(
    df, outcome_col, unit_col, time_col, treated_col,
    intervention_time, covariates=None,
    variance_method="placebo", n_bootstrap=200, seed=42,
    zeta_omega=None, zeta_lambda=None,
    pre_period_days_options=(None, 28, 56, 84),
    placebo_offsets_days=(28, 21, 14),
    diff_diff_checks=(),
    diff_diff_placebo_periods=None,
    diff_diff_zeta_multipliers=(0.25, 0.5, 1.0, 2.0, 4.0),
    zeta_lambda_multipliers=(),
)

Пересчитывает эффект для разных окон предпериода и placebo-дат интервенции. Результаты находятся в details["pre_period_sensitivity"] и details["placebo_results"], графики — в figures["pre_period_sensitivity"] и figures["placebo_estimates"].

Если передать zeta_lambda_multipliers, функция дополнительно повторит полный SDiD-fit для каждого множителя автоматически выбранного zeta_lambda. Результаты находятся в details["zeta_lambda_sensitivity"], графики — в figures["zeta_lambda_sensitivity"] и figures["zeta_lambda_weight_concentration"]. В таблице доступны эффект, значение регуляризации, ESS, доля effective pre-периодов, число положительных time weights и доли веса top-3/top-5 периодов. Масштаб множителей зависит от единиц outcome; для диагностики обычно используют логарифмическую сетку. По умолчанию tuple пустой, чтобы не увеличивать время расчёта.

zeta_omega и zeta_lambda фиксируют регуляризацию во всех базовых, placebo и sensitivity-fit. При zeta_lambda=None используется автоматическое значение; явное положительное значение позволяет проверить более сильное сглаживание time weights и получить сопоставимую FPR-проверку.

Опциональные нативные проверки diff-diff

Через параметр diff_diff_checks можно включить проверки, которые уже реализованы в результате diff-diff:

run_synthetic_did_robustness(
    df, outcome_col, unit_col, time_col, treated_col, intervention_time,
    diff_diff_checks=("in_time_placebo", "zeta_omega_sensitivity"),
    diff_diff_placebo_periods=["2025-12-15"],
    zeta_lambda_multipliers=(0.1, 1.0, 10.0, 100.0, 1_000.0, 10_000.0, 100_000.0),
)

Для этих нативных проверок также возвращаются одноимённые графики в figures. По умолчанию diff_diff_checks=(), поэтому дополнительные переоценки не запускаются.

Для SDiD auto и analytic используют plug-in MDE по inferential SE ATT от diff-diff. Это не отдельная закрытая формула дизайн-мощности SDiD: веса уже оценены на исходной панели. parametric использует ту же SE для draws, а proxy — level-shift-adjusted pre-fit RMSE.

В режиме mde_mode="resampling" строится нулевая псевдопанель: treated-строки используют level-shift-adjusted synthetic counterfactual, control-строки — unit-level baseline с календарным профилем. Остатки ресэмплируются, кандидатный эффект добавляется в post-периоде, затем каждый draw заново переоценивается через diff-diff вместе с unit/time-весами. Это наиболее полный, но самый медленный режим MDE.

Causal Impact

Формат данных для функции

fit_causal_impact(...)

fit_causal_impact(
    df, outcome_col, unit_col, time_col, treated_unit, intervention_time,
    donor_units=None, max_controls=10, pre_period=None, post_period=None,
    label="causal_impact",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None,
)

Параметры MDE

check_causal_impact_assumptions(...)

fpr_placebo_count задаёт число placebo-прогонов Causal Impact для эмпирической FPR; по умолчанию 20. fpr_method принимает time_placebo, block_bootstrap и placebo_units; можно передать список методов. Для block bootstrap длина блока задаётся fpr_block_length. Результаты находятся в details["fpr_results"], а при нескольких методах добавляется figures["fpr_comparison"].

До начала расчётов формируется details["fpr_plan"] с доступным числом дат, доноров или bootstrap-прогонов. При превышении структурного максимума пакет предупреждает до тяжёлого цикла; timing и failed/skipped сохраняются в сводке, подробности ошибок — в details["fpr_run_log"] без автоматического вывода.

check_causal_impact_assumptions(
    df, outcome_col, unit_col, time_col, treated_unit, intervention_time,
    donor_units=None, max_controls=10, pre_period=None, post_period=None,
    fpr_placebo_count=20, alpha=0.05,
    fpr_method="time_placebo", fpr_block_length=7,
)

Что проверяет: полноту aligned panel, число и качество выбранных доноров, качество pre-fit на train/validation и чувствительность дизайна через proxy MDE. Эмпирическую FPR можно считать через time_placebo, block_bootstrap и placebo_units; несколько методов передаются списком.

run_causal_impact_robustness(...)

run_causal_impact_robustness(
    df, outcome_col, unit_col, time_col, treated_unit, intervention_time,
    donor_units=None, max_controls=10, placebo_offsets_days=(28, 21, 14),
    pre_period_days_options=(None, 28, 56, 84),
)

Как проверяет устойчивость: запускает placebo с более ранними датами интервенции, делает leave-one-out по донорам и смотрит, не исчезает ли эффект после исключения одного донора.

Interrupted Time Series (ITS)

Формат данных для функции

Для панельного ITS допускается несколько строк на одну дату — по одной на unit × date. В этом случае модель оценивается на всех строках панели, cluster_col задаёт кластеризацию по юниту, а holdout/rolling-валидация и график проверяются на среднем значении по календарной дате. Это не следует путать с агрегированным single-series ITS.

build_standard_its_features(...)

build_standard_its_features(
    df, time_col, intervention_time,
    include_day_of_week=True, include_month_start=True, include_month_end=True,
    holiday_dates=None, extra_feature_cols=None,
)

fit_its(...)

fit_its(
    df, outcome_col, time_col, intervention_time,
    feature_cols=None, extra_feature_cols=None,
    standardize_features=True, validation_days=14,
    hac_lags=7, label="its",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None, se_type="hac", cluster_col=None, time_cluster_col=None,
)

Параметры MDE

check_its_assumptions(...)

fpr_placebo_count задаёт число placebo-прогонов для эмпирической FPR; по умолчанию 20. Для ITS доступен fpr_method="time_placebo": пакет переоценивает модель на нескольких фиктивных датах вмешательства внутри предпериода. placebo_units для single-series ITS неприменим и возвращается со статусом not_applicable. Режим block_bootstrap для ITS не поддерживается; при его передаче будет ValueError. Сводка находится в details["fpr_results"].

До цикла строится details["fpr_plan"] с доступными placebo-датами и структурным максимумом. В details["fpr_results"] сохраняются timing и failed/skipped, а details["fpr_run_log"] содержит подробности ошибок без автоматической печати.

check_its_assumptions(
    df, outcome_col, time_col, intervention_time,
    feature_cols=None, standardize_features=True,
    validation_days=14, hac_lags=7,
    recommended_min_pre_days=42, fpr_placebo_count=20,
    label="its_assumptions", alpha=0.05,
    fpr_method="time_placebo",
    se_type="hac", cluster_col=None, time_cluster_col=None,
)

Что проверяет: длину и полноту предпериода, holdout-качество прогноза, автокорреляцию и выбросы в остатках, а также явные внешние изменения, которые ломают single-series дизайн. FPR можно оценивать через time_placebo; placebo_units для ITS неприменим, а block_bootstrap не поддерживается.

run_its_robustness(...)

run_its_robustness(
    df, outcome_col, time_col, intervention_time,
    pre_window_days_options=(56, 84, 112),
    placebo_offsets_days=(28, 21, 14),
    feature_sets=None, hac_lags=7,
    hac_lags_options=(0, 3, 7, 14),
    se_type="hac", cluster_col=None, time_cluster_col=None,
)

Как проверяет устойчивость: меняет длину предпериода, запускает placebo на более ранних датах, сравнивает эффект на разных наборах признаков и для HAC перебирает значения hac_lags.

Regression Discontinuity Design (RDD)

Формат данных для функции

fit_rdd(...)

fit_rdd(
    df, outcome_col, running_col, cutoff,
    covariates=None, bandwidth=None,
    polynomial_order=1, kernel="triangular",
    label="rdd",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None, cluster_col="auto",
    se_type="auto", time_cluster_col=None,
)

Параметры MDE

check_rdd_assumptions(...)

check_rdd_assumptions(
    df, outcome_col, running_col, cutoff,
    covariates=None, bandwidth=None,
    density_bins=20, label="rdd_assumptions", cluster_col="auto",
    se_type="auto", time_cluster_col=None,
)

Что проверяет: число наблюдений по обе стороны cutoff, скачок плотности около порога и непрерывность ковариат рядом с cutoff. Continuity-регрессии используют выбранный cluster_col, а density-регрессия остаётся HC1, потому что строится на агрегированных бинах.

run_rdd_robustness(...)

run_rdd_robustness(
    df, outcome_col, running_col, cutoff,
    covariates=None,
    bandwidth_options=(None, 0.5, 1.0),
    polynomial_orders=(1, 2),
    placebo_cutoffs=None,
    cluster_col="auto", se_type="auto", time_cluster_col=None,
)

Как проверяет устойчивость: меняет bandwidth, меняет порядок полинома и проверяет, не возникает ли похожий эффект на placebo-cutoff.

Propensity Score Matching (PSM)

Формат данных для функции

check_psm_assumptions(...)

check_psm_assumptions(
    df, outcome_col, treatment_col, covariate_cols,
    propensity_model=None, caliper=None, n_neighbors=1,
    label="psm_assumptions",
)

Что проверяет: overlap и common support, слишком сильное разделение групп propensity-моделью, баланс ковариат до и после matching и долю treated без мэтча.

fit_psm(...)

fit_psm(
    df, outcome_col, treatment_col, covariate_cols,
    propensity_model=None, caliper=None, n_neighbors=1,
    label="psm_att",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None,
)

Параметры MDE

run_psm_robustness(...)

run_psm_robustness(
    df, outcome_col, treatment_col, covariate_cols,
    caliper_options=(None, 0.05, 0.1),
    neighbor_options=(1, 3),
)

Как проверяет устойчивость: меняет жесткость matching через caliper, меняет число соседей и сравнивает стабильность ATT.

Doubly Robust

Формат данных для функции

check_doubly_robust_assumptions(...)

check_doubly_robust_assumptions(
    df, outcome_col, treatment_col, covariate_cols,
    propensity_model=None, outcome_model=None,
    clip=0.01, label="doubly_robust_assumptions",
)

Что проверяет: overlap propensity score, баланс ковариат до и после взвешивания и наличие экстремальных весов, которые могут дестабилизировать AIPW.

fit_doubly_robust(...)

fit_doubly_robust(
    df, outcome_col, treatment_col, covariate_cols,
    propensity_model=None, outcome_model=None,
    clip=0.01, model_family="linear",
    label="doubly_robust_ate",
    mde_mode="auto", alpha=0.05, power=0.80,
    alternative="two-sided", n_simulations=2000,
    random_state=None, mde_effect_grid=None,
    mde_simulator=None,
)

Параметры MDE

run_doubly_robust_robustness(...)

run_doubly_robust_robustness(
    df, outcome_col, treatment_col, covariate_cols,
    clip_options=(0.01, 0.025, 0.05),
    model_families=("linear", "forest"),
)

Как проверяет устойчивость: меняет clipping propensity score, меняет семейство nuisance-моделей и сравнивает стабильность итогового ATE.

Совместимость окружения

ensure_runtime_compat()

from post_analysis_toolkit.compat import ensure_runtime_compat