Average Treatment Effect Localization (ATEL)

Contents

Average Treatment Effect Localization (ATEL)#

When to Use This Method#

A policy is adopted, and you are asked what it did. The usual answer averages the gap between the treated unit and its counterfactual over every post-treatment period. That average describes the policy only if the treated unit stood still while the policy acted on it, and units do not stand still. An organisation facing a funding cut fundraises, reorganises, and lays people off; a state facing a new firearms law sees policing and migration respond. Average over ten years and you measure the policy and every response to it, added together, with no way to read one off the other.

ATEL (Lee, [ATEL]) reports a different number: an average that puts most of its weight on the periods just after adoption, and little on the ones far from it. The estimand is still an average treatment effect on the treated, and it is still a single number, but it is localized at the moment the policy took effect, where the response has had least time to accumulate.

Two consequences follow, and they pull in opposite directions. What ATEL estimates is closer to the policy’s own effect, since it is measured before the unit has adapted. What it estimates is also a narrower quantity: it says nothing about the long run, and a policy whose effect grows over years will look small.

Reach for ATEL when#

  • the post-period is long enough that adaptation is plausible, and you want the policy’s effect and not the policy plus the response;

  • you have to report inside a budget or election cycle, so the near-term effect is the decision-relevant one;

  • the treated unit’s relationship to the donor pool moves over the sample. ATEL lets the factor loading vary with time, so a unit whose comparison group drifts is still usable;

  • you have time-varying covariates that plausibly drive the unit’s exposure to common shocks. These give the strongest version of the method, since the sieve basis in them is what lets the loading move with observables. They are not required – see Where the weights come from.

Do not use ATEL when#

  • the question is about the long run. The kernel discards exactly the periods a long-run question is about; use Factor Model Approach (FMA), Generalized Synthetic Control (GSYNTH) or a standard synthetic control;

  • you have one post-period, or two with a small bandwidth. The localization window is \(\lfloor T_1 h \rfloor\) and an empty window has no estimand;

  • nothing in the panel plausibly correlates with the loadings. The projection needs weights that do, and neither a covariate nor an outcome transformation will help if the relationship is absent – though no diagnostic can tell you this, so it is a judgement about the setting;

  • the effect is expected to switch sign over the post-period. A weighted average of a sign-changing path is a number whose interpretation depends on the weights, and the kernel’s weights are not a policy choice.

Localization against donor weighting#

ATEL differs from the estimators around it on two axes at once, and the second is easy to miss.

Estimator

Factors from

Loading

Post-period aggregation

Synthetic control

donor outcomes, convex hull

fixed weights

unweighted mean

Factor Model Approach (FMA)

principal components

fixed over time

unweighted mean

Generalized Synthetic Control (GSYNTH)

principal components

fixed per unit

unweighted mean

ATEL

diversified projection

varies with time

kernel, localized at \(T_0\)

The loading row is the substantive disagreement with Factor Model Approach (FMA). Taking factors by principal components and holding the loading fixed recovers, when the true loading moves, a time-average of it; the paper makes this point directly ([ATEL], p. 12). ATEL estimates the movement instead of averaging over it.

Overview#

ATEL implements Lee, R.-C. (2026), “Average Treatment Effect Localization: Projection Methods in Synthetic Control”, Econometric Theory.

The counterfactual comes from a factor model in which the treated unit’s loading changes over time. Three ideas make that estimable.

The first is diversified projection (Fan and Liao, [FanLiao]). A factor is usually extracted as an eigenvector of the donor panel’s covariance, which needs that covariance to have a clean spectrum. Diversified projection instead takes a weighted average across donors, \(\widehat F_{tj} = N^{-1} \sum_i Y_{it} W_{it}^{(j)}\), with weights chosen so that they correlate with the loadings. No eigendecomposition is taken, so the donor panel’s own spectrum never enters.

The second is the sieve. The weights have to correlate with the loadings, and the loadings are unobserved, so they are built from the observed covariates: if the loading at time t is a smooth function of \(X_{it}\), a finite basis in \(X_{it}\) spans that function approximately, and the basis values serve as the weights.

The third is local linear smoothing. With the factors in hand, the treated unit’s loading is fit on the pre-period by a regression that weights nearby periods more than distant ones, giving a level and a slope at \(T_0\), and the slope carries the loading into the post-period.

Notation#

Let \(i = 1\) denote the treated unit and \(i = 2, \ldots, N + 1\) the donors, observed over \(t = 1, \ldots, T\). Treatment begins at \(T_0 + 1\), giving \(T_1 = T - T_0\) post-treatment periods. Following Abadie’s potential-outcome notation, \(Y_{it}^N\) is the outcome without intervention and \(Y_{it}^I\) the outcome with it, so the observed outcome is \(Y_{1t} = Y_{1t}^N\) for \(t \le T_0\) and \(Y_{1t} = Y_{1t}^I\) after.

\(\mathbf F_t \in \mathbb R^J\) is the vector of \(J\) latent factors at time t and \(\boldsymbol\beta_{it} \in \mathbb R^J\) the loading of unit i at time t, so the no-intervention outcome is \(Y_{it}^N = \boldsymbol\beta_{it}^\top \mathbf F_t + u_{it}\). The loading carries a time subscript, which is the model’s departure from a conventional factor structure.

\(X_{it} \in \mathbb R^P\) are the observed covariates and \(W_{it}^{(j)}\) the j-th diversified weight built from them. \(K(\cdot)\) is the Epanechnikov kernel, \(h\) the bandwidth as a fraction of the sample, and \(K_h(\cdot) = h^{-1} K(\cdot / h)\).

The estimand is

\[\alpha = \frac{1}{T_1} \sum_{t = T_0 + 1}^{T} \mathbb E \bigl( Y_{1t}^I - Y_{1t}^N \bigr) K_h\!\left( \frac{t - T_0}{T_1} \right).\]

Setting \(K\) to the constant 1 recovers the ATT, so ATEL nests it and differs from it only in the weights.

Assumptions#

Assumption 1 (time-varying factor structure). The no-intervention outcomes follow \(Y_{it}^N = \boldsymbol\beta_{it}^\top \mathbf F_t + u_{it}\) with a fixed number \(J\) of factors, and the loading path \(\boldsymbol\beta_{it} = \boldsymbol\beta_i(t/T)\) is smooth in rescaled time.

Remark. The smoothness is what makes a local fit informative: within a window of width \(\lfloor T_0 h \rfloor\) the loading is approximately constant, so the periods in that window speak to the same quantity. A loading that jumps – a merger, a redefinition of the series – violates this at the jump, and the fit near it averages two different regimes.

Assumption 2 (the covariates span the loadings). The loading is a smooth function of the observed covariates, well approximated by the chosen sieve, and the resulting weights satisfy Fan and Liao’s rank condition: the matrix \(\mathbb E [ W_{it} \boldsymbol\beta_{it}^\top ]\) has full rank J.

Remark. This assumption has two halves and only one of them is checkable. Fan and Liao’s Assumption 2.1 asks that the weights be bounded and that \(\lambda_{\min}(W'W / N)\) stay away from zero, so the weight series are not carrying the same information as each other. That is a number, and it comes back on the result as diagnostics["weight_lambda_min"]. Their rank condition, \(\mathrm{rank}(W'B/N) = r\), involves the unobserved loadings and cannot be checked at all: if the weights carry no information about the loadings, the factors are noise and nothing downstream reports a problem. So read the conditioning diagnostic, choose weights that plausibly relate to the unit’s exposure to common shocks, and read the implied donor weights to see which donors the answer rests on.

Assumption 3 (no anticipation, untreated donors). The treated unit is unaffected before \(T_0 + 1\), and no donor is treated over the sample, so both the factors and the pre-period loading are estimated from no-intervention outcomes.

Remark. ATEL is more exposed to this than a long-horizon estimator. Its weight is concentrated at the adoption date, so contamination in the periods either side of \(T_0\) lands where the estimate is most sensitive. A treated unit that responds in anticipation biases exactly the periods the kernel weights most.

Assumption 4 (the loading extrapolates). The level and slope fit at \(T_0\) continue to describe the treated unit’s no-intervention loading over the post-period.

Remark. This is a linear extrapolation of a smooth path, so its error grows with distance from \(T_0\). The localization and this assumption support each other: the kernel puts its weight where the extrapolation is most reliable, and the extrapolation is only asked to travel as far as the kernel’s weight does.

Assumption 5 (regularity for inference). The idiosyncratic errors satisfy the moment and weak-dependence conditions of [ATEL] Theorem 1, and \(N, T_0, T_1\) are large enough for the normal approximation, with \(h \to 0\) and \(T_0 h \to \infty\).

Remark. The two bandwidth conditions conflict at any finite sample size: a small h localizes the estimand but leaves few effective observations. The cross-validated default resolves it by fit, and the estimator says when that resolution lands at an endpoint of the search grid, which means the criterion was still improving where the grid stopped.

Mathematical Formulation#

Step 1, the weights. For each covariate p, evaluate a sieve basis of width J at every \(X_{it,p}\) pooled over all units and periods, giving \(J \times P\) weight series. The B-spline basis takes its order from the width: linear at \(J = 2\), quadratic at \(J = 3\), cubic with \(J - 2\) breakpoints above that.

Step 2, the factors. For \(j = 1, \ldots, J\),

\[\widehat F_{tj} = \frac{1}{N} \sum_{i = 2}^{N + 1} Y_{it} W_{it}^{(j)} .\]

Step 3, the loading. With \(\mathbf Z_t = [\widehat{\mathbf F}_t,\ \widehat{\mathbf F}_t (t/T_0 - 1)]\) and kernel weights \(k_t\) one-sided at \(T_0\),

\[(\widehat{\mathbf b}_0, \widehat{\mathbf b}_1) = \arg\min_{\mathbf b} \sum_{t = 1}^{T_0} k_t \bigl( Y_{1t} - \mathbf Z_t^\top \mathbf b \bigr)^2 ,\]

and the post-period loading is \(\widehat{\boldsymbol\beta}_{1t} = \widehat{\mathbf b}_0 + \widehat{\mathbf b}_1 (T_0 - t)/T_1\).

Step 4, the counterfactual. \(\widehat Y_{1t}^N = \widehat{\boldsymbol\beta}_{1t}^\top \widehat{\mathbf F}_t\) for \(t > T_0\).

Step 5, the estimate. With \(\widetilde T_1 = \lfloor T_1 h \rfloor\) and \(\kappa_t = 2 K((t - T_0)/\widetilde T_1)\),

\[\widehat\alpha = \frac{1}{\widetilde T_1} \sum_{t = T_0 + 1}^{T} \bigl( Y_{1t} - \widehat Y_{1t}^N \bigr) \kappa_t .\]

The kernel is one-sided with its mass doubled, since \(T_0\) is an endpoint of the sample and only half the Epanechnikov support is available.

Inference and diagnostics#

The interval on \(\widehat\alpha\) comes from [ATEL] Theorem 1, whose variance has two parts: the sampling error in the estimated loading, propagated through the kernel-weighted aggregation, and the treated unit’s own idiosyncratic errors over the effective window. Both are built from pre-period residuals refit period by period with the Su and Wang ([SuWang]) boundary kernel. The p-value uses \(t_{\widetilde T_1 - 1}\).

Five diagnostics come back on the result, and each answers a question the point estimate alone does not.

kernel_weights is the weight on each post-period. They do not sum to one, so a constant effect d gives an estimate of d times their mass, available as kernel_mass. Reading these tells you which periods the number is made of.

implied_donor_weights is the weight each donor carries at each post-period. Substituting the projection into the counterfactual,

\[\widehat Y_{1t}^N = \sum_{i} Y_{it} \Bigl[ \frac{1}{N} \sum_j \widehat\beta_{1t,j} W_{it}^{(j)} \Bigr],\]

so ATEL is a donor-weighting estimator whose weights move over time. They come from a projection, so they are unconstrained in sign and do not sum to one. The standardized weights slot carries each donor’s path averaged against the kernel, which is the weight it carries in the reported estimate.

diagnostics["bandwidth_at_grid_edge"] records whether the cross-validated bandwidth landed on an endpoint of the search grid, and the estimator warns when it does. An endpoint means the criterion was still improving where the grid ran out, so the bandwidth is a corner solution and not an interior optimum. On the paper’s own Arizona panel this happens at every factor count tried: the selected h is 0.95, the top of the grid, and the smoothing window then spans 16 of 17 pre-periods, so the local fit is close to a global one.

diagnostics["weight_lambda_min"] is \(\min_t \lambda_{\min}(W_t' W_t / N)\) over the periods, the checkable half of Fan and Liao’s Assumption 2.1 evaluated on the cross-section actually projected. Near zero means two weight series carry the same information and the projection has fewer usable directions than its factor count suggests. diagnostics["weight_source"] records which construction produced them.

pointwise_standard_errors supports a band around the counterfactual path. This needs the treated unit’s loading path to be independent and normal across periods, which is stronger than Theorem 1 requires. The interval on \(\widehat\alpha\) is the defensible output; treat the band as indicative.

Where the weights come from#

weight_source picks the construction, following Fan and Liao’s Section 4. Only the first of the three needs covariates.

weight_source

Fan-Liao

What builds the weights

What it assumes

"covariates"

4.1

a sieve basis in the observed covariates at every unit-period

the loadings are driven by those covariates

"initial"

4.3

a sieve basis in each unit’s first outcome, \(\phi_k(x_{i0})\)

\((f_0, u_0)\) independent of the later errors

"hadamard"

4.4

deterministic sign columns, no data at all

nothing about the data; the rank condition holds only generically

"covariates" is the default and is what the paper uses. The other two exist because the projection does not need covariates – a panel carrying only an outcome and a treatment indicator is still usable.

"initial" holds out the first period, since that is what the weights are built from, and leaving it in would return the outcome the weights came from to the fit they are used for. The pre-period count therefore drops by one.

What these constructions must not be is a function of the errors they are meant to diversify away. A tempting choice is each unit’s pre-period mean outcome, which keeps post-treatment information out and still violates the assumption, because the mean is a function of the pre-period errors the loading is fit on. On the HCW panel that choice moves the estimate from 0.026-0.034 across factor counts to 0.032-0.046 drifting upward, and away from what the rest of the library reports. The initial observation is the legitimate version of the same idea.

Fan and Liao’s Section 4.2, weights from trimmed principal-component loadings on an earlier sample split, is not offered. It needs a split and serial independence of the errors, which is a different assumption burden.

Which basis, and why it matters here#

For "initial" the choice of basis decides whether Assumption 2.1(ii) survives. Fan and Liao’s own simulations use the polynomial \(\phi_k(z) = z^k\), which is fine for a covariate of order one. An outcome in natural units is often far smaller, and then the monomials collapse onto each other. On the HCW panel, where the initial growth rates run -0.03 to 0.14:

basis

J

\(\lambda_{\min}(W'W/N)\)

\(\mathrm{cond}(W)\)

\(\max|w|\)

polynomial

2

5.3e-06

2.3e+01

0.14

polynomial

6

1.6e-17

1.3e+07

0.14

bspline

2

1.1e-01

2.2e+00

1.00

bspline

6

1.2e-03

1.4e+01

1.00

The B-spline basis satisfies both halves of Assumption 2.1 comfortably and without rescaling: partition of unity bounds the entries at one exactly, and the knots come from the data’s own range, so the result does not depend on the units the outcome is measured in. It is the default for every source.

The trigonometric basis is the one to avoid at an even factor count: an intercept plus complete cos/sin pairs fills an odd number of columns, so the last one is zero and \(\lambda_{\min}\) is exactly zero. ATEL refuses that configuration where the projection would consume the empty column.

The factor count and the covariate count#

n_factors is required, and it must be a multiple of the number of covariates. Both constraints come from measurement on the reference implementation.

It is required because the information criterion that would choose it does not choose. On the paper’s Arizona panel the criterion is monotone over its whole candidate range, so it returns an endpoint of that range under either extremum: the residual it penalises is an in-sample projection onto \(2J\) directions against \(N = 14\) donors, and it collapses to zero once \(2J\) reaches N, taking the criterion with it. See ATEL — Average Treatment Effect Localization (Lee 2026) for the full decomposition.

Being required is less of an imposition than it sounds, because the theory says what to do instead. Fan and Liao ([FanLiao]) prove the projection valid for any working number of factors \(R \ge r\), admitting even \(r = 0\) with \(R \ge 1\), and advise taking “a slightly large R so that \(R \ge r\) is likely to hold”. Over-estimating is proved safe; under-estimating is not. There is a second reason to be generous: their rank condition fails when more than \(R - r\) weight series are nearly orthogonal to the loadings, and extra series make that less likely. So pick a count a little above what you think the panel supports and report it, instead of hunting for a number the data will not give you.

This is also why the paper can claim its results do not rely on accurate estimation of J while its own selection criterion is broken. The claim rests on Fan and Liao’s theorem, not on the criterion, and the two are compatible: the criterion is superfluous.

It must be a multiple of the covariate count because the projection consumes the first J of the \(J \times P\) weight blocks, which is a complete set of (basis, covariate) pairs only in that case. Otherwise the slice takes some basis for one covariate and not another, and the estimate depends on the order the covariates are named – on the Arizona panel, by 22.6 at \(J = 3\) and 71.4 at \(J = 5\), against standard errors near 13. Such a configuration raises MlsynthConfigError at construction.

Example#

import pandas as pd
from mlsynth import ATEL

# UK inward FDI against 29 OECD comparators, 1990-2017.
# The Brexit referendum lands in 2016, giving 22 pre-periods and 6 after.
df = pd.read_csv("basedata/fdi_oecd_brexit.csv")

res = ATEL({
    "df": df, "outcome": "fdi", "treat": "treated",
    "unitid": "country", "time": "year",
    "covariates": ["log_gdp", "log_gdp_percap"],
    "n_factors": 2,
    "display_graphs": False,
}).fit()

print(res.atel)                      # the localized estimate
print(res.inference.ci_lower, res.inference.ci_upper)
print(res.att)                       # the unweighted post-period mean
print(res.kernel_mass)               # what a constant effect would scale by
print(res.diagnostics["bandwidth_at_grid_edge"])

A panel with no covariates at all works the same way, with the weights coming from each unit’s first outcome:

# Hsiao, Ching and Wan (2012): Hong Kong quarterly GDP growth against 24
# comparator economies, integration with mainland China from quarter 44.
# The file carries an outcome and a treatment indicator, nothing else.
df = pd.read_csv("basedata/HongKong.csv")

res = ATEL({
    "df": df, "outcome": "GDP", "treat": "Integration",
    "unitid": "Country", "time": "Time",
    "weight_source": "initial",
    "n_factors": 3,
    "display_graphs": False,
}).fit()

print(res.atel, res.att)                      # 0.0324, 0.0346
print(res.diagnostics["weight_lambda_min"])   # 0.0301, the conditioning check

Two things this panel shows. The estimate sits beside what the library already reports – Forward Difference-in-Differences (FDID) gives 0.02540 and Factor Model Approach (FMA) 0.02543 – and the pre-treatment fit is tighter than either, with an RMSE of 0.0143 at three factors and 0.0132 at six against 0.0162 and 0.0177, on weights built from one observation per unit.

And the asymmetry between over- and under-estimating the factor count is visible directly. At three factors and above the estimate settles: 0.0324, 0.0317, 0.0309, 0.0312 for J of 3, 4, 5, 6. At two factors it is 0.0171, a different answer, which is what taking R below r looks like. The cost of going the other way is not in the estimate but in the conditioning, which falls from 1.1e-01 at two factors to 1.2e-03 at six: over-estimating stays valid and gradually spends the weights’ independence, so there is a practical ceiling even though there is no correctness one.

What this panel does not show is why you would localize. Whether atel lands above or below att here depends on the selected bandwidth – above it at two factors, below it at three – because the kernel’s window moves with h and the post-period gap is not monotone. A panel whose effect has a clear direction over the post-period is where the estimand earns its place, and this is not one.

res.atel and res.att are different estimands and neither substitutes for the other: atel is the kernel-weighted localized estimate the method is about, and att is the unweighted post-period mean that the two outcome paths imply. res.inference describes atel.

Verification#

ATEL is cross-validated against the author’s MATLAB toolbox (rueichilee/ATEL), run under Octave. The paper’s Section 5 application – Arizona’s 1994 right-to-carry law on violent crime, 14 donor states, 1977-2006 – reproduces every row of its Table 4 to four decimals:

\(J\)

ATEL

Standard error

Order-invariant

2

49.7665

15.0055

yes

3

71.9248

12.3949

no

4

57.8420

13.3495

yes

5

99.0401

13.7880

no

The final column is this implementation’s finding, not the paper’s. The two rows marked no move by 22.6 and 71.4 when the two covariates are passed in the other order, for the reason given above, and ATEL refuses those configurations. Restricted to the two that are order-invariant the estimate is stable, 49.77 and 57.84, a spread well inside one standard error.

Two smaller fixtures are pinned in mlsynth/tests/test_atel.py against the same toolbox: the bundled Brexit panel above and a deterministic synthetic panel, each at \(J = 2\) and \(J = 4\) and at a fixed bandwidth. Agreement is to nine significant figures on the estimate, the standard error and the p-value. The B-spline basis is checked separately against scipy’s BSpline.design_matrix, which computes the same object as the toolbox’s spcol.

See ATEL — Average Treatment Effect Localization (Lee 2026) for the full replication record, including the defects found in the reference implementation along the way.

Core API#

Average Treatment Effect Localization (ATEL).

Lee, R.-C. (2026). “Average Treatment Effect Localization: Projection Methods in Synthetic Control.” Econometric Theory.

ATEL answers a question the ATT does not. A policy evaluated over a long post-period mixes the policy’s effect with whatever the treated unit did in response to it, so an average over the whole post-period can describe the adaptation as much as the intervention. ATEL instead reports

\[\alpha = \frac{1}{T_1} \sum_{t > T_0} \bigl( Y^I_{1t} - Y^N_{1t} \bigr)\, K_h\!\left( \frac{t - T_0}{T_1} \right),\]

a kernel-weighted average localized at the adoption date, so early post-periods count for more than late ones.

The counterfactual comes from a factor model whose loadings vary with time:

  1. A sieve basis in the observed covariates gives diversified weights.

  2. The factors are cross-sectional donor averages against those weights (Fan and Liao 2022), so no eigendecomposition is taken and the donor panel’s own spectrum does not enter.

  3. The treated unit’s loading is fit by local linear regression on the pre-period, with a one-sided kernel at the boundary, and carried into the post-period.

  4. The post-period gap is averaged against the localization kernel, with Theorem 1’s variance for the interval.

Where this sits next to FMA: FMA takes its factors by principal components and holds the loading fixed over time, which recovers a time-average of a loading that moves. ATEL estimates the movement.

Two parameters are required and not selected from the data. The factor count is required because the reference implementation’s information criterion returns an endpoint of its candidate grid on the paper’s own panel. The bandwidth may be cross-validated, and the estimator warns when that search also lands on an endpoint of its grid.

class mlsynth.estimators.atel.ATEL(config: ATELConfig)#

Bases: object

Average Treatment Effect Localization for a single treated unit.

Parameters:

config (ATELConfig) – Validated configuration. See ATELConfig for the parameters, in particular why n_factors is required and why it must be a multiple of the covariate count.

Examples

>>> import pandas as pd
>>> from mlsynth import ATEL
>>> from mlsynth.config_models import ATELConfig
>>> df = pd.read_csv("basedata/fdi_oecd_brexit.csv")
>>> config = ATELConfig(
...     df=df, outcome="fdi", treat="treated",
...     unitid="country", time="year",
...     covariates=["log_gdp", "log_gdp_percap"],
...     n_factors=2, display_graphs=False,
... )
>>> results = ATEL(config).fit()
>>> results.atel
fit() → ATELResults#

Run the ATEL pipeline end to end.

Returns:

ATELResults

Raises:
  • MlsynthDataError – If the panel is unbalanced, a covariate has a missing cell, the pre-period is shorter than twice the factor count, or the localization window is empty.

  • MlsynthEstimationError – If a consumed weight block is identically zero.

Configuration#

class mlsynth.config_models.ATELConfig(*, df: ~pandas.DataFrame, outcome: str, treat: str, unitid: str, time: str, display_graphs: bool = True, save: bool | str = False, counterfactual_color: ~typing.List[str] = <factory>, treated_color: str = 'black', plot: ~mlsynth.config_models.PlotConfig = <factory>, weight_source: ~typing.Literal['covariates', 'initial', 'hadamard'] = 'covariates', covariates: ~typing.List[str] = <factory>, n_factors: ~typing.Annotated[int, ~annotated_types.Ge(ge=2)], basis: ~typing.Literal['bspline', 'trigonometric', 'polynomial'] = 'bspline', bandwidth: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0.0), ~annotated_types.Le(le=1.0)] = None, alpha: ~typing.Annotated[float, ~annotated_types.Gt(gt=0.0), ~annotated_types.Lt(lt=1.0)] = 0.05)#

Configuration for Average Treatment Effect Localization (ATEL).

Implements Lee, R.-C. (2026), “Average Treatment Effect Localization: Projection Methods in Synthetic Control”, Econometric Theory. ATEL reports a kernel-weighted average effect localized at the adoption date, so early post-periods count for more than late ones. The counterfactual comes from a time-varying factor model whose factors are estimated by diversified projection and whose loading is fit by local linear regression.

Parameters:
  • weight_source ({“covariates”, “initial”, “hadamard”}) – Where the diversified weights come from, following the constructions Fan and Liao (2022) Section 4 recommends.

    "covariates" (default) is their Section 4.1: a sieve basis in the observed time-varying covariates, which is what the ATEL paper uses and what requires covariates.

    "initial" is their Section 4.3: a sieve basis in each unit’s first observed outcome, w_ik = phi_k(x_i0), which correlates with the loadings through x_0 = B f_0 + u_0. The first period is held out of the estimation sample, since the weights are built from it. No covariates are needed.

    "hadamard" is their Section 4.4: deterministic sign columns, which satisfy the independence requirement by construction and use no data at all. No covariates are needed.

    Their Section 4.2, weights from trimmed principal-component loadings on an earlier sample split, is not offered: it needs a split and serial independence of the errors, which is a different assumption burden.

  • covariates (list of str) – Time-varying covariate columns. Required, and at least one, when weight_source is "covariates", since the sieve basis in these columns is what builds the weights. Refused for the other sources, which cannot use them.

  • n_factors (int) – Number of factors, which is also the sieve width. Required: the information criterion in the reference implementation returns an endpoint of its candidate grid on the paper’s own panel, so there is no data-driven default here. Must be at least 2.

    With P covariates the projection consumes the first n_factors of the n_factors * P weight blocks, and that set is a complete set of (basis, covariate) pairs only when n_factors is a multiple of P. Otherwise the estimate depends on the order the covariates are named: on the paper’s Arizona panel, swapping two covariates moves the estimate by 22.6 at n_factors = 3 and by 71.4 at n_factors = 5, against standard errors near 13. Such a configuration is refused.

  • basis ({“bspline”, “trigonometric”, “polynomial”}) – Sieve basis. "bspline" is the paper’s recommendation.

  • bandwidth (float or None) – Smoothing bandwidth as a fraction of the sample. None selects one by leave-one-out cross-validation over 0.30 to 0.95 in steps of 0.05, and warns when the criterion lands on an endpoint of that grid.

  • alpha (float) – Two-sided significance level for the interval on the localized estimate.

alpha: float#
bandwidth: float | None#
basis: Literal['bspline', 'trigonometric', 'polynomial']#
check_atel_params() → Any#
covariates: List[str]#
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_factors: int#
weight_source: Literal['covariates', 'initial', 'hadamard']#

Helper Modules#

Panel ingestion for the ATEL estimator.

Outcomes come through mlsynth.utils.datautils.dataprep(), which supplies the treated series, the donor matrix, the sorted period labels and the count of pre-treatment periods. The covariates are pivoted separately and aligned to that same unit and period order, so the cube and the outcome panel cannot disagree about which row is which unit.

dataprep aggregates its own covariates argument to pre-period means, which is the wrong shape here: the sieve needs each covariate at every unit-period, since that is what makes the loading vary with time.

Two requirements go beyond what dataprep enforces, and each is checked with its own message: the covariates are fully observed, because a missing cell has no basis value; and the pre-period is strictly longer than twice the factor count, because the local linear design carries a level and a slope per factor and the variance needs a residual degree of freedom left over.

When the weights come from the first observation (Fan and Liao 2022 Section 4.3) that period is held out here, so nothing the weights were built from remains in the sample the loading is fit on.

mlsynth.utils.atel_helpers.setup.prepare_atel_inputs(df: DataFrame, outcome: str, treat: str, unitid: str, time: str, covariates: List[str], n_factors: int, weight_source: str = 'covariates') → ATELInputs#

Assemble the outcome panel and covariate cube ATEL runs on.

Parameters:
  • df (pd.DataFrame) – Long balanced panel, one row per (unit, period).

  • outcome, treat, unitid, time (str) – Column names.

  • covariates (list of str) – Time-varying covariate columns. Empty unless the weights come from them.

  • n_factors (int) – Number of factors, used only to check the pre-period is long enough.

  • weight_source (str) – "covariates", "initial" or "hadamard". Only "initial" changes ingestion, by holding out the first period.

Returns:

ATELInputs

Raises:

MlsynthDataError – If a named column is absent, the panel is unbalanced, a covariate has a missing cell, no covariate is given, or the pre-period is shorter than twice the factor count.

Sieve bases and the diversified weights they build.

ATEL approximates the time-varying factor loading by a sieve in the observed covariates: the loading on factor j at time t is a smooth function of \(X_{it}\), and the sieve replaces that function by a finite basis. The basis values themselves become the diversified weights \(W_{it}^{(j)}\) that factors averages donor outcomes against.

Three bases follow Lee (2026) and the author’s toolbox: B-spline (the paper’s recommendation), trigonometric, and polynomial.

One layout detail decides which weight series the projection sees. construct_weights() emits J * P blocks of T columns each, ordered by (basis j, covariate p) with p inner, and diversified_factors() consumes the first J of them. With P covariates the consumed set is a complete set of (basis, covariate) pairs exactly when J is a multiple of P; ATELConfig refuses the other cases, because there the estimate depends on the order the covariates are named.

mlsynth.utils.atel_helpers.sieve.basis_values(x: ndarray, J: int, basis: str) → ndarray#

Dispatch to one of the three sieve bases.

mlsynth.utils.atel_helpers.sieve.bspline_weights(x: ndarray, J: int) → ndarray#

B-spline basis of width J evaluated at x.

The spline order and the breakpoints follow the width: J = 2 is linear with no interior knot, J = 3 quadratic with none, and J >= 4 is cubic over J - 2 breakpoints spanning the range of x. The order therefore changes with J even when the projection goes on to consume only the first few basis functions.

Parameters:
  • x (np.ndarray) – Covariate values, pooled over every unit and period.

  • J (int) – Basis width, at least 2.

Returns:

np.ndarray – Shape (x.size, J); rows sum to one.

Raises:
  • MlsynthConfigError – If J < 2.

  • MlsynthDataError – If x is constant, which leaves the knot vector degenerate.

mlsynth.utils.atel_helpers.sieve.construct_weights(X: ndarray, J: int, basis: str) → ndarray#

Diversified weights for every unit, shape (N + 1, T * J * P).

The basis is fit on each covariate pooled over every unit and period, the treated unit included, so the treated unit’s covariates move the knots. Blocks are ordered by (basis j, covariate p) with p inner.

Parameters:
  • X (np.ndarray) – Covariate cube (N + 1, T, P). A 2-D array is read as P = 1.

  • J (int) – Sieve width.

  • basis ({“bspline”, “trigonometric”, “polynomial”})

Returns:

np.ndarray – Shape (N + 1, T * J * P).

mlsynth.utils.atel_helpers.sieve.hadamard_weights(n_units: int, n_columns: int) → ndarray#

Deterministic sign weights, Fan and Liao (2022) Section 4.4.

The first column is all ones and column k alternates blocks of k - 1 ones and minus ones, which is their simulation choice (i). Being deterministic, these satisfy the independence half of Assumption 2.1 by construction, and the bounded-entries half exactly. What they cannot guarantee is the rank condition against the unobserved loadings, since they carry no information about them – which is a reason to take more columns than factors, not fewer.

Parameters:
  • n_units (int) – Number of units the weights apply to.

  • n_columns (int) – Number of weight series, at least 2.

Returns:

np.ndarray – Shape (n_units, n_columns), entries in {-1, +1}.

mlsynth.utils.atel_helpers.sieve.poly_weights(x: ndarray, J: int) → ndarray#

Monomial basis [x, x^2, ..., x^J], with no intercept.

mlsynth.utils.atel_helpers.sieve.tile_unit_weights(unit_weights: ndarray, n_periods: int) → ndarray#

Lay unit-level weights out in the block layout the projection reads.

A weight that does not move with time still has to be presented as one block of n_periods identical columns per weight series, because diversified_factors() slices by period block.

mlsynth.utils.atel_helpers.sieve.trig_weights(x: ndarray, J: int) → ndarray#

Trigonometric basis: an intercept then floor((J-1)/2) cos/sin pairs.

An intercept plus complete pairs fills an odd number of columns, so an even width leaves the last column at zero. Whether such a column reaches the projection depends on J and the covariate count together, and factors refuses a consumed block that is identically zero.

mlsynth.utils.atel_helpers.sieve.weight_conditioning(donor_weights: ndarray, n_factors: int, n_periods: int) → float#

Smallest eigenvalue of W_t' W_t / N over the periods, Assumption 2.1(ii).

Fan and Liao require the weights to be non-degenerate among themselves, uniformly. Evaluated on the cross-section actually projected at each period, this is a number the caller can read: near zero means two weight series are carrying the same information and the projection has fewer usable directions than it appears to.

This says nothing about the rank condition rank(W'B / N) = r, which involves the unobserved loadings and stays undiagnosable.

Diversified projection: factors as cross-sectional weighted averages.

Fan and Liao (2022) estimate the factors without an eigendecomposition. Given weights \(W_{it}^{(j)}\) that correlate with the loadings, the j-th factor at time t is the donor-average

\[\widehat F_{tj} = \frac{1}{N} \sum_{i=1}^{N} Y_{it} W_{it}^{(j)},\]

which is linear in the outcomes and invariant to how the donors are ordered. The estimate of the loading space comes from the covariates, so nothing here depends on the donor panel’s own spectrum.

mlsynth.utils.atel_helpers.factors.diversified_factors(donor_outcomes: ndarray, weights: ndarray, n_factors: int) → ndarray#

Factors (T, n_factors) from the donor panel and the weight blocks.

The j-th factor uses weight columns j*T : (j+1)*T of weights, whose first row belongs to the treated unit and is dropped. See sieve for why the first n_factors blocks are the ones consumed.

Parameters:
  • donor_outcomes (np.ndarray) – Donor outcomes (N, T).

  • weights (np.ndarray) – Diversified weights for every unit (N + 1, T * J * P).

  • n_factors (int) – Number of factors, the J of the sieve.

Returns:

np.ndarray – Shape (T, n_factors).

Raises:

MlsynthEstimationError – If a consumed weight block is identically zero, which would return a factor that is identically zero and a singular local-linear design.

Bandwidth selection and the time-varying loading.

The loading on the treated unit moves with time, so it is fit by local linear regression on the pre-period and carried into the post-period. Because the estimand sits at \(T_0\), which is an endpoint of the sample, the kernel is one-sided with its mass doubled instead of renormalised by its truncated integral – the treatment the reference implementation uses on the estimation path.

The bandwidth comes from leave-one-out cross-validation over a fixed grid (paper eq. 20). The kernel there is centred on the last pre-period for every held-out t, so the criterion scores prediction at the point the estimand is localised at and not at each t in turn.

mlsynth.utils.atel_helpers.loadings.BANDWIDTH_GRID = array([0.3 , 0.35, 0.4 , 0.45, 0.5 , 0.55, 0.6 , 0.65, 0.7 , 0.75, 0.8 ,        0.85, 0.9 , 0.95])#

The reference implementation’s bandwidth grid, 0.30 to 0.95 in steps of 0.05.

mlsynth.utils.atel_helpers.loadings.cv_bandwidth(treated_pre: ndarray, factors_pre: ndarray) → float#

Leave-one-out bandwidth over BANDWIDTH_GRID.

Parameters:
  • treated_pre (np.ndarray) – Treated outcomes over the pre-period, shape (T0,).

  • factors_pre (np.ndarray) – Estimated factors over the pre-period, shape (T0, J).

Returns:

float – The grid point minimising the criterion. Ties take the smallest.

mlsynth.utils.atel_helpers.loadings.half_epanechnikov(u: ndarray, side: str) → ndarray#

Epanechnikov weight on one side of its support, mass doubled.

Parameters:
  • u (np.ndarray) – Scaled distance from the localization point.

  • side ({“left”, “right”}) – "left" keeps u >= -1 (pre-period), "right" keeps u <= 1 (post-period).

Returns:

np.ndarray – 1.5 (1 - u^2) inside the half support, zero outside.

mlsynth.utils.atel_helpers.loadings.local_linear_loadings(treated_outcome: ndarray, factors_pre: ndarray, bandwidth: float) → ndarray#

Loadings for each post-period, shape (J, T1).

The local linear fit at \(T_0\) gives a level and a slope per factor; the slope carries the loading forward as (T0 - t) / T1 for each post-period t, so the loading is extrapolated linearly in rescaled time.

mlsynth.utils.atel_helpers.loadings.post_period_kernel(n_pre: int, n_total: int, scaled_window: int) → ndarray#

Localization weights for each post-period (paper eq. 5).

Theorem 1’s variance for the localized estimand, and the pointwise band.

Two components. \(\Sigma_1\) propagates the sampling error in the estimated loading through the kernel-weighted post-period aggregation; \(\Sigma_2\) is the contribution of the treated unit’s own idiosyncratic errors over the effective smoothing window. Both are built from the pre-period residuals, which are refit here period by period with the Su and Wang (2017) boundary kernel.

That boundary kernel divides the Epanechnikov weight by its integral over the truncated support. The normalizer is one scalar multiplying the whole kernel vector for a given period, and it enters only through the weighted least-squares solve in weighted_ls(), which is invariant to a positive rescaling of the weights. It therefore cannot move a reported number, and the reference implementation’s left-branch form is kept as written.

The pointwise band is a different object from the interval on the localized estimand: it requires the treated unit’s loading path to be independent and normal across periods, which is a stronger assumption than Theorem 1 needs. The interval on the estimate is the defensible output.

mlsynth.utils.atel_helpers.inference.atel_variance(treated_outcome: ndarray, factors_pre: ndarray, factors_post: ndarray, bandwidth: float) → Tuple[float, ndarray, ndarray]#

Theorem 1’s variance, with the pre-period fit and residuals.

Returns:

tuple – (variance, fitted_pre, residuals_pre).

mlsynth.utils.atel_helpers.inference.boundary_kernel(periods: ndarray, t: int, n_pre: int, window: int, bandwidth: float) → ndarray#

Su and Wang (2017) boundary kernel centred on period t.

Inside the interior the weight is the plain Epanechnikov. In the two boundary regions it is divided by the kernel’s integral over the part of the support that remains, which keeps the weights’ order uniform in t.

mlsynth.utils.atel_helpers.inference.pointwise_variance(factors: ndarray, loadings: ndarray, residuals_pre: ndarray, bandwidth: float, n_post: int) → ndarray#

Per-period variance of the counterfactual path, shape (T1,).

This supports a band around the counterfactual, under the stronger independent-normal assumption on the loading path noted in the module docstring.

mlsynth.utils.atel_helpers.inference.pre_period_residuals(treated_outcome: ndarray, factors_pre: ndarray, bandwidth: float) → Tuple[ndarray, ndarray]#

Fitted values and residuals over the pre-period, one local fit per period.

Returns:

tuple of np.ndarray – (fitted, residuals), each shape (T0,).

The weighted least-squares solve the three estimation steps share.

Every stage of ATEL – the bandwidth search, the loading fit, and the variance’s pre-period refit – solves the same kernel-weighted normal equations. Both the factor block and the local-linear block are built from the same factors, so the design is near-singular by construction and the pseudo-inverse’s cutoff decides what is treated as rank. The tolerance here is the one the reference implementation uses, max(shape) * eps relative to the largest singular value, which is Octave’s and MATLAB’s pinv default; numpy’s own default of 1e-15 is tighter and moves the fit on these designs.

mlsynth.utils.atel_helpers.numerics.reference_pinv(A: ndarray) → ndarray#

Pseudo-inverse at max(shape) * eps(norm(A)), the reference tolerance.

mlsynth.utils.atel_helpers.numerics.weighted_ls(design: ndarray, kernel: ndarray, target: ndarray) → ndarray#

Solve (X' K X)^+ X' K y for a diagonal kernel K.

A positive rescaling of kernel leaves the result unchanged, which is why a kernel normalizer that is off by a constant factor cannot move any reported number.

Orchestration for ATEL, Steps 1-5 of Lee (2026).

  1. Build the diversified weights, from a sieve basis in the covariates, in each unit’s first outcome, or from deterministic sign columns (sieve); weight_source picks which.

  2. Estimate the factors as cross-sectional donor averages against those weights (factors).

  3. Fit the time-varying loading on the treated unit’s pre-period by local linear regression, selecting the bandwidth by cross-validation if none is supplied (loadings).

  4. Carry the loading into the post-period and form the counterfactual.

  5. Average the post-period gap against the localization kernel, and attach Theorem 1’s variance (inference).

mlsynth.utils.atel_helpers.pipeline.run_atel(inputs: ATELInputs, n_factors: int, basis: str = 'bspline', bandwidth: float | None = None, alpha: float = 0.05, weight_source: str = 'covariates') → Tuple[Dict[str, Any], Dict[str, Any]]#

Run the ATEL pipeline.

Returns:

tuple of dict – (estimates, diagnostics). estimates carries the localized estimate, its interval, the counterfactual path and the intermediate arrays; diagnostics records the bandwidth search and the windows.

Plot helper for ATEL.

Two panels, because the localization is the point. The upper panel is the usual observed-versus-counterfactual path with the pointwise band over the post-period; the lower panel is the localization weight on each post-period, so a reader can see which periods the reported estimate is actually made of.

The helper builds a figure and returns it. Displaying, saving and closing belong to the caller.

mlsynth.utils.atel_helpers.plotter.plot_atel(results: ATELResults, observed_color: str = 'black', counterfactual_color: str = 'red', outcome_label: str = 'Outcome', time_axis_label: str = 'Time', figsize: tuple | None = None)#

Observed versus counterfactual, with the localization weights beneath.

Parameters:
  • results (ATELResults) – A fitted result.

  • observed_color, counterfactual_color (str) – Line colors.

  • outcome_label, time_axis_label (str) – Axis labels.

  • figsize (tuple, optional) – Figure size; defaults to (9, 7).

Returns:

matplotlib.figure.Figure

Note

ATEL.fit() returns an EffectResult on the standardized two-family contract, so res.att / res.att_ci / res.counterfactual / res.gap / res.pre_rmse / res.donor_weights all resolve. The localized estimate is res.atel, also mirrored in res.effects.additional_effects["atel"], and res.inference describes it.

Typed containers for the ATEL estimator.

class mlsynth.utils.atel_helpers.structures.ATELInputs(outcomes: ndarray, covariates: ndarray, n_pre: int, unit_labels: ndarray, time_labels: ndarray, covariate_names: Tuple[str, ...], initial_outcome: ndarray | None = None)#

The arrays Lee (2026) Steps 1-5 run on.

Parameters:
  • outcomes (np.ndarray) – Outcome panel (N + 1, T) with the treated unit in row 0.

  • covariates (np.ndarray) – Covariate cube (N + 1, T, P) in the same unit and period order.

  • n_pre (int) – Number of pre-treatment periods.

  • unit_labels (np.ndarray) – Unit labels, treated first, length N + 1.

  • time_labels (np.ndarray) – Period labels, length T.

  • covariate_names (tuple of str) – Covariate column names, matching the cube’s last axis. Empty when the weights do not come from covariates.

  • initial_outcome (np.ndarray or None) – The outcome at the period held out to build the weights, length N + 1, when weight_source='initial'. None otherwise.

covariate_names: Tuple[str, ...]#
covariates: ndarray#
initial_outcome: ndarray | None = None#
property n_donors: int#

Number of donor units.

property n_periods: int#

Total number of periods.

property n_post: int#

Number of post-treatment periods.

n_pre: int#
outcomes: ndarray#
time_labels: ndarray#
property treated_unit_name: Any#

Label of the treated unit.

unit_labels: ndarray#
class mlsynth.utils.atel_helpers.structures.ATELResults(*, effects: ~mlsynth.config_models.EffectsResults | None = None, fit_diagnostics: ~mlsynth.config_models.FitDiagnosticsResults | None = None, time_series: ~mlsynth.config_models.TimeSeriesResults | None = None, weights: ~mlsynth.config_models.WeightsResults | None = None, inference: ~mlsynth.config_models.InferenceResults | None = None, method_details: ~mlsynth.config_models.MethodDetailsResults | None = None, sub_method_results: ~typing.Dict[str, ~typing.Any] | None = None, additional_outputs: ~typing.Dict[str, ~typing.Any] | None = None, raw_results: ~typing.Dict[str, ~typing.Any] | None = None, execution_summary: ~typing.Dict[str, ~typing.Any] | None = None, plot_config: ~mlsynth.config_models.PlotConfig | None = None, atel: float, bandwidth: float, n_factors: int, factors: ~numpy.ndarray, loadings: ~numpy.ndarray, kernel_weights: ~numpy.ndarray, weights_matrix: ~numpy.ndarray, implied_donor_weights: ~numpy.ndarray, pointwise_standard_errors: ~numpy.ndarray, inputs: ~mlsynth.utils.atel_helpers.structures.ATELInputs | None = None, diagnostics: ~typing.Dict[str, ~typing.Any] = <factory>)#

Container returned by mlsynth.ATEL.fit().

An EffectResult. ATEL and the ATT are different estimands, so both are reported and neither stands in for the other: effects.att is the unweighted post-period mean gap that the standardized surface computes from the two outcome paths, and atel is the kernel-weighted localized estimate the paper is about. inference carries the interval, standard error and p-value for atel.

Parameters:
  • atel (float) – The localized estimate.

  • bandwidth (float) – Bandwidth used, whether supplied or cross-validated.

  • n_factors (int) – Number of factors, and the sieve width.

  • factors (np.ndarray) – Estimated factors (T, n_factors).

  • loadings (np.ndarray) – Time-varying loadings over the post-period (n_factors, T1).

  • kernel_weights (np.ndarray) – Localization weights on each post-period, length T1. They do not sum to one, so a constant effect d gives atel of d times their mass and not d itself.

  • weights_matrix (np.ndarray) – The diversified weights for every unit, (N + 1, T * R) in the block layout the projection reads. What built them is recorded in diagnostics["weight_source"], and how well conditioned they are in diagnostics["weight_lambda_min"].

  • implied_donor_weights (np.ndarray) – The weight each donor carries at each post-period, (N, T1). The counterfactual is sum_i Y_it * implied_donor_weights[i, t] exactly. These come from a projection, so they are unconstrained in sign and do not sum to one. The standardized weights slot carries each donor’s path averaged against the localization kernel, which is the weight it carries in the reported estimate.

  • pointwise_standard_errors (np.ndarray) – Per-period standard error of the counterfactual, length T1. These need the treated unit’s loading path to be independent and normal across periods, a stronger assumption than the interval on atel uses.

  • inputs (ATELInputs or None) – The ingested panel.

  • diagnostics (dict) – Free-form diagnostics: the cross-validation grid, whether the selected bandwidth is an endpoint of it, and the effective windows.

atel: float#
bandwidth: float#
diagnostics: Dict[str, Any]#
factors: np.ndarray#
implied_donor_weights: np.ndarray#
inputs: ATELInputs | None#
property kernel_mass: float#

Sum of the localization weights divided by the post-period window.

kernel_weights: np.ndarray#
loadings: np.ndarray#
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True, 'json_encoders': {<class 'numpy.ndarray'>: <function BaseEstimatorResults.Config.<lambda>>}}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_factors: int#
pointwise_standard_errors: np.ndarray#
weights_matrix: np.ndarray#

References#

[ATEL] (1,2,3,4)

Lee, R.-C. (2026). “Average Treatment Effect Localization: Projection Methods in Synthetic Control.” Econometric Theory.

[FanLiao] (1,2)

Fan, J., & Liao, Y. (2022). “Learning Latent Factors from Diversified Projections and Its Applications to Over-Estimated and Weak Factors.” Journal of the American Statistical Association 117(538):909-924.

[SuWang]

Su, L., & Wang, X. (2017). “On Time-Varying Factor Models: Estimation and Testing.” Journal of Econometrics 198(1):84-101.