ssiv 0.1.0__tar.gz

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.
@@ -0,0 +1,4 @@
1
+ # Normalise line endings so commits from Windows and Unix match.
2
+ * text=auto eol=lf
3
+ *.xlsx binary
4
+ *.png binary
@@ -0,0 +1,95 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ defaults:
10
+ run:
11
+ shell: bash
12
+
13
+ jobs:
14
+ lint:
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: "3.13"
21
+ - run: pip install ruff
22
+ - run: ruff check .
23
+ - run: ruff format --check .
24
+
25
+ test:
26
+ name: test (${{ matrix.os }}, Python ${{ matrix.python-version }})
27
+ runs-on: ${{ matrix.os }}
28
+ strategy:
29
+ fail-fast: false
30
+ matrix:
31
+ os: [ubuntu-latest, windows-latest, macos-latest]
32
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
33
+ steps:
34
+ - uses: actions/checkout@v4
35
+ - uses: actions/setup-python@v5
36
+ with:
37
+ python-version: ${{ matrix.python-version }}
38
+ - run: pip install -e ".[dev]"
39
+ - run: pytest --cov=ssiv --cov-report=term-missing
40
+
41
+ oldest-dependencies:
42
+ runs-on: ubuntu-latest
43
+ steps:
44
+ - uses: actions/checkout@v4
45
+ - uses: actions/setup-python@v5
46
+ with:
47
+ python-version: "3.11"
48
+ - run: |
49
+ printf 'numpy==1.24.*\npandas==2.0.*\n' > oldest.txt
50
+ pip install -e ".[dev]" -c oldest.txt
51
+ - run: pytest
52
+
53
+ validation:
54
+ # Reproduce the published ShiftShareSE results on the Autor-Dorn-Hanson data.
55
+ runs-on: ubuntu-latest
56
+ steps:
57
+ - uses: actions/checkout@v4
58
+ - uses: actions/setup-python@v5
59
+ with:
60
+ python-version: "3.13"
61
+ - uses: r-lib/actions/setup-r@v2
62
+ - name: Fetch ADH data
63
+ run: bash scripts/fetch_adh.sh "$RUNNER_TEMP/adh"
64
+ - run: pip install -e ".[dev]"
65
+ - name: Validate against ShiftShareSE
66
+ run: SSIV_ADH_DIR="$RUNNER_TEMP/adh" pytest -v tests/test_adh_validation.py tests/test_readme_and_example.py
67
+
68
+ installed-package:
69
+ name: installed package (${{ matrix.os }})
70
+ runs-on: ${{ matrix.os }}
71
+ strategy:
72
+ fail-fast: false
73
+ matrix:
74
+ os: [ubuntu-latest, windows-latest]
75
+ steps:
76
+ - uses: actions/checkout@v4
77
+ - uses: actions/setup-python@v5
78
+ with:
79
+ python-version: "3.13"
80
+ - name: Build sdist and wheel
81
+ run: |
82
+ pip install build twine
83
+ python -m build
84
+ twine check --strict dist/*
85
+ - name: Install the wheel into a clean environment
86
+ run: |
87
+ python -m venv clean-env
88
+ if [ -d clean-env/bin ]; then PY=clean-env/bin/python; else PY=clean-env/Scripts/python; fi
89
+ echo "PY=$PY" >> "$GITHUB_ENV"
90
+ "$PY" -m pip install "$(ls dist/*.whl)" pytest
91
+ - name: Check the installed copy is used
92
+ run: |
93
+ "$PY" -c "import ssiv; assert 'site-packages' in ssiv.__file__, ssiv.__file__; print(ssiv.__version__)"
94
+ - name: Run tests against the installed package
95
+ run: '"$PY" -m pytest -p no:cacheprovider'
@@ -0,0 +1,84 @@
1
+ name: Release
2
+
3
+ # Publishing a GitHub Release (tag vX.Y.Z) uploads the package to PyPI.
4
+ # "Run workflow" in the Actions tab can upload to TestPyPI for a trial.
5
+ # Authentication uses PyPI trusted publishing: no passwords or tokens are stored.
6
+
7
+ on:
8
+ release:
9
+ types: [published]
10
+ workflow_dispatch:
11
+ inputs:
12
+ target:
13
+ description: "Where to publish"
14
+ type: choice
15
+ options: [testpypi, pypi]
16
+ default: testpypi
17
+
18
+ jobs:
19
+ build:
20
+ name: Build distributions
21
+ runs-on: ubuntu-latest
22
+ steps:
23
+ - uses: actions/checkout@v4
24
+ - uses: actions/setup-python@v5
25
+ with:
26
+ python-version: "3.13"
27
+ - name: Check that the release tag matches the package version
28
+ if: github.event_name == 'release'
29
+ run: |
30
+ version=$(python -c "import re; print(re.search(r'\"(.+)\"', open('src/ssiv/_version.py').read()).group(1))")
31
+ if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
32
+ echo "::error::Tag ${GITHUB_REF_NAME} does not match package version v${version}"
33
+ exit 1
34
+ fi
35
+ - name: Build and check
36
+ run: |
37
+ pip install build twine
38
+ python -m build
39
+ twine check --strict dist/*
40
+ - name: Test the built wheel
41
+ run: |
42
+ python -m venv /tmp/clean
43
+ /tmp/clean/bin/pip install "$(ls dist/*.whl)" pytest
44
+ /tmp/clean/bin/python -m pytest -q -p no:cacheprovider
45
+ - uses: actions/upload-artifact@v4
46
+ with:
47
+ name: dist
48
+ path: dist/
49
+
50
+ publish-testpypi:
51
+ name: Publish to TestPyPI
52
+ if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
53
+ needs: build
54
+ runs-on: ubuntu-latest
55
+ environment:
56
+ name: testpypi
57
+ url: https://test.pypi.org/p/ssiv
58
+ permissions:
59
+ id-token: write
60
+ steps:
61
+ - uses: actions/download-artifact@v4
62
+ with:
63
+ name: dist
64
+ path: dist/
65
+ - uses: pypa/gh-action-pypi-publish@release/v1
66
+ with:
67
+ repository-url: https://test.pypi.org/legacy/
68
+
69
+ publish-pypi:
70
+ name: Publish to PyPI
71
+ if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
72
+ needs: build
73
+ runs-on: ubuntu-latest
74
+ environment:
75
+ name: pypi
76
+ url: https://pypi.org/p/ssiv
77
+ permissions:
78
+ id-token: write
79
+ steps:
80
+ - uses: actions/download-artifact@v4
81
+ with:
82
+ name: dist
83
+ path: dist/
84
+ - uses: pypa/gh-action-pypi-publish@release/v1
ssiv-0.1.0/.gitignore ADDED
@@ -0,0 +1,15 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .venv/
5
+ build/
6
+ dist/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ htmlcov/
11
+ *.xlsx
12
+ .ipynb_checkpoints/
13
+
14
+ # validation data (not distributed)
15
+ adh_data/
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — unreleased
4
+
5
+ First public release (alpha).
6
+
7
+ * `reg_ss` and `ivreg_ss`: OLS and IV with a shift-share variable, with homoskedastic,
8
+ EHW, region-clustered, AKM and AKM0 inference (Adão, Kolesár and Morales, 2019),
9
+ sector clustering, regression weights, categorical controls, small-sample options and
10
+ collinear-share handling.
11
+ * `rotemberg`: Rotemberg weights and sector-level just-identified estimates
12
+ (Goldsmith-Pinkham, Sorkin and Swift, 2020).
13
+ * `aggregate` and `shock_level_iv`: shock-level aggregation and IV with robust or
14
+ clustered errors, first-stage F, effective number of shocks (Borusyak, Hull and
15
+ Jaravel, 2022).
16
+ * `bartik`, `share_sum`, `recover_shocks`: building blocks.
17
+ * Validation against the published ShiftShareSE results on the Autor, Dorn and Hanson
18
+ data, run in CI.
@@ -0,0 +1,15 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use this software, please cite it as below, together with the papers whose methods you use."
3
+ title: "ssiv: shift-share (Bartik) instrumental variables in Python"
4
+ type: software
5
+ authors:
6
+ - family-names: Iskakov
7
+ given-names: Serik
8
+ version: 0.1.0
9
+ license: MIT
10
+ repository-code: "https://github.com/iskakovs/ssiv"
11
+ keywords:
12
+ - shift-share
13
+ - Bartik instrument
14
+ - instrumental variables
15
+ - econometrics
@@ -0,0 +1,35 @@
1
+ # Contributing to ssiv
2
+
3
+ ## Development setup
4
+
5
+ ```bash
6
+ git clone https://github.com/iskakovs/ssiv
7
+ cd ssiv
8
+ python -m venv .venv && source .venv/bin/activate
9
+ pip install -e ".[dev]"
10
+ pytest
11
+ ruff check . && ruff format --check .
12
+ ```
13
+
14
+ To also run the validation against ShiftShareSE (needs R):
15
+
16
+ ```bash
17
+ bash scripts/fetch_adh.sh adh_data
18
+ SSIV_ADH_DIR=adh_data pytest tests/test_adh_validation.py
19
+ ```
20
+
21
+ ## Ground rules
22
+
23
+ * **Implement from the papers.** Cite the equation or section you implement in the
24
+ docstring. Do not translate code from GPL-licensed packages; use them only as a black
25
+ box to compare results.
26
+ * **Every estimator has a test**: an exact identity, a closed form computed by hand, or a
27
+ published result.
28
+ * Keep the dependencies to `numpy` and `pandas`.
29
+
30
+ ## Pull requests
31
+
32
+ 1. Open an issue describing the change.
33
+ 2. Add tests and documentation.
34
+ 3. Make sure `pytest` and `ruff` pass.
35
+ 4. Add a line to `CHANGELOG.md`.
ssiv-0.1.0/LICENSE ADDED
@@ -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.
ssiv-0.1.0/PKG-INFO ADDED
@@ -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.
ssiv-0.1.0/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # ssiv
2
+
3
+ **Shift-share (Bartik) instrumental variables in Python**: exposure-robust inference
4
+ (AKM / AKM0), Rotemberg weights and shock-level estimation, in one package.
5
+
6
+ > Status: alpha (v0.1.0). The API may change before 1.0.
7
+
8
+ ## Why
9
+
10
+ Shift-share instruments, `z_l = Σ_n s_ln g_n`, combine local exposure shares with sector
11
+ shocks. They are used everywhere from trade and labour economics to regional and urban
12
+ studies. Since 2019, three papers have changed how they should be estimated and reported:
13
+
14
+ * **Adão, Kolesár and Morales (2019)**: conventional standard errors are too small,
15
+ because regions with similar sector mixes have correlated errors. They propose the
16
+ AKM and AKM0 confidence intervals.
17
+ * **Goldsmith-Pinkham, Sorkin and Swift (2020)**: the Bartik estimate is a weighted
18
+ sum of sector-level estimates; Rotemberg weights show which sectors drive it.
19
+ * **Borusyak, Hull and Jaravel (2022)**: with quasi-random shocks, the estimate equals
20
+ a shock-level regression, which gives exposure-robust inference and diagnostics.
21
+
22
+ These methods are implemented in R, Stata, MATLAB and Julia, but not in Python.
23
+ `ssiv` brings them to Python, implemented from the papers and validated against the R
24
+ reference implementation (see [Validation](#validation)).
25
+
26
+ ## Install
27
+
28
+ ```bash
29
+ pip install "ssiv @ git+https://github.com/iskakovs/ssiv"
30
+ ```
31
+
32
+ Python 3.11+, with `numpy` and `pandas` only.
33
+
34
+ ## Quick start
35
+
36
+ ```python
37
+ import numpy as np
38
+ import pandas as pd
39
+
40
+ import ssiv
41
+
42
+ # Simulated data: 500 regions, 40 sectors, incomplete shares, true effect -0.5
43
+ rng = np.random.default_rng(1)
44
+ n, s = 500, 40
45
+ shares = pd.DataFrame(
46
+ rng.dirichlet(np.full(s, 0.1), n) * rng.uniform(0.4, 0.9, (n, 1)),
47
+ columns=[f"sector{j}" for j in range(s)],
48
+ )
49
+ shocks = pd.Series(rng.normal(size=s), index=shares.columns)
50
+
51
+ data = pd.DataFrame(
52
+ {
53
+ "z": ssiv.bartik(shares, shocks), # shift-share instrument
54
+ "S": ssiv.share_sum(shares), # sum of shares (control with incomplete shares)
55
+ "c": rng.normal(size=n),
56
+ }
57
+ )
58
+ u = rng.normal(size=n) # unobserved confounder: OLS would be biased
59
+ data["x"] = 1.5 * data.z + 0.3 * data.c + u + rng.normal(scale=0.5, size=n)
60
+ data["y"] = -0.5 * data.x + 0.2 * data.c + u + rng.normal(scale=0.5, size=n)
61
+
62
+ # 1. IV with exposure-robust inference
63
+ res = ssiv.ivreg_ss(
64
+ data,
65
+ y="y",
66
+ endog="x",
67
+ instrument="z",
68
+ shares=shares,
69
+ controls=["c", "S"],
70
+ method=["ehw", "akm", "akm0"],
71
+ )
72
+ print(res)
73
+
74
+ # 2. Which sectors drive the estimate?
75
+ rw = ssiv.rotemberg(data, y="y", endog="x", shares=shares, shocks=shocks, controls=["c", "S"])
76
+ print(rw.top(5))
77
+
78
+ # 3. Shock-level estimation (identical point estimate)
79
+ sl = ssiv.shock_level_iv(
80
+ data, y="y", endog="x", shares=shares, shocks=shocks, controls=["c", "S"], shock_constant=True
81
+ )
82
+ print(sl)
83
+ ```
84
+
85
+ ## What is included
86
+
87
+ | Function | What it does | Reference |
88
+ |---|---|---|
89
+ | `reg_ss` | OLS with a shift-share regressor | AKM (2019) |
90
+ | `ivreg_ss` | IV with a shift-share instrument | AKM (2019) |
91
+ | `rotemberg` | Rotemberg weights and sector-level just-identified estimates | GPSS (2020) |
92
+ | `aggregate` | Exposure-weighted shock-level aggregates (the `ssaggregate` step) | BHJ (2022) |
93
+ | `shock_level_iv` | Shock-level IV with robust or clustered errors, first-stage F, effective number of shocks | BHJ (2022) |
94
+ | `bartik`, `share_sum`, `recover_shocks` | Build the instrument, the incomplete-shares control, recover shocks from an aggregated instrument | — |
95
+
96
+ `reg_ss` and `ivreg_ss` report five kinds of inference side by side:
97
+
98
+ | `method` | Inference |
99
+ |---|---|
100
+ | `"homosk"` | homoskedastic |
101
+ | `"ehw"` | heteroskedasticity-robust (Eicker–Huber–White) |
102
+ | `"region_cluster"` | clustered by region groups (`region_cluster=`) |
103
+ | `"akm"` | Adão–Kolesár–Morales, optionally clustering sectors (`sector_cluster=`) |
104
+ | `"akm0"` | AKM with the null imposed: test inversion, valid with weak instruments |
105
+
106
+ ## Validation
107
+
108
+ `ssiv` reproduces the published output of the R package
109
+ [ShiftShareSE](https://github.com/kolesarm/ShiftShareSE) on the Autor, Dorn and Hanson
110
+ (2013) data. That covers the first stage, reduced form and IV, under all five methods:
111
+ every estimate, standard error and confidence bound matches to the 7 printed digits.
112
+
113
+ | IV: effect of import exposure on employment | ShiftShareSE (R) | ssiv |
114
+ |---|---|---|
115
+ | Estimate | −0.7742267 | −0.7742267 |
116
+ | EHW s.e. | 0.1647892 | 0.1647892 |
117
+ | AKM s.e. | 0.2403730 | 0.2403730 |
118
+ | AKM0 95% CI | [−1.6903240, −0.3893132] | [−1.6903240, −0.3893132] |
119
+
120
+ To run it yourself (needs R to read the `.rda` file):
121
+
122
+ ```bash
123
+ bash scripts/fetch_adh.sh adh_data
124
+ SSIV_ADH_DIR=adh_data pytest tests/test_adh_validation.py
125
+ python examples/adh_replication.py adh_data
126
+ ```
127
+
128
+ The test suite also checks exact identities:
129
+ * Rotemberg weights reproduce the Bartik estimate.
130
+ * The shock-level estimate equals the region-level one, with and without a shock-level
131
+ constant.
132
+ * AKM0 intervals invert the AKM0 test.
133
+
134
+ ## Conventions
135
+
136
+ * **Small-sample corrections** (`small_sample=`): `"stata"` divides the residual variance
137
+ by `n − p`, uses HC1, and multiplies clustered variances by `G/(G−1)·(n−1)/(n−p)`;
138
+ `"none"` applies none. The defaults follow ShiftShareSE: `"stata"` for `reg_ss`,
139
+ `"none"` for `ivreg_ss`. AKM, AKM0 and shock-level errors never use a correction.
140
+ * **AKM**: sector shocks net of controls are estimated by a weighted regression of the
141
+ residualised shift-share variable on the shares. Residual sums are aggregated by sector
142
+ and squared within sector clusters.
143
+ * **Collinear shares**: collinear columns are dropped in order, keeping earlier columns,
144
+ with a `CollinearSharesWarning`. This is the same rule as R's `lm`.
145
+ * **AKM0** confidence sets come from inverting the test. When identification is weak the
146
+ set can be unbounded; it is then reported as `(-inf, inf)` with a note. Its "standard
147
+ error" is the set's length divided by `2z`, as in ShiftShareSE.
148
+ * **Shock-level IV**: without shock-level controls, the estimate is numerically identical
149
+ to the location-level one. With incomplete shares, add `share_sum` as a location
150
+ control and set `shock_constant=True`.
151
+
152
+ ## Roadmap
153
+
154
+ * Multiple shift-share instruments and overidentified models.
155
+ * Leave-one-out instruments and panel helpers (sector × period cells).
156
+ * Diagnostics: share balance (GPSS), shock balance and pre-trend tests (BHJ).
157
+ * Integration with `pyfixest` for high-dimensional fixed effects.
158
+
159
+ ## References
160
+
161
+ * Adão, R., Kolesár, M. and Morales, E. (2019). Shift-Share Designs: Theory and
162
+ Inference. *Quarterly Journal of Economics*, 134(4), 1949–2010.
163
+ * Borusyak, K., Hull, P. and Jaravel, X. (2022). Quasi-Experimental Shift-Share Research
164
+ Designs. *Review of Economic Studies*, 89(1), 181–213.
165
+ * Goldsmith-Pinkham, P., Sorkin, I. and Swift, H. (2020). Bartik Instruments: What, When,
166
+ Why, and How. *American Economic Review*, 110(8), 2586–2624.
167
+ * Autor, D., Dorn, D. and Hanson, G. (2013). The China Syndrome. *American Economic
168
+ Review*, 103(6), 2121–2168.
169
+
170
+ ## Citation
171
+
172
+ If you use `ssiv` in research, please cite it (see
173
+ [CITATION.cff](https://github.com/iskakovs/ssiv/blob/main/CITATION.cff)) together with
174
+ the papers whose methods you use.
175
+
176
+ ## License
177
+
178
+ MIT © 2026 Serik Iskakov. The ADH data used for validation are not distributed with this
179
+ package; `scripts/fetch_adh.sh` downloads them from the ShiftShareSE repository.