Документация 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)

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

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

Расшифровка 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 и ITS он строится из ошибки префита: pre-fit RMSE / sqrt(n_post) или validation RMSE / sqrt(n_post).

Для каждого 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=None, 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,
)

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

Параметры MDE

check_did_assumptions(...)

fpr_placebo_count задаёт число placebo-прогонов для эмпирической FPR; по умолчанию 20.

check_did_assumptions(
    df, outcome_col, time_col, treated_col, post_col,
    intervention_time, unit_col=None, cluster_col=None,
    event_bin_size=7, label="did_assumptions",
)

Что проверяет: визуальную форму предпериода, разницу наклонов и корреляцию на предпериоде, joint-test лидов через event study, стабильность состава и явные параллельные изменения.

Возвращает локализованные проверки, event-study таблицы и диагностические графики.

run_did_robustness(...)

run_did_robustness(
    df, outcome_col, time_col, treated_col, post_col,
    intervention_time=None, unit_col=None, cluster_col=None,
    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),
)

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

Event Study

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

Event Study — самостоятельная регрессионная оценка динамики эффекта. Она возвращает отдельную оценку для каждого временного бина относительно пропущенного эталонного бина, а не один суммарный коэффициент за весь постпериод.

fit_event_study(...)

fit_event_study(
    df, outcome_col, time_col, treated_col, intervention_time,
    unit_col=None, cluster_col=None, 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,
)

Параметры MDE

В summary одна строка соответствует одному event-бину и содержит эффект, доверительный интервал, p-value и MDE. В details["event_study_summary"] лежит общий joint-тест лидов, а в figures["event_study"] — график коэффициентов.

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

check_event_study_assumptions проверяет reference-бин, число pre/post-бинов, joint-тест pre-period коэффициентов и максимальный абсолютный pre-period коэффициент. run_event_study_robustness повторяет оценку для разных размеров event-бина, reference-бинов и окон предпериода. Результаты sensitivity лежат в robust.summary и robust.details["sensitivity"].

Triple Difference (DDD)

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

fit_triple_difference(...)

fit_triple_difference(
    df, outcome_col, time_col, treated_col, post_col, subgroup_col,
    covariates=None, cluster_col=None, 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,
)

Параметры 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=None,
    event_bin_size=7, label="triple_difference_assumptions",
)

Что проверяет: полноту ячеек 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=None,
    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.

Параметры 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,
    pre_period_days_options=(None, 28, 56, 84),
)

Что проверяет: размер и чистоту donor pool, качество pre-fit synthetic ряда и риск загрязнения donor pool treated-изменениями.

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 варианты и проверяет, не держится ли вывод на одном доноре.

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.

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,
)

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

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)

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

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,
)

Параметры MDE

check_its_assumptions(...)

fpr_placebo_count задаёт число placebo-прогонов для эмпирической FPR; по умолчанию 20.

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, label="its_assumptions",
)

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

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,
)

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

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,
)

Параметры MDE

check_rdd_assumptions(...)

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

Что проверяет: число наблюдений по обе стороны cutoff, скачок плотности около порога и непрерывность ковариат рядом с cutoff.

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,
)

Как проверяет устойчивость: меняет 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