local_projections
Estimate impulse responses across multiple horizons with local projections, adding controls, Newey-West confidence bands, and cumulative responses to support causal impact decisions.
Instructions
Estimate impulse responses via Jorda (2005) local projections. Validation: certified parity evidence. Assumptions: Outcome and shock series are (covariance-)stationary so horizon-h projections are not spurious; Shock is conditionally exogenous at t given controls and the auto-added lags (no contemporaneous feedback from y_t to shock_t); Newey-West truncation lag is adequate for the moving-average serial correlation induced by overlapping horizons. Pre-conditions: Single time-ordered series in a DataFrame with the outcome and shock columns; For identification='lpirfs_cholesky', endog_order contains the outcome and shock columns in the intended Cholesky ordering; Length comfortably exceeds horizons + max lag so the deepest horizon regression retains enough usable rows. Failure modes: Confidence bands explode or flip sign at long horizons after passing already-lagged controls together with auto_lag=True -> Set auto_lag=False for a bare specification, or drop your manual lags so collinear duplicate-lag columns are not formed; The horizon-0 response is zero when the shock is ordered after the response variable -> Use the intended endog_order, or switch back to identification='direct' i...
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alpha | No | Significance level for the confidence band. | |
| shock | Yes | Column name of the shock / treatment variable. | |
| 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 |
| nw_lags | No | Newey-West truncation lag. Defaults to ``round(1.5 * horizons)`` per Kilian & Kim (2011) recommendation. | |
| outcome | Yes | Column name of the outcome variable y. | |
| auto_lag | No | If ``True`` (the legacy default), also adds ``y_{t-1}`` and ``shock_{t-1}`` as automatic regressors. Set ``False`` for a bare ``y_{t+h} ~ const + shock_t + controls`` specification. These two auto-controls were silent in the pre-1.16 docstring. | |
| controls | No | Additional regressors taken **verbatim** from ``data``: the column values at time t are used directly, without re-lagging. If you want the lag of a control, lag it yourself before passing it in (e.g. ``df["unemp_lag"] = df["unemp"].shift(1)`` and then ``controls=["unemp_lag"]``). The pre-1.16 behaviour silently re-lagged controls a second time on top of an auto- added ``y_{t-1}``, producing collinear columns and surprising impulse responses; see ``MIGRATION.md`` for context. | |
| horizons | No | Number of horizons h = 0, 1, ..., H to estimate. | |
| 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. | |
| 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://. | |
| 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. | |
| cumulative | No | If ``True``, return the cumulative response ``y_{t+h} - y_{t-1}``. Default (False) returns ``y_{t+h}`` directly. | |
| endog_order | No | Endogenous variable order used only when ``identification='lpirfs_cholesky'``. Defaults to ``[outcome, shock]``. | |
| data_columns | No | Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads. | |
| data_sample_n | No | Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels. | |
| identification | No | Shock-identification convention. ``'direct'`` uses the coefficient on the observed ``shock`` variable in each horizon regression. ``'lpirfs_cholesky'`` reproduces ``lpirfs::lp_lin`` with ``lags_endog_lin=1`` and ``shock_type=1``: the variables in ``endog_order`` define the Cholesky ordering, and the reported response is the unit structural shock for ``shock``. | direct |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||