ssiv 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ssiv/__init__.py ADDED
@@ -0,0 +1,38 @@
1
+ """ssiv: shift-share (Bartik) instrumental variables in Python.
2
+
3
+ * :func:`reg_ss`, :func:`ivreg_ss` - OLS and IV with a shift-share variable and
4
+ AKM / AKM0 exposure-robust inference (Adão, Kolesár and Morales, 2019).
5
+ * :func:`rotemberg` - Rotemberg weights (Goldsmith-Pinkham, Sorkin and Swift, 2020).
6
+ * :func:`aggregate`, :func:`shock_level_iv` - shock-level estimation
7
+ (Borusyak, Hull and Jaravel, 2022).
8
+ * :func:`bartik`, :func:`share_sum`, :func:`recover_shocks` - building blocks.
9
+ """
10
+
11
+ from ._version import __version__
12
+ from .inference import (
13
+ METHODS,
14
+ CollinearSharesWarning,
15
+ ShiftShareResult,
16
+ ivreg_ss,
17
+ reg_ss,
18
+ )
19
+ from .instrument import bartik, recover_shocks, share_sum
20
+ from .rotemberg import RotembergResult, rotemberg
21
+ from .shocklevel import ShockLevelResult, aggregate, shock_level_iv
22
+
23
+ __all__ = [
24
+ "METHODS",
25
+ "CollinearSharesWarning",
26
+ "RotembergResult",
27
+ "ShiftShareResult",
28
+ "ShockLevelResult",
29
+ "__version__",
30
+ "aggregate",
31
+ "bartik",
32
+ "ivreg_ss",
33
+ "recover_shocks",
34
+ "reg_ss",
35
+ "rotemberg",
36
+ "share_sum",
37
+ "shock_level_iv",
38
+ ]
ssiv/_design.py ADDED
@@ -0,0 +1,172 @@
1
+ """Assemble arrays from a DataFrame, a share matrix and options."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from dataclasses import dataclass
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+
11
+ ArrayLike = np.ndarray | pd.Series | pd.DataFrame | Sequence[float]
12
+
13
+
14
+ @dataclass
15
+ class Design:
16
+ """Arrays used by the estimators, after dropping incomplete rows."""
17
+
18
+ y: np.ndarray
19
+ x: np.ndarray | None # shift-share variable (regressor or instrument)
20
+ endog: np.ndarray | None # endogenous regressor (IV only)
21
+ z: np.ndarray # controls (incl. intercept)
22
+ w: np.ndarray # regression weights
23
+ shares: np.ndarray # n x S
24
+ sector_names: list
25
+ control_names: list[str]
26
+ region_cluster: np.ndarray | None
27
+ sector_cluster: np.ndarray # length S
28
+ n_dropped: int
29
+ rows: np.ndarray # boolean mask of the rows of data that were used
30
+
31
+ @property
32
+ def n(self) -> int:
33
+ return self.y.size
34
+
35
+
36
+ def _column(data: pd.DataFrame, spec, name: str) -> pd.Series:
37
+ if spec is None:
38
+ raise ValueError(f"{name} is required")
39
+ if isinstance(spec, str):
40
+ if spec not in data.columns:
41
+ raise KeyError(f"column '{spec}' ({name}) not found in data")
42
+ return data[spec]
43
+ arr = np.asarray(spec)
44
+ if arr.ndim != 1 or arr.shape[0] != len(data):
45
+ raise ValueError(f"{name} must have one value per row of data")
46
+ return pd.Series(arr, index=data.index)
47
+
48
+
49
+ def _shares_frame(shares, data: pd.DataFrame) -> pd.DataFrame:
50
+ if isinstance(shares, pd.DataFrame):
51
+ if shares.shape[0] != len(data):
52
+ raise ValueError("shares must have one row per row of data")
53
+ if not shares.index.equals(data.index):
54
+ if set(shares.index) == set(data.index):
55
+ shares = shares.loc[data.index]
56
+ else:
57
+ shares = shares.set_axis(data.index, axis=0)
58
+ return shares.astype(float)
59
+ arr = np.asarray(shares, dtype=float)
60
+ if arr.ndim != 2 or arr.shape[0] != len(data):
61
+ raise ValueError("shares must be a 2-D array with one row per row of data")
62
+ return pd.DataFrame(arr, index=data.index)
63
+
64
+
65
+ def _is_categorical(col: pd.Series) -> bool:
66
+ """Text and category columns become dummies; numbers and booleans enter as values."""
67
+ return not (pd.api.types.is_numeric_dtype(col) or pd.api.types.is_bool_dtype(col))
68
+
69
+
70
+ def controls_matrix(
71
+ data: pd.DataFrame,
72
+ controls: Sequence[str] | None,
73
+ categorical: Sequence[str] | None,
74
+ intercept: bool,
75
+ ) -> pd.DataFrame:
76
+ """Numeric control matrix: intercept, numeric controls and dummies of categoricals.
77
+
78
+ Boolean columns become 0/1. Text and category columns, and any column listed
79
+ in ``categorical``, become dummies with the first level dropped.
80
+ """
81
+ controls = list(controls or [])
82
+ categorical = list(categorical or [])
83
+ parts = []
84
+ if intercept:
85
+ parts.append(pd.Series(1.0, index=data.index, name="(Intercept)"))
86
+ for c in controls:
87
+ if c not in data.columns:
88
+ raise KeyError(f"control '{c}' not found in data")
89
+ col = data[c]
90
+ if c in categorical or _is_categorical(col):
91
+ parts.append(
92
+ pd.get_dummies(col, prefix=c, drop_first=intercept, dummy_na=False).astype(float)
93
+ )
94
+ else:
95
+ parts.append(col.astype(float).rename(c))
96
+ for c in categorical:
97
+ if c not in controls:
98
+ if c not in data.columns:
99
+ raise KeyError(f"categorical '{c}' not found in data")
100
+ parts.append(pd.get_dummies(data[c], prefix=c, drop_first=intercept).astype(float))
101
+ if not parts:
102
+ return pd.DataFrame(index=data.index)
103
+ return pd.concat(parts, axis=1)
104
+
105
+
106
+ def build(
107
+ data: pd.DataFrame,
108
+ *,
109
+ y,
110
+ shares,
111
+ x=None,
112
+ endog=None,
113
+ controls: Sequence[str] | None = None,
114
+ categorical: Sequence[str] | None = None,
115
+ intercept: bool = True,
116
+ weights=None,
117
+ region_cluster=None,
118
+ sector_cluster: ArrayLike | None = None,
119
+ ) -> Design:
120
+ """Collect and align all inputs; drop rows with missing values."""
121
+ if not isinstance(data, pd.DataFrame):
122
+ raise TypeError("data must be a pandas DataFrame")
123
+ sh = _shares_frame(shares, data)
124
+ cols = {"y": _column(data, y, "y")}
125
+ if x is not None:
126
+ cols["x"] = _column(data, x, "x")
127
+ if endog is not None:
128
+ cols["endog"] = _column(data, endog, "endog")
129
+ cols["w"] = (
130
+ pd.Series(1.0, index=data.index) if weights is None else _column(data, weights, "weights")
131
+ )
132
+ if region_cluster is not None:
133
+ cols["region_cluster"] = _column(data, region_cluster, "region_cluster")
134
+ zdf = controls_matrix(data, controls, categorical, intercept)
135
+
136
+ frame = pd.DataFrame({k: v.to_numpy() for k, v in cols.items()}, index=data.index)
137
+ numeric = [k for k in frame.columns if k != "region_cluster"]
138
+ ok = frame[numeric].notna().all(axis=1).to_numpy().copy() # writable under copy-on-write
139
+ ok &= zdf.notna().all(axis=1).to_numpy()
140
+ ok &= sh.notna().all(axis=1).to_numpy()
141
+ if "region_cluster" in frame:
142
+ ok &= frame["region_cluster"].notna().to_numpy()
143
+ w = frame["w"].to_numpy(dtype=float)
144
+ if np.any(w[ok] < 0):
145
+ raise ValueError("weights must be non-negative")
146
+ ok &= w > 0
147
+
148
+ s_count = sh.shape[1]
149
+ if sector_cluster is None:
150
+ sc = np.arange(s_count)
151
+ else:
152
+ sc = np.asarray(sector_cluster)
153
+ if sc.shape[0] != s_count:
154
+ raise ValueError("sector_cluster must have one entry per column of shares")
155
+
156
+ get = lambda k: frame.loc[ok, k].to_numpy(dtype=float) if k in frame else None # noqa: E731
157
+ return Design(
158
+ y=get("y"),
159
+ x=get("x"),
160
+ endog=get("endog"),
161
+ z=zdf.loc[ok].to_numpy(dtype=float),
162
+ w=w[ok],
163
+ shares=sh.loc[ok].to_numpy(dtype=float),
164
+ sector_names=list(sh.columns),
165
+ control_names=list(zdf.columns),
166
+ region_cluster=frame.loc[ok, "region_cluster"].to_numpy()
167
+ if "region_cluster" in frame
168
+ else None,
169
+ sector_cluster=sc,
170
+ n_dropped=int((~ok).sum()),
171
+ rows=ok,
172
+ )
ssiv/_linalg.py ADDED
@@ -0,0 +1,61 @@
1
+ """Weighted least-squares helpers and collinearity detection."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+
7
+
8
+ def wls_residuals(a: np.ndarray, z: np.ndarray | None, w: np.ndarray) -> np.ndarray:
9
+ """Residuals of a weighted least-squares regression of ``a`` on ``z``.
10
+
11
+ ``a`` may be a vector or a matrix (each column is residualised).
12
+ Rank-deficient ``z`` is handled through a minimum-norm solution, which
13
+ leaves the residuals unchanged.
14
+ """
15
+ if z is None or z.shape[1] == 0:
16
+ return np.array(a, dtype=float, copy=True)
17
+ sw = np.sqrt(w)
18
+ a2 = a if a.ndim == 2 else a[:, None]
19
+ coef = np.linalg.lstsq(z * sw[:, None], a2 * sw[:, None], rcond=None)[0]
20
+ r = a2 - z @ coef
21
+ return r if a.ndim == 2 else r[:, 0]
22
+
23
+
24
+ def wls_coef(a: np.ndarray, z: np.ndarray, w: np.ndarray) -> np.ndarray:
25
+ """Weighted least-squares coefficients of ``a`` on ``z``."""
26
+ sw = np.sqrt(w)
27
+ return np.linalg.lstsq(z * sw[:, None], a * sw, rcond=None)[0]
28
+
29
+
30
+ def matrix_rank(z: np.ndarray | None) -> int:
31
+ if z is None or z.shape[1] == 0:
32
+ return 0
33
+ return int(np.linalg.matrix_rank(z))
34
+
35
+
36
+ def independent_columns(a: np.ndarray, tol: float = 1e-7) -> np.ndarray:
37
+ """Boolean mask of columns kept when dropping collinear columns in order.
38
+
39
+ A column is dropped when the norm of its projection off the span of the
40
+ columns kept before it is at most ``tol`` times its own norm. This mirrors
41
+ the column-dropping rule of R's ``lm`` (earlier columns are kept), so the
42
+ same sectors are dropped when a share matrix is collinear.
43
+ """
44
+ n, k = a.shape
45
+ norms = np.linalg.norm(a, axis=0)
46
+ keep = norms > 0
47
+ if np.linalg.matrix_rank(a[:, keep]) == keep.sum():
48
+ return keep
49
+ basis = np.zeros((n, 0))
50
+ for j in range(k):
51
+ if not keep[j]:
52
+ continue
53
+ v = a[:, j].astype(float)
54
+ for _ in range(2): # re-orthogonalise for numerical stability
55
+ v = v - basis @ (basis.T @ v)
56
+ nv = np.linalg.norm(v)
57
+ if nv <= tol * norms[j]:
58
+ keep[j] = False
59
+ else:
60
+ basis = np.column_stack([basis, v / nv])
61
+ return keep
ssiv/_version.py ADDED
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
ssiv/inference.py ADDED
@@ -0,0 +1,368 @@
1
+ """OLS and IV regressions with a shift-share variable, with exposure-robust inference.
2
+
3
+ Implements the AKM and AKM0 confidence intervals of Adão, Kolesár and Morales
4
+ (2019, *Quarterly Journal of Economics* 134(4)), alongside the usual
5
+ homoskedastic, heteroskedasticity-robust (EHW) and region-clustered errors.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import warnings
11
+ from collections.abc import Sequence
12
+ from dataclasses import dataclass, field
13
+ from statistics import NormalDist
14
+ from typing import Literal
15
+
16
+ import numpy as np
17
+ import pandas as pd
18
+
19
+ from . import _design
20
+ from ._linalg import independent_columns, matrix_rank, wls_coef, wls_residuals
21
+
22
+ METHODS = ("homosk", "ehw", "region_cluster", "akm", "akm0")
23
+ LABELS = {
24
+ "homosk": "Homoscedastic",
25
+ "ehw": "EHW",
26
+ "region_cluster": "Reg. cluster",
27
+ "akm": "AKM",
28
+ "akm0": "AKM0",
29
+ }
30
+ SmallSample = Literal["stata", "none"]
31
+ _ND = NormalDist()
32
+
33
+
34
+ class CollinearSharesWarning(UserWarning):
35
+ """Some columns of the share matrix were collinear and were dropped."""
36
+
37
+
38
+ @dataclass
39
+ class ShiftShareResult:
40
+ """Point estimate and inference under several methods.
41
+
42
+ ``table`` has one row per method with columns ``se``, ``p``, ``ci_low`` and
43
+ ``ci_high``. For AKM0 the confidence set comes from test inversion; ``se``
44
+ is its length divided by ``2 z`` (as in ShiftShareSE) and may be infinite
45
+ when the set is unbounded.
46
+ """
47
+
48
+ kind: str
49
+ beta: float
50
+ table: pd.DataFrame
51
+ n: int
52
+ n_sectors: int
53
+ n_sectors_dropped: int
54
+ alpha: float
55
+ beta0: float
56
+ small_sample: str
57
+ y: str
58
+ regressor: str
59
+ instrument: str | None = None
60
+ notes: list[str] = field(default_factory=list)
61
+
62
+ @property
63
+ def se(self) -> pd.Series:
64
+ return self.table["se"]
65
+
66
+ @property
67
+ def pvalues(self) -> pd.Series:
68
+ return self.table["p"]
69
+
70
+ def conf_int(self) -> pd.DataFrame:
71
+ return self.table[["ci_low", "ci_high"]]
72
+
73
+ def summary(self) -> str:
74
+ lvl = int(round((1 - self.alpha) * 100))
75
+ head = (
76
+ f"{'IV' if self.kind == 'iv' else 'OLS'} with a shift-share "
77
+ f"{'instrument' if self.kind == 'iv' else 'regressor'}\n"
78
+ f"Outcome: {self.y} Regressor: {self.regressor}"
79
+ + (f" Instrument: {self.instrument}" if self.instrument else "")
80
+ + f"\nObservations: {self.n} Sectors: {self.n_sectors}"
81
+ + (f" ({self.n_sectors_dropped} collinear dropped)" if self.n_sectors_dropped else "")
82
+ + f"\nEstimate: {self.beta:.7g}\n\n"
83
+ )
84
+ t = self.table.rename(index=LABELS).rename(
85
+ columns={
86
+ "se": "Std. Error",
87
+ "p": f"p-value (H0: beta={self.beta0:g})",
88
+ "ci_low": f"Lower {lvl}% CI",
89
+ "ci_high": f"Upper {lvl}% CI",
90
+ }
91
+ )
92
+ return head + t.to_string(float_format=lambda v: f"{v:.7g}")
93
+
94
+ def __repr__(self) -> str:
95
+ return self.summary()
96
+
97
+
98
+ def _methods(method) -> list[str]:
99
+ if method == "all":
100
+ return list(METHODS)
101
+ ms = [method] if isinstance(method, str) else list(method)
102
+ bad = set(ms) - set(METHODS)
103
+ if bad:
104
+ raise ValueError(f"unknown method(s) {sorted(bad)}; choose from {METHODS} or 'all'")
105
+ return [m for m in METHODS if m in ms]
106
+
107
+
108
+ def _cluster_sums(values: np.ndarray, groups: np.ndarray) -> np.ndarray:
109
+ return pd.Series(values).groupby(groups, sort=False).sum().to_numpy()
110
+
111
+
112
+ def _quadratic_set(a2: float, a1: float, a0: float) -> tuple[float, float]:
113
+ """Set {b : a2 b^2 + a1 b + a0 <= 0}, returned as (low, high).
114
+
115
+ Unbounded or disjoint sets are returned as (-inf, inf).
116
+ """
117
+ disc = a1 * a1 - 4 * a2 * a0
118
+ if a2 > 0 and disc >= 0:
119
+ r = np.sqrt(disc)
120
+ lo, hi = (-a1 - r) / (2 * a2), (-a1 + r) / (2 * a2)
121
+ return float(min(lo, hi)), float(max(lo, hi))
122
+ return float("-inf"), float("inf")
123
+
124
+
125
+ def _fit(
126
+ d: _design.Design,
127
+ *,
128
+ iv: bool,
129
+ method,
130
+ alpha: float,
131
+ beta0: float,
132
+ small_sample: SmallSample,
133
+ names: dict,
134
+ ) -> ShiftShareResult:
135
+ if small_sample not in ("stata", "none"):
136
+ raise ValueError("small_sample must be 'stata' or 'none'")
137
+ ms = _methods(method)
138
+ if "region_cluster" in ms and d.region_cluster is None:
139
+ raise ValueError("method 'region_cluster' needs region_cluster=")
140
+ w, z = d.w, d.z
141
+ n = d.n
142
+ xd = wls_residuals(d.x, z, w)
143
+ yd = wls_residuals(d.y, z, w)
144
+ rd = wls_residuals(d.endog, z, w) if iv else xd
145
+ den = float(np.sum(w * xd * rd))
146
+ scale = max(float(np.sum(w * d.x**2)), np.finfo(float).tiny)
147
+ if float(np.sum(w * xd**2)) <= 1e-12 * scale or den == 0:
148
+ raise ValueError("the shift-share variable has no variation after partialling out controls")
149
+ beta = float(np.sum(w * xd * yd) / den)
150
+ e = yd - beta * rd
151
+ p_reg = matrix_rank(z) + 1
152
+ stata = small_sample == "stata"
153
+ zcrit = _ND.inv_cdf(1 - alpha / 2)
154
+ notes: list[str] = []
155
+
156
+ rows = {}
157
+
158
+ def normal_row(var: float) -> dict:
159
+ se = float(np.sqrt(var))
160
+ t = (beta - beta0) / se if se > 0 else np.inf
161
+ return dict(
162
+ se=se, p=2 * _ND.cdf(-abs(t)), ci_low=beta - zcrit * se, ci_high=beta + zcrit * se
163
+ )
164
+
165
+ if "homosk" in ms:
166
+ sigma2 = float(np.sum(w * e**2)) / (n - p_reg if stata else n)
167
+ rows["homosk"] = normal_row(sigma2 * float(np.sum(w * xd**2)) / den**2)
168
+ if "ehw" in ms:
169
+ v = float(np.sum((w * xd * e) ** 2)) / den**2
170
+ rows["ehw"] = normal_row(v * (n / (n - p_reg) if stata else 1.0))
171
+ if "region_cluster" in ms:
172
+ g = d.region_cluster
173
+ n_g = len(pd.unique(g))
174
+ v = float(np.sum(_cluster_sums(w * xd * e, g) ** 2)) / den**2
175
+ corr = n_g / (n_g - 1) * (n - 1) / (n - p_reg) if stata else 1.0
176
+ rows["region_cluster"] = normal_row(v * corr)
177
+
178
+ n_dropped = 0
179
+ if "akm" in ms or "akm0" in ms:
180
+ sw = np.sqrt(w)
181
+ keep = independent_columns(d.shares * sw[:, None])
182
+ n_dropped = int((~keep).sum())
183
+ if n_dropped:
184
+ warnings.warn(
185
+ f"share matrix is collinear: dropping {n_dropped} sector(s) for AKM inference "
186
+ "(earlier columns are kept; reordering columns can change which are dropped)",
187
+ CollinearSharesWarning,
188
+ stacklevel=3,
189
+ )
190
+ notes.append(f"{n_dropped} collinear sectors dropped for AKM/AKM0")
191
+ sh = d.shares[:, keep]
192
+ clusters = d.sector_cluster[keep]
193
+ # Shocks net of controls: weighted regression of residualised X on raw shares.
194
+ xs_hat = wls_coef(xd, sh, w)
195
+
196
+ if "akm" in ms:
197
+ r = sh.T @ (w * e)
198
+ a = _cluster_sums(xs_hat * r, clusters)
199
+ rows["akm"] = normal_row(float(np.sum(a**2)) / den**2)
200
+
201
+ if "akm0" in ms:
202
+ ry = sh.T @ (w * yd)
203
+ rr = sh.T @ (w * rd)
204
+ ac = _cluster_sums(xs_hat * ry, clusters)
205
+ bc = _cluster_sums(xs_hat * rr, clusters)
206
+ num_y = float(np.sum(w * xd * yd))
207
+ # Test of H0: beta = b uses residuals under the null, y - b * r.
208
+ # Confidence set: {b : (num_y - b den)^2 <= z^2 sum_c (a_c - b b_c)^2}
209
+ a2 = den**2 - zcrit**2 * float(np.sum(bc**2))
210
+ a1 = -2 * num_y * den + 2 * zcrit**2 * float(np.sum(ac * bc))
211
+ a0 = num_y**2 - zcrit**2 * float(np.sum(ac**2))
212
+ lo, hi = _quadratic_set(a2, a1, a0)
213
+ if not np.isfinite(lo):
214
+ notes.append("AKM0 confidence set is unbounded (weak identification)")
215
+ v0 = float(np.sum((ac - beta0 * bc) ** 2))
216
+ t0 = (num_y - beta0 * den) / np.sqrt(v0) if v0 > 0 else np.inf
217
+ rows["akm0"] = dict(
218
+ se=(hi - lo) / (2 * zcrit), p=2 * _ND.cdf(-abs(t0)), ci_low=lo, ci_high=hi
219
+ )
220
+
221
+ table = pd.DataFrame.from_dict(rows, orient="index")[["se", "p", "ci_low", "ci_high"]]
222
+ table.index.name = "method"
223
+ return ShiftShareResult(
224
+ kind="iv" if iv else "ols",
225
+ beta=beta,
226
+ table=table.loc[[m for m in METHODS if m in rows]],
227
+ n=n,
228
+ n_sectors=d.shares.shape[1],
229
+ n_sectors_dropped=n_dropped,
230
+ alpha=alpha,
231
+ beta0=beta0,
232
+ small_sample=small_sample,
233
+ notes=notes,
234
+ **names,
235
+ )
236
+
237
+
238
+ def _label(v, default: str) -> str:
239
+ return v if isinstance(v, str) else default
240
+
241
+
242
+ def reg_ss(
243
+ data: pd.DataFrame,
244
+ *,
245
+ y,
246
+ x,
247
+ shares,
248
+ controls: Sequence[str] | None = None,
249
+ categorical: Sequence[str] | None = None,
250
+ intercept: bool = True,
251
+ weights=None,
252
+ region_cluster=None,
253
+ sector_cluster=None,
254
+ method="all",
255
+ alpha: float = 0.05,
256
+ beta0: float = 0.0,
257
+ small_sample: SmallSample = "stata",
258
+ ) -> ShiftShareResult:
259
+ """OLS of ``y`` on a shift-share regressor ``x`` and controls.
260
+
261
+ Parameters
262
+ ----------
263
+ data:
264
+ One row per region (or region-period).
265
+ y, x:
266
+ Column names (or arrays) of the outcome and of the shift-share
267
+ regressor ``x = shares @ shocks``.
268
+ shares:
269
+ Share matrix, one row per row of ``data`` and one column per sector.
270
+ controls, categorical, intercept:
271
+ Control variables. Columns listed in ``categorical`` (and any column of
272
+ object or category dtype) enter as dummies.
273
+ weights:
274
+ Regression weights (column name or array).
275
+ region_cluster:
276
+ Region-level cluster variable for the ``"region_cluster"`` method.
277
+ sector_cluster:
278
+ One cluster label per sector (column of ``shares``) for AKM/AKM0, e.g.
279
+ 3-digit industry codes. Defaults to no clustering of sectors.
280
+ method:
281
+ ``"all"`` or a subset of ``("homosk", "ehw", "region_cluster", "akm", "akm0")``.
282
+ alpha:
283
+ Significance level of the confidence intervals.
284
+ beta0:
285
+ Null value for p-values (and for the AKM0 test).
286
+ small_sample:
287
+ ``"stata"`` applies the usual corrections (residual variance divided by
288
+ ``n - p``, HC1, and ``G/(G-1) (n-1)/(n-p)`` for clusters); ``"none"``
289
+ uses none. AKM and AKM0 never use a correction. The default matches
290
+ ``ShiftShareSE::reg_ss``.
291
+ """
292
+ d = _design.build(
293
+ data,
294
+ y=y,
295
+ x=x,
296
+ shares=shares,
297
+ controls=controls,
298
+ categorical=categorical,
299
+ intercept=intercept,
300
+ weights=weights,
301
+ region_cluster=region_cluster,
302
+ sector_cluster=sector_cluster,
303
+ )
304
+ return _fit(
305
+ d,
306
+ iv=False,
307
+ method=method,
308
+ alpha=alpha,
309
+ beta0=beta0,
310
+ small_sample=small_sample,
311
+ names=dict(y=_label(y, "y"), regressor=_label(x, "x")),
312
+ )
313
+
314
+
315
+ def ivreg_ss(
316
+ data: pd.DataFrame,
317
+ *,
318
+ y,
319
+ endog,
320
+ instrument,
321
+ shares,
322
+ controls: Sequence[str] | None = None,
323
+ categorical: Sequence[str] | None = None,
324
+ intercept: bool = True,
325
+ weights=None,
326
+ region_cluster=None,
327
+ sector_cluster=None,
328
+ method="all",
329
+ alpha: float = 0.05,
330
+ beta0: float = 0.0,
331
+ small_sample: SmallSample = "none",
332
+ ) -> ShiftShareResult:
333
+ """IV regression of ``y`` on ``endog`` with a shift-share ``instrument``.
334
+
335
+ The model is just identified: one endogenous regressor and one shift-share
336
+ instrument ``instrument = shares @ shocks``. See :func:`reg_ss` for the
337
+ other parameters. ``small_sample`` defaults to ``"none"``, matching
338
+ ``ShiftShareSE::ivreg_ss``.
339
+
340
+ AKM0 inverts an Anderson-Rubin-type test, so its confidence set remains
341
+ valid when the instrument is weak (it may then be unbounded).
342
+ """
343
+ d = _design.build(
344
+ data,
345
+ y=y,
346
+ x=instrument,
347
+ endog=endog,
348
+ shares=shares,
349
+ controls=controls,
350
+ categorical=categorical,
351
+ intercept=intercept,
352
+ weights=weights,
353
+ region_cluster=region_cluster,
354
+ sector_cluster=sector_cluster,
355
+ )
356
+ return _fit(
357
+ d,
358
+ iv=True,
359
+ method=method,
360
+ alpha=alpha,
361
+ beta0=beta0,
362
+ small_sample=small_sample,
363
+ names=dict(
364
+ y=_label(y, "y"),
365
+ regressor=_label(endog, "endog"),
366
+ instrument=_label(instrument, "instrument"),
367
+ ),
368
+ )
ssiv/instrument.py ADDED
@@ -0,0 +1,65 @@
1
+ """Constructing shift-share instruments and recovering shocks."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ import pandas as pd
7
+
8
+ from ._linalg import independent_columns
9
+
10
+
11
+ def _as_frame(shares) -> pd.DataFrame:
12
+ return shares if isinstance(shares, pd.DataFrame) else pd.DataFrame(np.asarray(shares, float))
13
+
14
+
15
+ def align_shocks(shares, shocks) -> np.ndarray:
16
+ """Shock values ordered like the share columns (by label when both are labelled)."""
17
+ sh = _as_frame(shares)
18
+ if isinstance(shocks, pd.Series) and isinstance(shares, pd.DataFrame):
19
+ missing = [c for c in sh.columns if c not in shocks.index]
20
+ if missing:
21
+ raise KeyError(f"no shock for {len(missing)} sector(s), e.g. {missing[:3]}")
22
+ return shocks.loc[sh.columns].to_numpy(float)
23
+ g = np.asarray(shocks, float)
24
+ if g.ndim != 1 or g.shape[0] != sh.shape[1]:
25
+ raise ValueError("shocks must have one value per column of shares")
26
+ return g
27
+
28
+
29
+ def bartik(shares, shocks) -> pd.Series:
30
+ """Shift-share variable ``z_l = sum_n s_ln g_n``.
31
+
32
+ ``shares`` is a regions x sectors matrix (DataFrame or array); ``shocks``
33
+ has one value per sector. If both are labelled (DataFrame columns and a
34
+ Series index), shocks are aligned to the share columns by label.
35
+ """
36
+ sh = _as_frame(shares)
37
+ g = align_shocks(shares, shocks)
38
+ return pd.Series(sh.to_numpy(float) @ g, index=sh.index, name="bartik")
39
+
40
+
41
+ def share_sum(shares) -> pd.Series:
42
+ """Sum of exposure shares per region.
43
+
44
+ With incomplete shares (rows summing to less than one), Borusyak, Hull and
45
+ Jaravel (2022) recommend including this sum as a control.
46
+ """
47
+ sh = _as_frame(shares)
48
+ return pd.Series(sh.to_numpy(float).sum(axis=1), index=sh.index, name="share_sum")
49
+
50
+
51
+ def recover_shocks(shares, x, weights=None) -> pd.Series:
52
+ """Recover sector shocks from a shift-share variable by least squares.
53
+
54
+ Useful when a dataset ships the aggregated instrument ``x = shares @ g``
55
+ but not the shocks themselves. Collinear sectors get ``NaN``.
56
+ """
57
+ sh = _as_frame(shares)
58
+ a = sh.to_numpy(float)
59
+ xv = np.asarray(x, float)
60
+ w = np.ones(len(xv)) if weights is None else np.asarray(weights, float)
61
+ sw = np.sqrt(w)
62
+ keep = independent_columns(a * sw[:, None])
63
+ g = np.full(a.shape[1], np.nan)
64
+ g[keep] = np.linalg.lstsq(a[:, keep] * sw[:, None], xv * sw, rcond=None)[0]
65
+ return pd.Series(g, index=sh.columns, name="shock")
ssiv/rotemberg.py ADDED
@@ -0,0 +1,119 @@
1
+ """Rotemberg weights (Goldsmith-Pinkham, Sorkin and Swift, 2020)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from dataclasses import dataclass
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+
11
+ from . import _design
12
+ from ._linalg import wls_residuals
13
+ from .instrument import align_shocks
14
+
15
+
16
+ @dataclass
17
+ class RotembergResult:
18
+ """Decomposition of a Bartik IV estimate into sector-level estimates.
19
+
20
+ ``table`` has one row per sector with the shock ``g``, the Rotemberg weight
21
+ ``alpha`` and the just-identified estimate ``beta`` using that sector's
22
+ share as the only instrument. By construction
23
+ ``sum(alpha * beta) == beta_bartik`` (over sectors with a defined ``beta``).
24
+ """
25
+
26
+ beta_bartik: float
27
+ table: pd.DataFrame
28
+
29
+ @property
30
+ def alpha(self) -> pd.Series:
31
+ return self.table["alpha"]
32
+
33
+ def top(self, k: int = 5) -> pd.DataFrame:
34
+ """Sectors with the largest absolute Rotemberg weights."""
35
+ idx = self.table["alpha"].abs().sort_values(ascending=False).index[:k]
36
+ return self.table.loc[idx]
37
+
38
+ def summary(self) -> pd.Series:
39
+ a = self.table["alpha"]
40
+ b = self.table["beta"]
41
+ ok = b.notna()
42
+ top5 = self.top(5)
43
+ return pd.Series(
44
+ {
45
+ "beta_bartik": self.beta_bartik,
46
+ "n_sectors": int(len(a)),
47
+ "sum_positive_alpha": float(a[a > 0].sum()),
48
+ "sum_negative_alpha": float(a[a < 0].sum()),
49
+ "share_top5_abs_alpha": float(top5["alpha"].abs().sum() / a.abs().sum()),
50
+ "corr_alpha_g": float(np.corrcoef(a, self.table["g"])[0, 1])
51
+ if len(a) > 1
52
+ else np.nan,
53
+ "weighted_mean_beta_positive": float(
54
+ (a[ok & (a > 0)] * b[ok & (a > 0)]).sum() / a[ok & (a > 0)].sum()
55
+ )
56
+ if (ok & (a > 0)).any()
57
+ else np.nan,
58
+ "weighted_mean_beta_negative": float(
59
+ (a[ok & (a < 0)] * b[ok & (a < 0)]).sum() / a[ok & (a < 0)].sum()
60
+ )
61
+ if (ok & (a < 0)).any()
62
+ else np.nan,
63
+ }
64
+ )
65
+
66
+
67
+ def rotemberg(
68
+ data: pd.DataFrame,
69
+ *,
70
+ y,
71
+ endog,
72
+ shares,
73
+ shocks,
74
+ controls: Sequence[str] | None = None,
75
+ categorical: Sequence[str] | None = None,
76
+ intercept: bool = True,
77
+ weights=None,
78
+ ) -> RotembergResult:
79
+ """Rotemberg weights of a Bartik instrument.
80
+
81
+ With residualisation on the controls (weighted), the Bartik IV estimate
82
+ equals ``sum_k alpha_k beta_k`` where
83
+
84
+ * ``alpha_k = g_k s_k' x / sum_j g_j s_j' x`` (``s_k`` = shares of sector k,
85
+ ``x`` = residualised endogenous regressor),
86
+ * ``beta_k = s_k' y / s_k' x`` is the just-identified IV estimate using
87
+ the shares of sector k alone as the instrument.
88
+
89
+ For panels, give share columns per sector x period (shocks likewise), so
90
+ that each column is one instrument.
91
+ """
92
+ sh = shares if isinstance(shares, pd.DataFrame) else pd.DataFrame(np.asarray(shares, float))
93
+ g = align_shocks(sh, shocks)
94
+ d = _design.build(
95
+ data,
96
+ y=y,
97
+ endog=endog,
98
+ shares=sh,
99
+ controls=controls,
100
+ categorical=categorical,
101
+ intercept=intercept,
102
+ weights=weights,
103
+ )
104
+ w = d.w
105
+ yd = wls_residuals(d.y, d.z, w)
106
+ xd = wls_residuals(d.endog, d.z, w)
107
+ sx = d.shares.T @ (w * xd) # s_k' W x
108
+ sy = d.shares.T @ (w * yd)
109
+ num = g * sx
110
+ total = float(num.sum())
111
+ if total == 0:
112
+ raise ValueError("the Bartik instrument has no first stage (sum of g_k s_k'x is zero)")
113
+ alpha = num / total
114
+ with np.errstate(divide="ignore", invalid="ignore"):
115
+ beta_k = np.where(sx != 0, sy / sx, np.nan)
116
+ beta_bartik = float((g * sy).sum() / total)
117
+ table = pd.DataFrame({"g": g, "alpha": alpha, "beta": beta_k}, index=sh.columns)
118
+ table.index.name = "sector"
119
+ return RotembergResult(beta_bartik=beta_bartik, table=table)
ssiv/shocklevel.py ADDED
@@ -0,0 +1,221 @@
1
+ """Shock-level estimation (Borusyak, Hull and Jaravel, 2022).
2
+
3
+ The location-level shift-share IV estimate equals an IV regression across
4
+ shocks (sectors) of exposure-weighted averages of residualised outcomes and
5
+ treatments on the shocks, weighted by total exposure ``s_n``. Inference at the
6
+ shock level is then valid under quasi-random assignment of shocks.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from collections.abc import Sequence
12
+ from dataclasses import dataclass
13
+ from statistics import NormalDist
14
+
15
+ import numpy as np
16
+ import pandas as pd
17
+
18
+ from . import _design
19
+ from ._linalg import wls_residuals
20
+ from .instrument import align_shocks
21
+
22
+ _ND = NormalDist()
23
+
24
+
25
+ def aggregate(
26
+ data: pd.DataFrame,
27
+ *,
28
+ shares,
29
+ variables: dict | Sequence[str],
30
+ controls: Sequence[str] | None = None,
31
+ categorical: Sequence[str] | None = None,
32
+ intercept: bool = True,
33
+ weights=None,
34
+ ) -> pd.DataFrame:
35
+ """Exposure-weighted shock-level aggregates (the ``ssaggregate`` step).
36
+
37
+ For each variable ``v`` (residualised on the controls with weights ``e_l``)
38
+ returns ``v_n = sum_l e_l s_ln v_l / s_n`` with ``s_n = sum_l e_l s_ln``.
39
+ The result has one row per sector, a column ``s_n`` and one column per
40
+ variable. Sectors with zero total exposure are dropped.
41
+ """
42
+ items = list(variables.items()) if isinstance(variables, dict) else [(v, v) for v in variables]
43
+ if not items:
44
+ raise ValueError("give at least one variable to aggregate")
45
+ cols = {}
46
+ for name, v in items:
47
+ col = data[v] if isinstance(v, str) else pd.Series(np.asarray(v, float), index=data.index)
48
+ if len(col) != len(data):
49
+ raise ValueError(f"variable '{name}' must have one value per row of data")
50
+ cols[name] = col.astype(float)
51
+ complete = pd.DataFrame(cols).notna().all(axis=1).to_numpy()
52
+ # Mark rows with any missing variable through the first variable, so the
53
+ # design drops them together with rows missing controls, weights or shares.
54
+ first = cols[items[0][0]].where(complete)
55
+ d = _design.build(
56
+ data,
57
+ y=first,
58
+ shares=shares,
59
+ controls=controls,
60
+ categorical=categorical,
61
+ intercept=intercept,
62
+ weights=weights,
63
+ )
64
+ sh = d.shares
65
+ s_n = sh.T @ d.w
66
+ out = {"s_n": s_n}
67
+ for name, col in cols.items():
68
+ vd = wls_residuals(col.to_numpy()[d.rows], d.z, d.w)
69
+ with np.errstate(divide="ignore", invalid="ignore"):
70
+ out[name] = (sh.T @ (d.w * vd)) / s_n
71
+ df = pd.DataFrame(out, index=pd.Index(d.sector_names, name="sector"))
72
+ return df.loc[df["s_n"] > 0]
73
+
74
+
75
+ @dataclass
76
+ class ShockLevelResult:
77
+ """Shock-level IV estimate with exposure-robust inference."""
78
+
79
+ beta: float
80
+ se: float
81
+ p: float
82
+ ci_low: float
83
+ ci_high: float
84
+ first_stage_coef: float
85
+ first_stage_se: float
86
+ first_stage_f: float
87
+ n_shocks: int
88
+ effective_n_shocks: float
89
+ largest_weight: float
90
+ alpha: float
91
+ data: pd.DataFrame
92
+
93
+ def summary(self) -> pd.Series:
94
+ return pd.Series(
95
+ {
96
+ "beta": self.beta,
97
+ "se": self.se,
98
+ "p": self.p,
99
+ "ci_low": self.ci_low,
100
+ "ci_high": self.ci_high,
101
+ "first_stage_coef": self.first_stage_coef,
102
+ "first_stage_se": self.first_stage_se,
103
+ "first_stage_F": self.first_stage_f,
104
+ "n_shocks": self.n_shocks,
105
+ "effective_n_shocks": self.effective_n_shocks,
106
+ "largest_weight": self.largest_weight,
107
+ }
108
+ )
109
+
110
+ def __repr__(self) -> str:
111
+ return "Shock-level IV (Borusyak, Hull and Jaravel)\n" + self.summary().to_string(
112
+ float_format=lambda v: f"{v:.6g}"
113
+ )
114
+
115
+
116
+ def shock_level_iv(
117
+ data: pd.DataFrame,
118
+ *,
119
+ y,
120
+ endog,
121
+ shares,
122
+ shocks,
123
+ controls: Sequence[str] | None = None,
124
+ categorical: Sequence[str] | None = None,
125
+ intercept: bool = True,
126
+ weights=None,
127
+ shock_controls: pd.DataFrame | np.ndarray | None = None,
128
+ shock_constant: bool = False,
129
+ sector_cluster=None,
130
+ alpha: float = 0.05,
131
+ beta0: float = 0.0,
132
+ ) -> ShockLevelResult:
133
+ """IV regression at the level of shocks.
134
+
135
+ Regresses exposure-weighted outcome averages on treatment averages,
136
+ instrumented by the shocks, with weights ``s_n``. Without shock-level
137
+ controls the point estimate is numerically identical to the
138
+ location-level IV estimate with instrument ``shares @ shocks``.
139
+
140
+ Parameters
141
+ ----------
142
+ shock_controls:
143
+ Sector-level controls ``q_n`` (one row per column of ``shares``). For
144
+ the equivalence to hold, include their exposure-weighted versions
145
+ ``shares @ q`` among the location-level controls.
146
+ shock_constant:
147
+ Add a constant at the shock level. With incomplete shares, combine it
148
+ with the sum of shares as a location-level control
149
+ (:func:`ssiv.share_sum`).
150
+ sector_cluster:
151
+ Cluster labels for sectors (e.g. 3-digit industries); otherwise
152
+ heteroskedasticity-robust standard errors at the shock level.
153
+
154
+ Standard errors use no small-sample correction.
155
+ """
156
+ sh = shares if isinstance(shares, pd.DataFrame) else pd.DataFrame(np.asarray(shares, float))
157
+ g_all = align_shocks(sh, shocks)
158
+ agg = aggregate(
159
+ data,
160
+ shares=sh,
161
+ variables={"y": y, "x": endog},
162
+ controls=controls,
163
+ categorical=categorical,
164
+ intercept=intercept,
165
+ weights=weights,
166
+ )
167
+ pos = sh.columns.get_indexer(agg.index)
168
+ g = g_all[pos]
169
+ s = agg["s_n"].to_numpy()
170
+ yb, xb = agg["y"].to_numpy(), agg["x"].to_numpy()
171
+
172
+ q_parts = []
173
+ if shock_constant:
174
+ q_parts.append(np.ones((len(g), 1)))
175
+ if shock_controls is not None:
176
+ q = np.asarray(shock_controls, float)
177
+ q = q.reshape(-1, 1) if q.ndim == 1 else q
178
+ if q.shape[0] != sh.shape[1]:
179
+ raise ValueError("shock_controls must have one row per sector")
180
+ q_parts.append(q[pos])
181
+ q = np.hstack(q_parts) if q_parts else None
182
+
183
+ gt = wls_residuals(g, q, s)
184
+ yt = wls_residuals(yb, q, s)
185
+ xt = wls_residuals(xb, q, s)
186
+ den = float(np.sum(s * gt * xt))
187
+ if den == 0:
188
+ raise ValueError("no first stage at the shock level")
189
+ beta = float(np.sum(s * gt * yt) / den)
190
+ eps = yt - beta * xt
191
+
192
+ clusters = np.arange(len(g)) if sector_cluster is None else np.asarray(sector_cluster)[pos]
193
+
194
+ def csum(v):
195
+ return pd.Series(v).groupby(clusters, sort=False).sum().to_numpy()
196
+
197
+ se = float(np.sqrt(np.sum(csum(s * gt * eps) ** 2)) / abs(den))
198
+ zc = _ND.inv_cdf(1 - alpha / 2)
199
+ t = (beta - beta0) / se
200
+ # First stage at the shock level: x_n on g_n
201
+ sgg = float(np.sum(s * gt * gt))
202
+ pi = float(np.sum(s * gt * xt) / sgg)
203
+ u = xt - pi * gt
204
+ pi_se = float(np.sqrt(np.sum(csum(s * gt * u) ** 2)) / sgg)
205
+ wn = s / s.sum()
206
+ agg = agg.assign(g=g)
207
+ return ShockLevelResult(
208
+ beta=beta,
209
+ se=se,
210
+ p=2 * _ND.cdf(-abs(t)),
211
+ ci_low=beta - zc * se,
212
+ ci_high=beta + zc * se,
213
+ first_stage_coef=pi,
214
+ first_stage_se=pi_se,
215
+ first_stage_f=(pi / pi_se) ** 2,
216
+ n_shocks=len(g),
217
+ effective_n_shocks=float(1.0 / np.sum(wn**2)),
218
+ largest_weight=float(wn.max()),
219
+ alpha=alpha,
220
+ data=agg,
221
+ )
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.5
2
+ Name: ssiv
3
+ Version: 0.1.0
4
+ Summary: Shift-share (Bartik) instrumental variables in Python: AKM/AKM0 exposure-robust inference, Rotemberg weights and shock-level estimation.
5
+ Project-URL: Homepage, https://github.com/iskakovs/ssiv
6
+ Project-URL: Issues, https://github.com/iskakovs/ssiv/issues
7
+ Author: Serik Iskakov
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: Bartik instrument,Rotemberg weights,causal inference,econometrics,exposure-robust standard errors,instrumental variables,regional economics,shift-share
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Scientific/Engineering
20
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
21
+ Requires-Python: >=3.11
22
+ Requires-Dist: numpy>=1.24
23
+ Requires-Dist: pandas>=2.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
26
+ Requires-Dist: pytest>=8; extra == 'dev'
27
+ Requires-Dist: ruff>=0.5; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # ssiv
31
+
32
+ **Shift-share (Bartik) instrumental variables in Python**: exposure-robust inference
33
+ (AKM / AKM0), Rotemberg weights and shock-level estimation, in one package.
34
+
35
+ > Status: alpha (v0.1.0). The API may change before 1.0.
36
+
37
+ ## Why
38
+
39
+ Shift-share instruments, `z_l = Σ_n s_ln g_n`, combine local exposure shares with sector
40
+ shocks. They are used everywhere from trade and labour economics to regional and urban
41
+ studies. Since 2019, three papers have changed how they should be estimated and reported:
42
+
43
+ * **Adão, Kolesár and Morales (2019)**: conventional standard errors are too small,
44
+ because regions with similar sector mixes have correlated errors. They propose the
45
+ AKM and AKM0 confidence intervals.
46
+ * **Goldsmith-Pinkham, Sorkin and Swift (2020)**: the Bartik estimate is a weighted
47
+ sum of sector-level estimates; Rotemberg weights show which sectors drive it.
48
+ * **Borusyak, Hull and Jaravel (2022)**: with quasi-random shocks, the estimate equals
49
+ a shock-level regression, which gives exposure-robust inference and diagnostics.
50
+
51
+ These methods are implemented in R, Stata, MATLAB and Julia, but not in Python.
52
+ `ssiv` brings them to Python, implemented from the papers and validated against the R
53
+ reference implementation (see [Validation](#validation)).
54
+
55
+ ## Install
56
+
57
+ ```bash
58
+ pip install "ssiv @ git+https://github.com/iskakovs/ssiv"
59
+ ```
60
+
61
+ Python 3.11+, with `numpy` and `pandas` only.
62
+
63
+ ## Quick start
64
+
65
+ ```python
66
+ import numpy as np
67
+ import pandas as pd
68
+
69
+ import ssiv
70
+
71
+ # Simulated data: 500 regions, 40 sectors, incomplete shares, true effect -0.5
72
+ rng = np.random.default_rng(1)
73
+ n, s = 500, 40
74
+ shares = pd.DataFrame(
75
+ rng.dirichlet(np.full(s, 0.1), n) * rng.uniform(0.4, 0.9, (n, 1)),
76
+ columns=[f"sector{j}" for j in range(s)],
77
+ )
78
+ shocks = pd.Series(rng.normal(size=s), index=shares.columns)
79
+
80
+ data = pd.DataFrame(
81
+ {
82
+ "z": ssiv.bartik(shares, shocks), # shift-share instrument
83
+ "S": ssiv.share_sum(shares), # sum of shares (control with incomplete shares)
84
+ "c": rng.normal(size=n),
85
+ }
86
+ )
87
+ u = rng.normal(size=n) # unobserved confounder: OLS would be biased
88
+ data["x"] = 1.5 * data.z + 0.3 * data.c + u + rng.normal(scale=0.5, size=n)
89
+ data["y"] = -0.5 * data.x + 0.2 * data.c + u + rng.normal(scale=0.5, size=n)
90
+
91
+ # 1. IV with exposure-robust inference
92
+ res = ssiv.ivreg_ss(
93
+ data,
94
+ y="y",
95
+ endog="x",
96
+ instrument="z",
97
+ shares=shares,
98
+ controls=["c", "S"],
99
+ method=["ehw", "akm", "akm0"],
100
+ )
101
+ print(res)
102
+
103
+ # 2. Which sectors drive the estimate?
104
+ rw = ssiv.rotemberg(data, y="y", endog="x", shares=shares, shocks=shocks, controls=["c", "S"])
105
+ print(rw.top(5))
106
+
107
+ # 3. Shock-level estimation (identical point estimate)
108
+ sl = ssiv.shock_level_iv(
109
+ data, y="y", endog="x", shares=shares, shocks=shocks, controls=["c", "S"], shock_constant=True
110
+ )
111
+ print(sl)
112
+ ```
113
+
114
+ ## What is included
115
+
116
+ | Function | What it does | Reference |
117
+ |---|---|---|
118
+ | `reg_ss` | OLS with a shift-share regressor | AKM (2019) |
119
+ | `ivreg_ss` | IV with a shift-share instrument | AKM (2019) |
120
+ | `rotemberg` | Rotemberg weights and sector-level just-identified estimates | GPSS (2020) |
121
+ | `aggregate` | Exposure-weighted shock-level aggregates (the `ssaggregate` step) | BHJ (2022) |
122
+ | `shock_level_iv` | Shock-level IV with robust or clustered errors, first-stage F, effective number of shocks | BHJ (2022) |
123
+ | `bartik`, `share_sum`, `recover_shocks` | Build the instrument, the incomplete-shares control, recover shocks from an aggregated instrument | — |
124
+
125
+ `reg_ss` and `ivreg_ss` report five kinds of inference side by side:
126
+
127
+ | `method` | Inference |
128
+ |---|---|
129
+ | `"homosk"` | homoskedastic |
130
+ | `"ehw"` | heteroskedasticity-robust (Eicker–Huber–White) |
131
+ | `"region_cluster"` | clustered by region groups (`region_cluster=`) |
132
+ | `"akm"` | Adão–Kolesár–Morales, optionally clustering sectors (`sector_cluster=`) |
133
+ | `"akm0"` | AKM with the null imposed: test inversion, valid with weak instruments |
134
+
135
+ ## Validation
136
+
137
+ `ssiv` reproduces the published output of the R package
138
+ [ShiftShareSE](https://github.com/kolesarm/ShiftShareSE) on the Autor, Dorn and Hanson
139
+ (2013) data. That covers the first stage, reduced form and IV, under all five methods:
140
+ every estimate, standard error and confidence bound matches to the 7 printed digits.
141
+
142
+ | IV: effect of import exposure on employment | ShiftShareSE (R) | ssiv |
143
+ |---|---|---|
144
+ | Estimate | −0.7742267 | −0.7742267 |
145
+ | EHW s.e. | 0.1647892 | 0.1647892 |
146
+ | AKM s.e. | 0.2403730 | 0.2403730 |
147
+ | AKM0 95% CI | [−1.6903240, −0.3893132] | [−1.6903240, −0.3893132] |
148
+
149
+ To run it yourself (needs R to read the `.rda` file):
150
+
151
+ ```bash
152
+ bash scripts/fetch_adh.sh adh_data
153
+ SSIV_ADH_DIR=adh_data pytest tests/test_adh_validation.py
154
+ python examples/adh_replication.py adh_data
155
+ ```
156
+
157
+ The test suite also checks exact identities:
158
+ * Rotemberg weights reproduce the Bartik estimate.
159
+ * The shock-level estimate equals the region-level one, with and without a shock-level
160
+ constant.
161
+ * AKM0 intervals invert the AKM0 test.
162
+
163
+ ## Conventions
164
+
165
+ * **Small-sample corrections** (`small_sample=`): `"stata"` divides the residual variance
166
+ by `n − p`, uses HC1, and multiplies clustered variances by `G/(G−1)·(n−1)/(n−p)`;
167
+ `"none"` applies none. The defaults follow ShiftShareSE: `"stata"` for `reg_ss`,
168
+ `"none"` for `ivreg_ss`. AKM, AKM0 and shock-level errors never use a correction.
169
+ * **AKM**: sector shocks net of controls are estimated by a weighted regression of the
170
+ residualised shift-share variable on the shares. Residual sums are aggregated by sector
171
+ and squared within sector clusters.
172
+ * **Collinear shares**: collinear columns are dropped in order, keeping earlier columns,
173
+ with a `CollinearSharesWarning`. This is the same rule as R's `lm`.
174
+ * **AKM0** confidence sets come from inverting the test. When identification is weak the
175
+ set can be unbounded; it is then reported as `(-inf, inf)` with a note. Its "standard
176
+ error" is the set's length divided by `2z`, as in ShiftShareSE.
177
+ * **Shock-level IV**: without shock-level controls, the estimate is numerically identical
178
+ to the location-level one. With incomplete shares, add `share_sum` as a location
179
+ control and set `shock_constant=True`.
180
+
181
+ ## Roadmap
182
+
183
+ * Multiple shift-share instruments and overidentified models.
184
+ * Leave-one-out instruments and panel helpers (sector × period cells).
185
+ * Diagnostics: share balance (GPSS), shock balance and pre-trend tests (BHJ).
186
+ * Integration with `pyfixest` for high-dimensional fixed effects.
187
+
188
+ ## References
189
+
190
+ * Adão, R., Kolesár, M. and Morales, E. (2019). Shift-Share Designs: Theory and
191
+ Inference. *Quarterly Journal of Economics*, 134(4), 1949–2010.
192
+ * Borusyak, K., Hull, P. and Jaravel, X. (2022). Quasi-Experimental Shift-Share Research
193
+ Designs. *Review of Economic Studies*, 89(1), 181–213.
194
+ * Goldsmith-Pinkham, P., Sorkin, I. and Swift, H. (2020). Bartik Instruments: What, When,
195
+ Why, and How. *American Economic Review*, 110(8), 2586–2624.
196
+ * Autor, D., Dorn, D. and Hanson, G. (2013). The China Syndrome. *American Economic
197
+ Review*, 103(6), 2121–2168.
198
+
199
+ ## Citation
200
+
201
+ If you use `ssiv` in research, please cite it (see
202
+ [CITATION.cff](https://github.com/iskakovs/ssiv/blob/main/CITATION.cff)) together with
203
+ the papers whose methods you use.
204
+
205
+ ## License
206
+
207
+ MIT © 2026 Serik Iskakov. The ADH data used for validation are not distributed with this
208
+ package; `scripts/fetch_adh.sh` downloads them from the ShiftShareSE repository.
@@ -0,0 +1,12 @@
1
+ ssiv/__init__.py,sha256=RxlOVNRgaYD53sgClPcPXzYUxiZQMgkOYjz3e0NtP4k,1112
2
+ ssiv/_design.py,sha256=axTcHmZ3fXTlzYxCkEbkm1hte-B5dEYOoTe-5TUDrx0,6159
3
+ ssiv/_linalg.py,sha256=UIzeGm5gWUGGXepL1v4jxxY4DuuMp-_A2Dr5p_MaI-4,2163
4
+ ssiv/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
5
+ ssiv/inference.py,sha256=i6682tzxwUuPp6T42x3fmV2mA9ByFckehZLKpNrqaZM,12209
6
+ ssiv/instrument.py,sha256=Nvgrasae90wmQzzG27JCciXOqONZEBKr2zBMusxsvjA,2467
7
+ ssiv/rotemberg.py,sha256=B7TEIQ2rgmGmvaTIWl3d08QnKSS2Oqsoubs-GnyWtoY,4015
8
+ ssiv/shocklevel.py,sha256=hHCZC_4JdVl1fmH4KsU0NmHC1l-uoSA9j62LfiLUH7A,7392
9
+ ssiv-0.1.0.dist-info/METADATA,sha256=Wq-99OPIj6UM5C0KPCThNe54t3OwMsGzcj0UfdZKwRY,8734
10
+ ssiv-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
11
+ ssiv-0.1.0.dist-info/licenses/LICENSE,sha256=VdfixxoNvksqEi5SApuP9H2wNLLc-6G2ao1ngCoKdNI,1070
12
+ ssiv-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Serik Iskakov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.