did_imputation
Fits a two-way model on untreated observations, imputes counterfactual Y(0) for treated units, and averages residuals to estimate the ATT in staggered DiD. Needs never-treated or not-yet-treated units.
Instructions
Borusyak-Jaravel-Spiess (2024) imputation DiD. Fits a TWFE model on untreated observations only, imputes counterfactual Y(0) for treated obs, and averages the imputation residuals. Efficient under no-anticipation + parallel trends; analytical SE via bjs_inference. Validation: certified evidence with scoped limitations. Known limitations: R/Stata parity is for the documented untreated-only TWFE and simple ATT aggregation convention only; event-study and SE rows are backend-specific diagnostics. Do NOT use when: there is no never-treated (or not-yet-treated) group to fit the untreated-potential-outcome model on -- imputation has no estimation sample; the design is a simple 2x2 -- sp.did(method='2x2') is the same estimand and far cheaper; pre-trends are visibly non-parallel -- BJS imputes Y(0) from a two-way model that assumes them away, so violations are absorbed silently rather than surfaced. Cost: Fits the untreated two-way model once, then imputes; cheap in memory. vce='bootstrap' multiplies total runtime by n_boot -- budget accordingly before raising n_boot. Assumptions: Parallel trends in absolute levels; No anticipation (no pre-treatment reaction); SUTVA. Pre-conditions: panel...
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| y | Yes | Outcome variable column name or outcome array. | |
| fe | No | Fixed effects in the Y(0) model, replacing the default unit+time. Stata's fe(): entries are column names or 'a#b' interacted cells; [] means no fixed effects. | |
| vce | No | Standard-error mode for the overall ATT. 'analytic' is fast but anti-conservative (~0.87 coverage); 'bootstrap' resamples clusters. | analytic |
| time | Yes | Time period column | |
| alpha | No | Significance level for confidence intervals and tests. | |
| group | Yes | Unit identifier | |
| hetby | No | Report heterogeneous ATTs by a time-invariant unit-level variable (Stata: hetby()) | |
| min_n | No | Drop event-study horizons with fewer treated observations (Stata: minn()) | |
| detail | No | Payload depth: 'minimal' (~150 tokens) for sub-step calls where only the point estimate is needed; 'standard' (~1K tokens) for diagnostics + coefficient table; 'agent' (~2K tokens, default) adds violations / next_steps / suggested_functions so the LLM can plan its next call without another round-trip. | agent |
| n_boot | No | Cluster-bootstrap replications when vce='bootstrap'. | |
| cluster | No | Cluster identifier column for clustered standard errors. | |
| horizon | No | Relative-time leads / lags (default: all available) | |
| project | No | Regress the imputed treatment effects on these covariates and report constant plus slopes. Stata's project(); mutually exclusive with hetby. | |
| balanced | No | Keep only eventually-treated units observed at every non-negative requested horizon (Stata: hbalance) | |
| controls | No | Control-variable column names. | |
| as_handle | No | If true, cache the fitted result on the server and return result_id + result_uri alongside the JSON payload so a subsequent tools/call can chain without re-running. | |
| boot_seed | No | Seed for the cluster bootstrap (deterministic results). | |
| data_path | Yes | Absolute path or URL to a data file. Supported: .csv / .tsv / .txt (delimited), .parquet / .pq, .feather / .arrow, .xlsx / .xls, .dta (Stata), .json / .jsonl. Schemes: file://, s3://, gs://, https://. | |
| pretrends | No | Estimate k placebo pre-trend coefficients (-k..-1) and report their joint Wald test (Stata: pretrends(k)) | |
| result_id | No | Optional handle to a previously-fitted result (returned by an earlier call when as_handle=true). Tools that operate on a fitted object accept this in place of re-supplying data_path + columns. | |
| se_method | No | Shared DiD spelling for vce=: 'analytic', 'bootstrap' or 'auto'. Passing both raises. | |
| first_treat | Yes | First-treatment period; 0 = never-treated | |
| data_columns | No | Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads. | |
| save_weights | No | Store exact estimation weights w with ATT = w'y in model_info (Stata: saveweights()) | |
| data_sample_n | No | Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels. | |
| save_residuals | No | Store untreated-fit residuals in model_info (Stata: saveresid()) | |
| pretrend_method | No | Reference convention for the PRE-treatment event-study coefficients. 'bjs' matches Stata did_imputation, 'in-sample' is the fect/did2s residual average (attenuated by N0/N), 'symmetric' is Roth's (2026) TWFE-comparable repair for non-staggered designs. Post-treatment coefficients are identical under all three. | bjs |
| time_covariates | No | Controls interacted with the period fixed effects (one coefficient per period). Stata's timecontrols(). | |
| unit_covariates | No | Controls interacted with the unit fixed effects (one slope per unit). Stata did_imputation's unitcontrols(); unit_covariates=[time] gives unit-specific trends. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||