fix(bartik): proper leave-one-out with regional_shocks panel + fail-loud warning

Pre-fix, `bartik(leave_one_out=True)` (the default!) silently fell
through to the simple Bartik instrument because proper LOO requires
per-region industry growth data that the basic API didn't carry. The
docstring promised "exclude own region from national average" but the
implementation was `pass`. Users relying on LOO got lied to.

Fix:
- Add optional `regional_shocks: pd.DataFrame` (n_units x n_industries)
  parameter. When provided with leave_one_out=True, compute exact
  Borusyak-Hull-Jaravel 2022 LOO: g_k^{-i} = (sum_j g_{jk} - g_{ik})/(n-1),
  then B_i = sum_k s_ik * g_k^{-i}.
- When leave_one_out=True but regional_shocks is missing, emit a
  UserWarning explaining the fallback and remediation — silent bug
  becomes loud.
- Validate regional_shocks shape and industry coverage upfront.

Tests: TestBartikLeaveOneOut (7 cases) covers warn-on-missing,
silent-when-disabled, panel activates LOO, LOO ≠ simple Bartik,
exact-formula match vs. manual computation (rtol=1e-10), and two
validation errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: brycewang-stanford

src/statspai/bartik/shift_share.py

@@ -16,6 +16,8 @@
 """
 
 from typing import Optional, List, Dict, Any
+import warnings
+
 import numpy as np
 import pandas as pd
 from scipy import stats
@@ -31,6 +33,7 @@ def bartik(
     shocks: pd.Series,
     covariates: Optional[List[str]] = None,
     leave_one_out: bool = True,
+    regional_shocks: Optional[pd.DataFrame] = None,
     robust: str = 'hc1',
     alpha: float = 0.05,
 ) -> EconometricResults:
@@ -53,7 +56,23 @@ def bartik(
     covariates : list of str, optional
         Exogenous control variables.
     leave_one_out : bool, default True
-        Compute leave-one-out shocks (exclude own region from national average).
+        Compute leave-one-out shocks (exclude own region from national
+        average). Only takes effect when ``regional_shocks`` is also
+        supplied — without the per-region industry growth panel there
+        is not enough information to reconstruct ``g_k`` excluding
+        region ``i``. When ``leave_one_out=True`` but
+        ``regional_shocks`` is not provided, a ``UserWarning`` is
+        raised and the estimator falls back to the simple Bartik
+        instrument.
+    regional_shocks : pd.DataFrame, optional
+        Regional industry growth matrix (n_units x n_industries). Row
+        ``i``, column ``k`` is the realised growth of industry ``k``
+        in region ``i``. When provided with ``leave_one_out=True``,
+        the instrument uses
+        ``g_k^{-i} = (sum_j g_{jk} - g_{ik}) / (n - 1)`` (Borusyak-
+        Hull-Jaravel 2022-style exact leave-one-out). Row index must
+        align with ``shares``; columns must be a superset of
+        ``shocks.index``.
     robust : str, default 'hc1'
         Standard error type.
     alpha : float, default 0.05
@@ -74,6 +93,7 @@ def bartik(
     estimator = BartikIV(
         data=data, y=y, endog=endog, shares=shares, shocks=shocks,
         covariates=covariates, leave_one_out=leave_one_out,
+        regional_shocks=regional_shocks,
         robust=robust, alpha=alpha,
     )
     return estimator.fit()
@@ -93,6 +113,7 @@ def __init__(
         shocks: pd.Series,
         covariates: Optional[List[str]] = None,
         leave_one_out: bool = True,
+        regional_shocks: Optional[pd.DataFrame] = None,
         robust: str = 'hc1',
         alpha: float = 0.05,
     ):
@@ -103,6 +124,7 @@ def __init__(
         self.shocks = shocks
         self.covariates = covariates or []
         self.leave_one_out = leave_one_out
+        self.regional_shocks = regional_shocks
         self.robust = robust
         self.alpha = alpha
 
@@ -127,17 +149,66 @@ def _validate(self):
         self.shares = self.shares[common]
         self.shocks = self.shocks[common]
 
+        if self.regional_shocks is not None:
+            if self.regional_shocks.shape[0] != len(self.data):
+                raise ValueError(
+                    f"regional_shocks has {self.regional_shocks.shape[0]} "
+                    f"rows but data has {len(self.data)} rows"
+                )
+            missing = set(common) - set(self.regional_shocks.columns)
+            if missing:
+                raise ValueError(
+                    "regional_shocks is missing industries present in "
+                    f"shares/shocks: {sorted(missing)}"
+                )
+            self.regional_shocks = self.regional_shocks[common]
+
     def _construct_instrument(self) -> np.ndarray:
-        """Construct the Bartik instrument: B_i = sum_k(s_ik * g_k)."""
+        """Construct the Bartik instrument.
+
+        - ``B_i = sum_k s_ik * g_k`` (simple Bartik), or
+        - ``B_i = sum_k s_ik * g_k^{-i}`` (leave-one-out) when
+          ``leave_one_out=True`` and ``regional_shocks`` is provided,
+          where ``g_k^{-i} = (sum_j g_{jk} - g_{ik}) / (n - 1)`` is
+          the national industry growth rate computed excluding
+          region ``i`` (Borusyak-Hull-Jaravel 2022).
+
+        Silent-no-op guard: prior to v0.9.13 ``leave_one_out=True``
+        quietly fell through to simple Bartik because the LOO step
+        requires per-region industry growth data that the basic API
+        does not carry. We now warn loudly instead so users notice
+        the fallback.
+        """
         S = self.shares.values  # (n, K)
         g = self.shocks.values  # (K,)
 
-        if self.leave_one_out:
-            # TODO: proper leave-one-out requires additional data structure
-            # For now, use simple Bartik
-            pass
+        if not self.leave_one_out:
+            return S @ g  # (n,)
+
+        if self.regional_shocks is None:
+            warnings.warn(
+                "bartik(leave_one_out=True) requested but "
+                "`regional_shocks` was not supplied. Proper "
+                "leave-one-out requires per-region industry growth "
+                "(n_units x n_industries) to reconstruct g_k^{-i}. "
+                "Falling back to the simple Bartik instrument "
+                "B_i = sum_k s_ik * g_k; pass `regional_shocks=` or "
+                "set `leave_one_out=False` to silence this warning.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return S @ g
 
-        return S @ g  # (n,)
+        G = self.regional_shocks.values.astype(float)  # (n, K)
+        n = G.shape[0]
+        if n < 2:
+            raise ValueError(
+                "leave-one-out requires at least 2 regions"
+            )
+        # g_k^{-i} = (col_sum_k - G[i,k]) / (n - 1)
+        col_sum = G.sum(axis=0, keepdims=True)        # (1, K)
+        g_loo = (col_sum - G) / (n - 1)                # (n, K)
+        return np.einsum('ij,ij->i', S, g_loo)         # (n,)
 
     def _rotemberg_weights(self, B, Y, X_endog, X_exog):
         """

tests/test_bartik.py

@@ -2,6 +2,8 @@
 Tests for Shift-Share (Bartik) IV module.
 """
 
+import warnings
+
 import pytest
 import numpy as np
 import pandas as pd
@@ -146,5 +148,109 @@ def test_no_common_industries(self, bartik_data):
                    shares=shares, shocks=bad_shocks)
 
 
+class TestBartikLeaveOneOut:
+    """v0.9.13: proper leave-one-out requires `regional_shocks` panel.
+
+    Before v0.9.13 `leave_one_out=True` silently fell through to the
+    simple Bartik instrument. Now it either computes the true LOO
+    instrument or warns the user about the fallback.
+    """
+
+    @pytest.fixture
+    def bartik_loo_data(self, bartik_data):
+        """Attach a regional_shocks panel consistent with bartik_data."""
+        data, shares, shocks = bartik_data
+        rng = np.random.default_rng(2026)
+        # Regional industry growth — national shock + regional noise.
+        # Mean across regions is close to the aggregated shock but
+        # leave-one-out must subtract the region's own contribution.
+        G = shocks.values[None, :] + rng.normal(0, 0.01,
+                                                (len(data), len(shocks)))
+        regional = pd.DataFrame(G, columns=shares.columns)
+        return data, shares, shocks, regional
+
+    def test_loo_warns_when_regional_shocks_missing(self, bartik_data):
+        data, shares, shocks = bartik_data
+        with pytest.warns(UserWarning, match="regional_shocks"):
+            bartik(data, y='y', endog='x_endog',
+                   shares=shares, shocks=shocks, leave_one_out=True)
+
+    def test_loo_silent_when_disabled(self, bartik_data):
+        data, shares, shocks = bartik_data
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', UserWarning)
+            bartik(data, y='y', endog='x_endog',
+                   shares=shares, shocks=shocks, leave_one_out=False)
+
+    def test_loo_uses_panel_when_provided(self, bartik_loo_data):
+        data, shares, shocks, regional = bartik_loo_data
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', UserWarning)
+            # Must NOT warn because regional_shocks covers the LOO path
+            result = bartik(data, y='y', endog='x_endog',
+                            shares=shares, shocks=shocks,
+                            regional_shocks=regional,
+                            leave_one_out=True)
+        assert result is not None
+
+    def test_loo_instrument_differs_from_simple_bartik(self, bartik_loo_data):
+        """B_i^{LOO} should differ from B_i^{simple} when regional
+        growth differs from the aggregated shock."""
+        data, shares, shocks, regional = bartik_loo_data
+        model_simple = BartikIV(data=data, y='y', endog='x_endog',
+                                shares=shares, shocks=shocks,
+                                leave_one_out=False)
+        model_simple._validate()
+        B_simple = model_simple._construct_instrument()
+
+        model_loo = BartikIV(data=data, y='y', endog='x_endog',
+                             shares=shares, shocks=shocks,
+                             regional_shocks=regional,
+                             leave_one_out=True)
+        model_loo._validate()
+        B_loo = model_loo._construct_instrument()
+
+        # They should be close (LOO ≈ national when noise is small)
+        # but not identical.
+        assert not np.allclose(B_simple, B_loo)
+        assert np.corrcoef(B_simple, B_loo)[0, 1] > 0.5
+
+    def test_loo_formula_matches_manual_computation(self, bartik_loo_data):
+        """Verify: g_k^{-i} = (sum_j g_{jk} - g_{ik}) / (n - 1)."""
+        data, shares, shocks, regional = bartik_loo_data
+        model = BartikIV(data=data, y='y', endog='x_endog',
+                         shares=shares, shocks=shocks,
+                         regional_shocks=regional,
+                         leave_one_out=True)
+        model._validate()
+        B = model._construct_instrument()
+
+        G = regional.values
+        n, K = G.shape
+        expected = np.zeros(n)
+        for i in range(n):
+            for k in range(K):
+                g_loo_ik = (G[:, k].sum() - G[i, k]) / (n - 1)
+                expected[i] += shares.values[i, k] * g_loo_ik
+        np.testing.assert_allclose(B, expected, rtol=1e-10)
+
+    def test_regional_shocks_wrong_rows_raises(self, bartik_loo_data):
+        data, shares, shocks, regional = bartik_loo_data
+        with pytest.raises(ValueError, match="regional_shocks has"):
+            bartik(data, y='y', endog='x_endog',
+                   shares=shares, shocks=shocks,
+                   regional_shocks=regional.iloc[:50],
+                   leave_one_out=True)
+
+    def test_regional_shocks_missing_industry_raises(self, bartik_loo_data):
+        data, shares, shocks, regional = bartik_loo_data
+        partial = regional.drop(columns=['ind_0'])
+        with pytest.raises(ValueError, match="missing industries"):
+            bartik(data, y='y', endog='x_endog',
+                   shares=shares, shocks=shocks,
+                   regional_shocks=partial,
+                   leave_one_out=True)
+
+
 if __name__ == "__main__":
     pytest.main([__file__, '-v'])