# fLP() : y ~ shock + controls
# fLPIV() : y ~ D + controls, instruments = ~ z + l(z, 1:6)
# fLPPanel() : y ~ shock + controls | fe1 + fe2
# fLPDID() : y ~ treat + controlsLocal Projections — Common Syntax and Conventions
One reference sheet for fLP(), fLPIV(), fLPPanel(), and fLPDID()
1 Purpose of this chapter
The four local-projection engines in tidyMacro — fLP(), fLPIV(), fLPPanel(), fLPDID() — deliberately share a single, fixest-inspired interface: the same formula grammar, the same lag/lead operators, the same panel-index convention, the same multi-band handling, and the same plotting entry point (fPlotIRF() / fPlotLPDID()). This chapter is the one place where those shared conventions are documented, so the empirical replication chapters that follow (Jorda and Taylor (2025), Mian et al. (2017), Dube et al. (2025)) can stay focused on the economics.
Read this once, then treat the estimator chapters as extensions:
fLP()andfLPIV()— Local Projections with Shocks and IVfLPPanel()— Panel Local ProjectionsfLPDID()— Local Projections Difference-in-Differences
3 2 · Common arguments
The four engines share more arguments than differ. The list below shows what every LP call looks like in tidyMacro; consult the individual ?fLP, ?fLPIV, ?fLPPanel, ?fLPDID help pages for the estimator-specific extras.
| Argument | fLP | fLPIV | fLPPanel | fLPDID | Meaning |
|---|---|---|---|---|---|
formula |
✓ | ✓ | ✓ | ✓ | Formula with ..macro, l(), f() (and d() for LP-DiD) |
data |
✓ | ✓ | ✓ | ✓ | data.frame / tibble (long form for panel) |
horizons |
✓ | ✓ | ✓ | — | Scalar H or the sequence 0:H |
post, pre |
— | — | — | ✓ | Event-time windows (LP-DiD replaces horizons) |
shock |
✓ | — | ✓ | — | Name of the impulse term |
endog |
— | ✓ | — | — | Name of the endogenous treatment RHS term |
instruments |
— | ✓ | — | — | One-sided formula, e.g. ~ l(z, 0:6) |
treat |
— | — | — | ✓ | Name of the treatment level column |
panel_id |
— | — | ✓ | ✓ | c("id_col", "time_col") |
cluster |
— | — | — | ✓ | Cluster column (default = unit id) |
conf |
✓ | ✓ | ✓ | ✓ | Scalar or vector of confidence levels |
cumulative |
✓ | ✓ | ✓ | implicit | Long-difference outcome y_{t+h} − y_{t-1} |
shock_size |
✓ | ✓ | — | — | "unit" (default) or "sd" impulse units |
nw_lags |
✓ | as nw_lags_iv |
— | — | Newey–West base bandwidth |
nw_offset |
✓ | — | — | — | NW bandwidth shift (+1 MA&R, 0 classic Jordà) |
ssc |
— | — | ✓ | — | Small-sample correction of the clustered variance: "none", "CR1", "IK" |
p_max |
— | — | ✓ | — | Max lags of the regressand and shock added as controls |
nonabsorbing |
— | — | — | ✓ | Non-absorbing treatment (with L, ccc) |
L, ccc |
— | — | — | ✓ | Clean-control window and flavor |
pmd |
— | — | — | ✓ | Pre-mean-differenced baseline (Stata formula) |
reweight |
— | — | — | ✓ | Equally-weighted ATT via inverse implicit weights |
n_threads |
✓ | ✓ | ✓ | ✓ | OpenMP threads; <= 0 uses all cores |
3.1 2.1 · Multi-level confidence bands from one fit
Every engine accepts a vector conf, e.g. conf = c(68, 95), and rebuilds every band from the same raw SE in R. There is no re-estimation cost and no multiple-testing story — bands are just alternative visualizations of the same variance. fPlotIRF() draws one ribbon per level automatically.
3.2 2.2 · Impulse units (shock_size)
fLP() and fLPIV() report the response to a one-unit shock by default (shock_size = "unit"). Setting shock_size = "sd" reports the response to a one-standard-deviation shock instead: fLP() z-scores the shock regressor, fLPIV() scales the 2SLS coefficient and its standard error by sd(D). In both cases the standard deviation is taken over the dates with every regressor observed — i.e. after the leading rows consumed by generated lags — not over the raw input column, and the same value serves every horizon. These correspond to LPopt.impact = 1 and LPopt.impact = 0 in the local-projection routine of Cesa-Bianchi’s VAR Toolbox.
3.3 2.3 · Threading and console noise
All four engines parallelize the horizon loop with OpenMP. The thread rule is uniform: n_threads <= 0 uses all available cores, n_threads > 0 uses exactly that many. Thread-count print messages have been gated behind an internal verbose flag (default off), so the engines are silent by default.
4 3 · The panel index convention
For fLPPanel() and fLPDID(), the panel is described by panel_id = c(id_col, time_col), plus an optional cluster = ... (LP-DiD).
Both estimators do the following, once, up front:
- Time normalization. The time column can be numeric,
Date, orPOSIXct. Internally it is re-mapped to an integer grid where consecutive periods differ by 1 (the step is inferred asmin(diff(sort(unique(time))))). This makesDatecolumns and monthly / quarterly / annual numeric grids behave identically. - Off-grid rows dropped. Rows whose time cannot be placed on the inferred grid are dropped with an informative message. This eliminates a class of hard-to-debug alignment bugs.
- Duplicate
(id, time)rejected. Any pair that appears twice would silently corrupt the internal unit-time row map used byl(),f(),d(), and the clean-control sets. A clear error is raised at the R boundary before any C++ call. - Gap preservation. All shifts look up
(id, normalized_time + k)explicitly rather than “the adjacent row after sorting”. Calendar gaps stay as gaps: no lag or lead ever silently bridges a missing period.
5 4 · What each engine returns
The output shapes share a common core so tidy() and fPlotIRF() work uniformly.
5.1 fLP() and fLPIV()
An S3 object of class "fLP" (fLPIV() adds the "fLPIV" subclass). Core fields:
| Field | Shape | Description |
|---|---|---|
irfs |
(H+1) × n_y |
IRF point estimates |
irfs_se |
(H+1) × n_y |
Raw HAC SE of the shock coefficient |
irfs_upper, irfs_lower |
matrix, or named list of matrices | Confidence bands; a list when conf has multiple levels |
horizons |
0:H |
Horizon index |
nobs |
(H+1) × n_y |
Observations per horizon and outcome |
Fstat_fs, rsqr_fs |
(H+1) × n_y (fLPIV only) |
First-stage F and R² per horizon and outcome (each outcome’s sample has its own first stage) |
tidy.fLP() returns a long data frame; single-band fits give the classic (estimate, se, lower, upper) columns, multi-band fits give one lower_X / upper_X pair per level.
Weak-instrument fallback for fLPIV(). When the 2SLS denominator \(\hat D' D_r\) is numerically zero (weak / degenerate first stage), fLPIV() returns NaN for that horizon’s estimate and SE rather than a silent 0. Downstream tidy.fLP() / fPlotIRF() propagate the NaNs so the horizon simply doesn’t render on the plot. Corresponding Fstat_fs[h] values become NaN when the residual df is non-positive.
5.2 fLPPanel()
An S3 object of class c("fLPPanel", "fLP") — so it plugs into fPlotIRF() and tidy.fLP() unchanged. Beyond the core fields, it exposes:
| Field | Shape | Description |
|---|---|---|
df |
(H+1) × n_s |
Effective degrees of freedom (LAHR or Imbens–Kolesar) |
pval |
(H+1) × n_s |
Two-sided p-values built in R from (estimate, SE, df) |
CI90/95/99 |
(H+1) × n_s × 2 arrays |
Fixed-level bands (rebuilt in R, not C++) |
status |
integer H+1 |
0 OK · 1 no complete rows · 2 HDFE failed |
converged |
integer H+1 |
1 HDFE converged · 0 did not |
Non-0 status values are surfaced as R warnings when they occur; the status / converged vectors let you programmatically screen individual horizons in downstream code.
5.3 fLPDID()
A tibble of class c("fLPDID", ...) with columns event_time, estimate, se, conf_low, conf_high, nobs, nclust, ndrop, and an attr("lpdid_spec") list capturing every argument that shaped the fit. ndrop counts control columns omitted for collinearity at that horizon (as reghdfe does); horizons that could not be estimated raise a warning naming the event times rather than returning a silent NaN. The plot function is fPlotLPDID(), which accepts one result or several named results (fPlotLPDID(\OLS` = m1, `Reweighted` = m2)`).
6 5 · The estimating equations
For quick reference, here are the population objects each function targets.
6.1 fLP() — classical Jordà LP
Standard form: \[y_{t+h} \;=\; \alpha_h + \beta_h\, s_t + \gamma_h' w_t + u_{t+h}, \qquad h = 0, 1, \dots, H.\]
Cumulative form (cumulative = TRUE): \[y_{t+h} - y_{t-1} \;=\; \alpha_h + \beta_h\, s_t + \gamma_h' w_t + u_{t+h}.\]
The base \(y_{t-1}\) for the first regressor date lies one period before the regressor sample. When generated lags trim the leading rows, that outcome is still observed, so fLP() and fLPIV() keep it as the base rather than discarding it — the estimation sample is not shortened by the long difference. This matches endo_lag1 = ENDO(lag_trim:end-1) in the VAR Toolbox’s local-projection routine.
Missing values. The sample is chosen as Stata does with F.h y: the lead is built on the full data first, and rows are dropped afterwards, horizon by horizon. The regressors (shock and controls; in fLPIV() the treatment, controls and instruments) fix the candidate dates \(t\), the rows where all of them are observed. At horizon \(h\), each outcome then uses the dates whose \(y_{t+h}\) is observed (and \(y_{t-1}\) for the cumulative form). Three consequences:
- an outcome observed after the shock series ends is used, so the sample does not shrink with \(h\) until the outcome itself ends;
- each outcome in
c(y1, y2)has its own sample, so theNAs ofy2never change the estimates fory1; - a date whose outcome is missing at \(t\) but observed at \(t+h\) is kept.
nobs reports the resulting sample size per horizon and outcome. On fully observed data nothing changes. Time-series LP still requires contiguous samples: the engines treat the retained rows as consecutive periods for the Newey–West autocovariances, so an interior gap in the regressors or in an outcome is rejected with an error (leading and trailing NAs, e.g. from l() / f(), are fine).
The IRF at horizon \(h\) is \(\beta_h\). Standard errors use the full Newey–West sandwich V_h = (X'X)⁻¹ X'ΩX (X'X)⁻¹ with a Bartlett kernel of bandwidth max(nw_lags + h + nw_offset, 0).
6.2 fLPIV() — LP with an external instrument
The endogenous treatment \(D_t\) is identified by an external instrument matrix \(Z_t\) (build any lags with l(z, 0:k) in the instruments formula). Estimation is horizon-by-horizon 2SLS via Frisch–Waugh–Lovell:
- Residualize \(y_{h}\), \(D\) and \(Z\) on \([1, C_t]\).
- First stage: \(\hat D_t = Z_r (Z_r' Z_r)^{-1} Z_r' D_r\).
- 2SLS point estimate \(\hat\beta_h = (\hat D' Y_r) / (\hat D' D_r)\).
- Newey–West delta-method SE on the score \(g_t = \hat D_t \cdot \varepsilon_t\).
The first-stage F reported in Fstat_fs uses df2 = Th − kc − nz, i.e. the residual df of the full first-stage regression \(D \sim [1, C, Z]\) under the FWL equivalence; if df2 <= 0 the value is NaN.
6.3 fLPPanel() — panel LP
At horizon \(h\), for each interaction component \(j\): \[y_{i, t+h} \;=\; \alpha^{(h)}_{\mathrm{FE}} + \beta_h^{(j)} (s_{it, j}\, x_t) + \gamma_h' w_{it} + \sum_{k=1}^{\min(h, p_{\max})} \delta_{hk}' v_{i,t-k} + u_{i,t+h}.\]
Inference: asymptotic time-clustered (LAHR) by default (ssc = "none"). ssc = "CR1" applies the finite-sample multiplier and \(t\) degrees of freedom used by Stata and fixest; ssc = "IK" applies the Imbens and Kolesár (2016) refinement, which reports a component-specific effective degrees of freedom. The predecessor argument small_sample = TRUE maps onto ssc = "IK" and is deprecated.
6.4 fLPDID() — LP-DiD à la Dube–Girardi–Jordà–Taylor
At horizon \(h\): \[y_{i, t+h} - y_{i, t-1} \;=\; \beta_h\, \Delta D_{it} + X_{it}' \gamma_h + \tau_t + \varepsilon_{it},\]
restricted to a clean-control sample. Pre-treatment horizons replace \(y_{i, t+h}\) by \(y_{i, t-j}\) with \(\beta_{-1} = 0\) as the normalization. Standard errors are CR1 cluster-robust with the reghdfe correction \(c = \tfrac{G}{G-1} \cdot \tfrac{N-1}{N-K}\) where \(K\) counts absorbed time fixed effects. Singleton absorbed-FE observations are dropped before \(N\) and \(K\) are formed, again as reghdfe does. Confidence bands use a cluster-\(t\) critical value with \(G-1\) degrees of freedom, not a normal quantile.
PMD baseline (pmd = TRUE) replaces \(y_{i, t-1}\) by the pre-treatment mean \(\bar y_{i,<t}\) computed exactly as in the DGJT Stata replication code:
- Numerator: per-unit running sum of \(y\) treating missing outcomes as \(0\) (Stata’s
sum()convention). - Denominator: calendar time since the global sample start,
time - 1withtime = year - start_year + 1. - The baseline is defined only when the immediately preceding calendar row exists for the unit (Stata’s
L.semantics); otherwise it isNAand that horizon drops.
This reproduces the published numbers on balanced and gap-containing panels alike.
Reweight (reweight = TRUE) applies inverse implicit weights \(w = 1/(1 - p_t)\) to recover the equally-weighted ATT (exogenous / absorbing case). When combined with non-empty controls, fLPDID() emits a runtime warning stating that this is not the DDCG teffects ra regression-adjustment estimator — the naming is deliberate so downstream interpretation is unambiguous.
7 6 · Plotting
Both fPlotIRF() and fPlotLPDID() are the same idea: pass a fit (or several) and get a ggplot back.
fPlotIRF(lp_fit) # single fit → one panel per LHS
fPlotIRF(lp_fit, return_data = TRUE) # tibble for hand-rolled ggplot
fPlotIRF(`h` = lp_a, `h + 1` = lp_b) # several fits overlaid, one colour each
fPlotLPDID(m_ols, m_rw) # unnamed fits get generic labels
fPlotLPDID(`OLS` = m_ols, `Reweighted` = m_rw) # named → facet labels
fPlotLPDID(m_ols, ci = "bars") # DGJT coefplot styleMulti-band fLP() / fLPIV() / fLPPanel() fits automatically get one ribbon per level.
8 7 · Direct C++ boundary access
Advanced users may bypass the R wrapper and call the C++ engines through tidyMacro:::fLP_cpp, tidyMacro:::fLPIV_cpp, tidyMacro:::fLPPanel_cpp, tidyMacro:::fLPDID_cpp. Each of these does its own boundary validation before entering the parallel region:
- Finite inputs only —
NA,NaN,Infare rejected up-front. The exception is the outcome matrixYoffLP_cppandfLPIV_cpp, whereNAmarks an unobserved outcome (Infis still rejected);Ymay also have more rows than the regressors, the extra rows holding the outcomes’ leads. - Row-count consistency across all matrices / vectors.
- Non-negative scalar arguments (
H,pre_window,post_window, etc.). ccc ∈ {0, 1, 2}for LP-DiD;Lwin >= 0whennonabsorbingandccc > 0.
The R wrappers already enforce all of the above; the direct-call checks are a safety net so .Call from downstream packages fails cleanly.
9 8 · Where to go next
fLP()andfLPIV()— Local Projections with Shocks and IV (Jordà & Taylor 2025 replication).fLPPanel()— Panel Local Projections (Mian et al. (2017) replication).fLPDID()— Local Projections Difference-in-Differences (Dube, Girardi, Jordà & Taylor 2025 replication).