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.
- ssiv-0.1.0/.gitattributes +4 -0
- ssiv-0.1.0/.github/workflows/ci.yml +95 -0
- ssiv-0.1.0/.github/workflows/release.yml +84 -0
- ssiv-0.1.0/.gitignore +15 -0
- ssiv-0.1.0/CHANGELOG.md +18 -0
- ssiv-0.1.0/CITATION.cff +15 -0
- ssiv-0.1.0/CONTRIBUTING.md +35 -0
- ssiv-0.1.0/LICENSE +21 -0
- ssiv-0.1.0/PKG-INFO +208 -0
- ssiv-0.1.0/README.md +179 -0
- ssiv-0.1.0/examples/adh_replication.py +68 -0
- ssiv-0.1.0/pyproject.toml +60 -0
- ssiv-0.1.0/scripts/export_adh.R +13 -0
- ssiv-0.1.0/scripts/fetch_adh.sh +13 -0
- ssiv-0.1.0/src/ssiv/__init__.py +38 -0
- ssiv-0.1.0/src/ssiv/_design.py +172 -0
- ssiv-0.1.0/src/ssiv/_linalg.py +61 -0
- ssiv-0.1.0/src/ssiv/_version.py +1 -0
- ssiv-0.1.0/src/ssiv/inference.py +368 -0
- ssiv-0.1.0/src/ssiv/instrument.py +65 -0
- ssiv-0.1.0/src/ssiv/rotemberg.py +119 -0
- ssiv-0.1.0/src/ssiv/shocklevel.py +221 -0
- ssiv-0.1.0/tests/conftest.py +43 -0
- ssiv-0.1.0/tests/test_adh_validation.py +125 -0
- ssiv-0.1.0/tests/test_design.py +87 -0
- ssiv-0.1.0/tests/test_inference.py +184 -0
- ssiv-0.1.0/tests/test_instrument.py +41 -0
- ssiv-0.1.0/tests/test_readme_and_example.py +26 -0
- ssiv-0.1.0/tests/test_rotemberg_shocklevel.py +120 -0
|
@@ -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
ssiv-0.1.0/CHANGELOG.md
ADDED
|
@@ -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.
|
ssiv-0.1.0/CITATION.cff
ADDED
|
@@ -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.
|