causal-toolkit-bergeson 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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rhett Bergeson
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.
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: causal-toolkit-bergeson
3
+ Version: 0.1.0
4
+ Summary: A Python package for causal inference methods including ATE estimation, propensity score methods, and meta-learners
5
+ Author-email: Rhett Bergeson <rhettbergeson@uchicago.edu>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/rhettbergeson/causal-toolkit-bergeson
8
+ Project-URL: Documentation, https://github.com/rhettbergeson/causal-toolkit-bergeson#readme
9
+ Project-URL: Repository, https://github.com/rhettbergeson/causal-toolkit-bergeson
10
+ Project-URL: Bug Tracker, https://github.com/rhettbergeson/causal-toolkit-bergeson/issues
11
+ Keywords: causal inference,statistics,machine learning,treatment effects
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
21
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: pandas>=1.3.0
26
+ Requires-Dist: numpy>=1.21.0
27
+ Requires-Dist: scipy>=1.7.0
28
+ Requires-Dist: scikit-learn>=1.0.0
29
+ Requires-Dist: lightgbm>=3.3.0
30
+ Requires-Dist: patsy>=0.5.0
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
33
+ Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
34
+ Requires-Dist: black>=22.0.0; extra == "dev"
35
+ Requires-Dist: pylint>=2.12.0; extra == "dev"
36
+ Requires-Dist: mypy>=0.950; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # causal-toolkit-bergeson
40
+
41
+ [![Tests](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions/workflows/tests.yml/badge.svg)](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions)
42
+ [![PyPI version](https://badge.fury.io/py/causal-toolkit-bergeson.svg)](https://pypi.org/project/causal-toolkit-bergeson/)
43
+
44
+ A Python package for estimating causal effects. It collects the methods built in
45
+ UChicago's *Causal Models in Data Science* (ADSP 32029) course into one installable
46
+ toolkit:
47
+
48
+ - **Randomized experiments**: average treatment effect (ATE) with confidence
49
+ intervals and p-values
50
+ - **Propensity score methods**: inverse propensity weighting (IPW) and doubly
51
+ robust (AIPW) estimation of the ATE
52
+ - **Meta-learners**: S-, T- and X-learners and Double ML for estimating
53
+ conditional average treatment effects (CATE)
54
+
55
+ ## Installation
56
+
57
+ Requires Python 3.8+. Install from [PyPI](https://pypi.org/project/causal-toolkit-bergeson/):
58
+
59
+ ```bash
60
+ pip install causal-toolkit-bergeson
61
+ ```
62
+
63
+ ### From source (for development)
64
+
65
+ Clone the repository and install in editable mode with [uv](https://docs.astral.sh/uv/):
66
+
67
+ ```bash
68
+ # Clone the repository
69
+ git clone https://github.com/rhettbergeson/causal-toolkit-bergeson.git
70
+ cd causal-toolkit-bergeson
71
+
72
+ # Install in editable mode
73
+ uv pip install -e .
74
+
75
+ # Run the test suite to verify the installation
76
+ uv run pytest
77
+ ```
78
+
79
+ The package installs as `causal-toolkit-bergeson` but is imported as
80
+ `causal_toolkit_bergeson` (Python import names can't contain hyphens).
81
+
82
+ Using plain pip instead? `pip install -e ".[dev]"` installs the package along with
83
+ the testing and linting tools.
84
+
85
+ ## Quick start
86
+
87
+ ```python
88
+ import numpy as np
89
+ import pandas as pd
90
+ from causal_toolkit_bergeson import (
91
+ calculate_ate_ci, calculate_ate_pvalue, ipw, doubly_robust,
92
+ s_learner_discrete, t_learner_discrete, x_learner_discrete, double_ml_cate,
93
+ )
94
+
95
+ rng = np.random.default_rng(0)
96
+ n = 2000
97
+ ```
98
+
99
+ ### Randomized experiment
100
+
101
+ The RCT functions expect a binary treatment column named `T` and an outcome
102
+ column named `Y`.
103
+
104
+ ```python
105
+ rct = pd.DataFrame({"T": rng.binomial(1, 0.5, n)})
106
+ rct["Y"] = 1.5 * rct["T"] + rng.normal(0, 2, n) # true ATE = 1.5
107
+
108
+ ate, ci_lower, ci_upper = calculate_ate_ci(rct, alpha=0.05)
109
+ ate, t_stat, p_value = calculate_ate_pvalue(rct)
110
+ # ATE ≈ 1.39, 95% CI ≈ (1.21, 1.56), p < 0.001
111
+ ```
112
+
113
+ ### Observational data (confounded treatment)
114
+
115
+ ```python
116
+ x1, x2 = rng.normal(size=n), rng.normal(size=n)
117
+ t = rng.binomial(1, 1 / (1 + np.exp(-(0.5 * x1 + 0.3 * x2)))) # x1, x2 drive treatment
118
+ y = 2.0 * t + x1 + 0.5 * x2 + rng.normal(0, 0.5, n) # true ATE = 2.0
119
+ obs = pd.DataFrame({"x1": x1, "x2": x2, "t": t, "y": y})
120
+
121
+ # ATE with propensity score methods
122
+ ipw(obs, "x1 + x2", T="t", Y="y") # ≈ 1.99
123
+ doubly_robust(obs, "x1 + x2", T="t", Y="y") # ≈ 1.98
124
+
125
+ # CATE with meta-learners: fit on train, score test
126
+ train, test = obs.iloc[:1600], obs.iloc[1600:]
127
+ X = ["x1", "x2"]
128
+
129
+ s_out = s_learner_discrete(train, test, X, "t", "y")
130
+ t_out = t_learner_discrete(train, test, X, "t", "y")
131
+ x_out = x_learner_discrete(train, test, X, "t", "y")
132
+ dml_out = double_ml_cate(train, test, X, "t", "y")
133
+
134
+ dml_out["cate"].mean() # ≈ 2.00 (S/T/X-learners give ≈ 2.02–2.04)
135
+ ```
136
+
137
+ ## API reference
138
+
139
+ All functions can be imported from the top level of the package.
140
+
141
+ ### Randomized experiments (`rct.py`)
142
+
143
+ #### `calculate_ate_ci(data, alpha=0.05)`
144
+
145
+ Difference-in-means ATE with a normal-approximation confidence interval.
146
+
147
+ | Parameter | Type | Description |
148
+ |---|---|---|
149
+ | `data` | `pd.DataFrame` | Must contain a binary treatment column `T` (0/1) and an outcome column `Y` |
150
+ | `alpha` | `float` | Significance level; the interval has coverage `1 - alpha` (default `0.05`) |
151
+
152
+ **Returns** `(ate, ci_lower, ci_upper)`, a tuple of floats. The standard error is
153
+ `sqrt(SE_treated² + SE_control²)`.
154
+
155
+ #### `calculate_ate_pvalue(data)`
156
+
157
+ Two-sided test of H₀: ATE = 0, using a normal approximation.
158
+
159
+ | Parameter | Type | Description |
160
+ |---|---|---|
161
+ | `data` | `pd.DataFrame` | Must contain columns `T` (0/1) and `Y` |
162
+
163
+ **Returns** `(ate, t_statistic, p_value)`, a tuple of floats.
164
+
165
+ ### Propensity score methods (`propensity.py`)
166
+
167
+ Both functions estimate the propensity score e(x) = P(T = 1 | X) with an
168
+ unpenalized logistic regression. The covariates are specified as a
169
+ [patsy](https://patsy.readthedocs.io/) formula, for example `"x1 + x2"` or
170
+ `"age + C(region)"`.
171
+
172
+ #### `ipw(df, ps_formula, T, Y)`
173
+
174
+ ATE by inverse propensity weighting: mean of `(T − e(x)) / (e(x)(1 − e(x))) · Y`.
175
+
176
+ | Parameter | Type | Description |
177
+ |---|---|---|
178
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
179
+ | `ps_formula` | `str` | Patsy right-hand-side formula for the propensity model |
180
+ | `T` | `str` | Name of the binary treatment column |
181
+ | `Y` | `str` | Name of the outcome column |
182
+
183
+ **Returns** the estimated ATE as a `float`.
184
+
185
+ #### `doubly_robust(df, formula, T, Y)`
186
+
187
+ ATE by augmented IPW. The estimator combines the propensity model with separate
188
+ linear outcome models for the treated and control groups. It stays consistent
189
+ if *either* the propensity model or the outcome models are correctly specified.
190
+
191
+ | Parameter | Type | Description |
192
+ |---|---|---|
193
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
194
+ | `formula` | `str` | Patsy formula used for both the propensity and outcome models |
195
+ | `T` | `str` | Name of the binary treatment column |
196
+ | `Y` | `str` | Name of the outcome column |
197
+
198
+ **Returns** the estimated ATE as a `float`.
199
+
200
+ ### Meta-learners (`meta_learners.py`)
201
+
202
+ All four functions share the same signature and return value. They fit models
203
+ on `train` and estimate the CATE for every row of `test`. The underlying
204
+ models are LightGBM regressors with default hyperparameters.
205
+
206
+ | Parameter | Type | Description |
207
+ |---|---|---|
208
+ | `train` | `pd.DataFrame` | Training data (covariates, treatment and outcome) |
209
+ | `test` | `pd.DataFrame` | Data to score; it needs the covariate columns |
210
+ | `X` | `list[str]` | Covariate column names |
211
+ | `T` | `str` | Treatment column name |
212
+ | `y` | `str` | Outcome column name |
213
+
214
+ **Returns** a copy of `test` with an added `cate` column.
215
+
216
+ | Function | Treatment | Method |
217
+ |---|---|---|
218
+ | `s_learner_discrete` | Binary | One model on `X + T`. CATE = prediction with T=1 minus prediction with T=0 |
219
+ | `t_learner_discrete` | Binary | Separate outcome models for the treated and control groups. CATE = difference of their predictions |
220
+ | `x_learner_discrete` | Binary | Imputes individual effects from T-learner models, models them within each group, then blends with a logistic propensity score |
221
+ | `double_ml_cate` | Binary **or continuous** | Residualizes T and Y on X with 5-fold cross-fitting, then fits a weighted model to the ratio `Ỹ / T̃` |
222
+
223
+ ## Running the tests
224
+
225
+ ```bash
226
+ uv run pytest
227
+ ```
228
+
229
+ This runs the suite in `tests/` with a coverage report: terminal output plus an
230
+ HTML report in `htmlcov/`.
231
+
232
+ ## Notes
233
+
234
+ - LightGBM prints `[LightGBM] [Info]` messages while it trains. These are
235
+ informational, not errors.
236
+
237
+ ## License
238
+
239
+ MIT. See [LICENSE](https://github.com/rhettbergeson/causal-toolkit-bergeson/blob/main/LICENSE).
240
+
241
+ ---
242
+
243
+ *AI disclosure: README drafted with Claude Opus 5.5 (Anthropic) and reviewed by me.*
@@ -0,0 +1,205 @@
1
+ # causal-toolkit-bergeson
2
+
3
+ [![Tests](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions/workflows/tests.yml/badge.svg)](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions)
4
+ [![PyPI version](https://badge.fury.io/py/causal-toolkit-bergeson.svg)](https://pypi.org/project/causal-toolkit-bergeson/)
5
+
6
+ A Python package for estimating causal effects. It collects the methods built in
7
+ UChicago's *Causal Models in Data Science* (ADSP 32029) course into one installable
8
+ toolkit:
9
+
10
+ - **Randomized experiments**: average treatment effect (ATE) with confidence
11
+ intervals and p-values
12
+ - **Propensity score methods**: inverse propensity weighting (IPW) and doubly
13
+ robust (AIPW) estimation of the ATE
14
+ - **Meta-learners**: S-, T- and X-learners and Double ML for estimating
15
+ conditional average treatment effects (CATE)
16
+
17
+ ## Installation
18
+
19
+ Requires Python 3.8+. Install from [PyPI](https://pypi.org/project/causal-toolkit-bergeson/):
20
+
21
+ ```bash
22
+ pip install causal-toolkit-bergeson
23
+ ```
24
+
25
+ ### From source (for development)
26
+
27
+ Clone the repository and install in editable mode with [uv](https://docs.astral.sh/uv/):
28
+
29
+ ```bash
30
+ # Clone the repository
31
+ git clone https://github.com/rhettbergeson/causal-toolkit-bergeson.git
32
+ cd causal-toolkit-bergeson
33
+
34
+ # Install in editable mode
35
+ uv pip install -e .
36
+
37
+ # Run the test suite to verify the installation
38
+ uv run pytest
39
+ ```
40
+
41
+ The package installs as `causal-toolkit-bergeson` but is imported as
42
+ `causal_toolkit_bergeson` (Python import names can't contain hyphens).
43
+
44
+ Using plain pip instead? `pip install -e ".[dev]"` installs the package along with
45
+ the testing and linting tools.
46
+
47
+ ## Quick start
48
+
49
+ ```python
50
+ import numpy as np
51
+ import pandas as pd
52
+ from causal_toolkit_bergeson import (
53
+ calculate_ate_ci, calculate_ate_pvalue, ipw, doubly_robust,
54
+ s_learner_discrete, t_learner_discrete, x_learner_discrete, double_ml_cate,
55
+ )
56
+
57
+ rng = np.random.default_rng(0)
58
+ n = 2000
59
+ ```
60
+
61
+ ### Randomized experiment
62
+
63
+ The RCT functions expect a binary treatment column named `T` and an outcome
64
+ column named `Y`.
65
+
66
+ ```python
67
+ rct = pd.DataFrame({"T": rng.binomial(1, 0.5, n)})
68
+ rct["Y"] = 1.5 * rct["T"] + rng.normal(0, 2, n) # true ATE = 1.5
69
+
70
+ ate, ci_lower, ci_upper = calculate_ate_ci(rct, alpha=0.05)
71
+ ate, t_stat, p_value = calculate_ate_pvalue(rct)
72
+ # ATE ≈ 1.39, 95% CI ≈ (1.21, 1.56), p < 0.001
73
+ ```
74
+
75
+ ### Observational data (confounded treatment)
76
+
77
+ ```python
78
+ x1, x2 = rng.normal(size=n), rng.normal(size=n)
79
+ t = rng.binomial(1, 1 / (1 + np.exp(-(0.5 * x1 + 0.3 * x2)))) # x1, x2 drive treatment
80
+ y = 2.0 * t + x1 + 0.5 * x2 + rng.normal(0, 0.5, n) # true ATE = 2.0
81
+ obs = pd.DataFrame({"x1": x1, "x2": x2, "t": t, "y": y})
82
+
83
+ # ATE with propensity score methods
84
+ ipw(obs, "x1 + x2", T="t", Y="y") # ≈ 1.99
85
+ doubly_robust(obs, "x1 + x2", T="t", Y="y") # ≈ 1.98
86
+
87
+ # CATE with meta-learners: fit on train, score test
88
+ train, test = obs.iloc[:1600], obs.iloc[1600:]
89
+ X = ["x1", "x2"]
90
+
91
+ s_out = s_learner_discrete(train, test, X, "t", "y")
92
+ t_out = t_learner_discrete(train, test, X, "t", "y")
93
+ x_out = x_learner_discrete(train, test, X, "t", "y")
94
+ dml_out = double_ml_cate(train, test, X, "t", "y")
95
+
96
+ dml_out["cate"].mean() # ≈ 2.00 (S/T/X-learners give ≈ 2.02–2.04)
97
+ ```
98
+
99
+ ## API reference
100
+
101
+ All functions can be imported from the top level of the package.
102
+
103
+ ### Randomized experiments (`rct.py`)
104
+
105
+ #### `calculate_ate_ci(data, alpha=0.05)`
106
+
107
+ Difference-in-means ATE with a normal-approximation confidence interval.
108
+
109
+ | Parameter | Type | Description |
110
+ |---|---|---|
111
+ | `data` | `pd.DataFrame` | Must contain a binary treatment column `T` (0/1) and an outcome column `Y` |
112
+ | `alpha` | `float` | Significance level; the interval has coverage `1 - alpha` (default `0.05`) |
113
+
114
+ **Returns** `(ate, ci_lower, ci_upper)`, a tuple of floats. The standard error is
115
+ `sqrt(SE_treated² + SE_control²)`.
116
+
117
+ #### `calculate_ate_pvalue(data)`
118
+
119
+ Two-sided test of H₀: ATE = 0, using a normal approximation.
120
+
121
+ | Parameter | Type | Description |
122
+ |---|---|---|
123
+ | `data` | `pd.DataFrame` | Must contain columns `T` (0/1) and `Y` |
124
+
125
+ **Returns** `(ate, t_statistic, p_value)`, a tuple of floats.
126
+
127
+ ### Propensity score methods (`propensity.py`)
128
+
129
+ Both functions estimate the propensity score e(x) = P(T = 1 | X) with an
130
+ unpenalized logistic regression. The covariates are specified as a
131
+ [patsy](https://patsy.readthedocs.io/) formula, for example `"x1 + x2"` or
132
+ `"age + C(region)"`.
133
+
134
+ #### `ipw(df, ps_formula, T, Y)`
135
+
136
+ ATE by inverse propensity weighting: mean of `(T − e(x)) / (e(x)(1 − e(x))) · Y`.
137
+
138
+ | Parameter | Type | Description |
139
+ |---|---|---|
140
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
141
+ | `ps_formula` | `str` | Patsy right-hand-side formula for the propensity model |
142
+ | `T` | `str` | Name of the binary treatment column |
143
+ | `Y` | `str` | Name of the outcome column |
144
+
145
+ **Returns** the estimated ATE as a `float`.
146
+
147
+ #### `doubly_robust(df, formula, T, Y)`
148
+
149
+ ATE by augmented IPW. The estimator combines the propensity model with separate
150
+ linear outcome models for the treated and control groups. It stays consistent
151
+ if *either* the propensity model or the outcome models are correctly specified.
152
+
153
+ | Parameter | Type | Description |
154
+ |---|---|---|
155
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
156
+ | `formula` | `str` | Patsy formula used for both the propensity and outcome models |
157
+ | `T` | `str` | Name of the binary treatment column |
158
+ | `Y` | `str` | Name of the outcome column |
159
+
160
+ **Returns** the estimated ATE as a `float`.
161
+
162
+ ### Meta-learners (`meta_learners.py`)
163
+
164
+ All four functions share the same signature and return value. They fit models
165
+ on `train` and estimate the CATE for every row of `test`. The underlying
166
+ models are LightGBM regressors with default hyperparameters.
167
+
168
+ | Parameter | Type | Description |
169
+ |---|---|---|
170
+ | `train` | `pd.DataFrame` | Training data (covariates, treatment and outcome) |
171
+ | `test` | `pd.DataFrame` | Data to score; it needs the covariate columns |
172
+ | `X` | `list[str]` | Covariate column names |
173
+ | `T` | `str` | Treatment column name |
174
+ | `y` | `str` | Outcome column name |
175
+
176
+ **Returns** a copy of `test` with an added `cate` column.
177
+
178
+ | Function | Treatment | Method |
179
+ |---|---|---|
180
+ | `s_learner_discrete` | Binary | One model on `X + T`. CATE = prediction with T=1 minus prediction with T=0 |
181
+ | `t_learner_discrete` | Binary | Separate outcome models for the treated and control groups. CATE = difference of their predictions |
182
+ | `x_learner_discrete` | Binary | Imputes individual effects from T-learner models, models them within each group, then blends with a logistic propensity score |
183
+ | `double_ml_cate` | Binary **or continuous** | Residualizes T and Y on X with 5-fold cross-fitting, then fits a weighted model to the ratio `Ỹ / T̃` |
184
+
185
+ ## Running the tests
186
+
187
+ ```bash
188
+ uv run pytest
189
+ ```
190
+
191
+ This runs the suite in `tests/` with a coverage report: terminal output plus an
192
+ HTML report in `htmlcov/`.
193
+
194
+ ## Notes
195
+
196
+ - LightGBM prints `[LightGBM] [Info]` messages while it trains. These are
197
+ informational, not errors.
198
+
199
+ ## License
200
+
201
+ MIT. See [LICENSE](https://github.com/rhettbergeson/causal-toolkit-bergeson/blob/main/LICENSE).
202
+
203
+ ---
204
+
205
+ *AI disclosure: README drafted with Claude Opus 5.5 (Anthropic) and reviewed by me.*
@@ -0,0 +1,24 @@
1
+ """Causal_Toolkit_Bergeson - Causal Inference Toolkit"""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ # Import key functions for easy access
6
+ from .rct import calculate_ate_ci, calculate_ate_pvalue
7
+ from .propensity import ipw, doubly_robust
8
+ from .meta_learners import (
9
+ s_learner_discrete,
10
+ t_learner_discrete,
11
+ x_learner_discrete,
12
+ double_ml_cate
13
+ )
14
+
15
+ __all__ = [
16
+ "calculate_ate_ci",
17
+ "calculate_ate_pvalue",
18
+ "ipw",
19
+ "doubly_robust",
20
+ "s_learner_discrete",
21
+ "t_learner_discrete",
22
+ "x_learner_discrete",
23
+ "double_ml_cate",
24
+ ]
@@ -0,0 +1,83 @@
1
+ # Wrote most of the code myself, and used Claude Opus 5.5 to correct mistakes & test
2
+ import pandas as pd
3
+ from lightgbm import LGBMRegressor
4
+ from sklearn.linear_model import LogisticRegression
5
+ from sklearn.model_selection import cross_val_predict
6
+ import numpy as np
7
+
8
+
9
+
10
+ # S-Learner
11
+ def s_learner_discrete(train, test, X, T, y) -> pd.DataFrame:
12
+ # Fit the S-Learner
13
+ s_learner = LGBMRegressor()
14
+ s_learner.fit(train[X+[T]], train[y])
15
+ # Filter Test dataframe
16
+ test_filtered = test[X + [T]]
17
+ # Create treated/control dataframes
18
+ test_0 = test_filtered.assign(**{T: 0})
19
+ test_1 = test_filtered.assign(**{T: 1})
20
+ # Define CATE
21
+ cate = s_learner.predict(test_1) - s_learner.predict(test_0)
22
+ # Apply CATE
23
+ s_learner_cate_test = test.assign(cate=cate)
24
+ # Return the dataframe
25
+ return s_learner_cate_test
26
+
27
+
28
+ # T-Learner
29
+ def t_learner_discrete(train, test, X, T, y) -> pd.DataFrame:
30
+ # Create models
31
+ m0 = LGBMRegressor()
32
+ m1 = LGBMRegressor()
33
+ # Fit models
34
+ m0.fit(train.query(f"{T}==0")[X], train.query(f"{T}==0")[y])
35
+ m1.fit(train.query(f"{T}==1")[X], train.query(f"{T}==1")[y])
36
+ # Assign values
37
+ t_learner_cate_test = test.assign(
38
+ cate=m1.predict(test[X]) - m0.predict(test[X]))
39
+ # return Dataframe
40
+ return t_learner_cate_test
41
+
42
+
43
+
44
+ # X-Learner
45
+ def x_learner_discrete(train, test, X, T, y) -> pd.DataFrame:
46
+ # Split train by treatment group
47
+ ctrl = train[train[T] == 0]
48
+ trt = train[train[T] == 1]
49
+ # Outcome models (same as T-learner)
50
+ m0 = LGBMRegressor().fit(ctrl[X], ctrl[y])
51
+ m1 = LGBMRegressor().fit(trt[X], trt[y])
52
+ # Imputed treatment effects
53
+ tau_0 = m1.predict(ctrl[X]) - ctrl[y] # controls: imputed treated outcome minus actual
54
+ tau_1 = trt[y] - m0.predict(trt[X]) # treated: actual minus imputed control outcome
55
+ # Propensity score e(x) on test
56
+ ps_model = LogisticRegression(penalty=None).fit(train[X], train[T])
57
+ ps = ps_model.predict_proba(test[X])[:, 1] # column 1 = P(T=1 | x)
58
+ # X Learner models
59
+ mu_tau0 = LGBMRegressor().fit(ctrl[X], tau_0)
60
+ mu_tau1 = LGBMRegressor().fit(trt[X], tau_1)
61
+ # Calculate CATE: propensity-weighted blend of the two effect models
62
+ cate = ((1 - ps) * mu_tau1.predict(test[X]) +
63
+ ps * mu_tau0.predict(test[X]))
64
+ # Return Dataframe
65
+ return test.assign(cate=cate)
66
+
67
+
68
+
69
+ # Double ML
70
+ def double_ml_cate(train, test, X, T, y) -> pd.DataFrame:
71
+ # Models
72
+ debias_m = LGBMRegressor()
73
+ denoise_m = LGBMRegressor()
74
+ # Residuals
75
+ t_res = train[T] - cross_val_predict(debias_m,train[X],train[T],cv=5)
76
+ y_res = train[y] - cross_val_predict(denoise_m,train[X],train[y],cv=5)
77
+ # Transformed outcomes and weights
78
+ y_star = y_res/t_res
79
+ w = t_res**2
80
+ # Build CATE model
81
+ cate_model = LGBMRegressor().fit(train[X], y_star, sample_weight=w)
82
+ # Predict CATE on test & return Dataframe
83
+ return test.assign(cate=cate_model.predict(test[X]))
@@ -0,0 +1,39 @@
1
+ # Wrote the code myself, and used Claude Opus 5.5 to verify correctness
2
+ import pandas as pd
3
+ import numpy as np
4
+ import patsy
5
+ from sklearn.linear_model import LogisticRegression
6
+ from sklearn.linear_model import LinearRegression
7
+
8
+
9
+
10
+
11
+ # Calculate the Average Treatment Effect using Inverse Propensity Weighting.
12
+ def ipw(df: pd.DataFrame, ps_formula: str, T: str, Y: str) -> float:
13
+ X = patsy.dmatrix(ps_formula, df)
14
+ ps_model = LogisticRegression(penalty=None, max_iter=1000).fit(X, df[T])
15
+ ps = ps_model.predict_proba(X)[:, 1]
16
+ # Compute ATE
17
+ return np.mean((df[T]-ps) / (ps*(1-ps)) * df[Y])
18
+
19
+
20
+
21
+
22
+
23
+ # Calculate the Average Treatment Effect using Doubly Robust Estimation.
24
+ def doubly_robust(df: pd.DataFrame, formula: str, T: str, Y: str) -> float:
25
+ X = patsy.dmatrix(formula, df)
26
+ ps_model = LogisticRegression(penalty=None, max_iter=1000).fit(X, df[T])
27
+ ps = ps_model.predict_proba(X)[:, 1]
28
+ # Fit Outcome Models
29
+ m0 = LinearRegression().fit(X[df[T]==0, :], df.query(f"{T}==0")[Y])
30
+ m1 = LinearRegression().fit(X[df[T]==1, :], df.query(f"{T}==1")[Y])
31
+ # Get predictions
32
+ m0_hat = m0.predict(X)
33
+ m1_hat = m1.predict(X)
34
+ # Calculate ATE using doubly robust formula
35
+ return (
36
+ np.mean(df[T]*(df[Y] - m1_hat)/ps + m1_hat) -
37
+ np.mean((1-df[T])*(df[Y] - m0_hat)/(1-ps) + m0_hat)
38
+ )
39
+
@@ -0,0 +1,42 @@
1
+ # Wrote the code myself, and used Claude Opus 5.5 to verify correctness
2
+ import pandas as pd
3
+ import numpy as np
4
+ from typing import Tuple
5
+ import math
6
+ import scipy.stats as stats
7
+
8
+
9
+ # Calculate the confidence interval for the Average Treatment Effect.
10
+ def calculate_ate_ci(data: pd.DataFrame, alpha: float = 0.05) -> Tuple[float, float, float]:
11
+ # Split into treated/untreated
12
+ treated_df = data[data['T'] == 1]
13
+ untreated_df = data[data['T'] == 0]
14
+ # Calculate ATE
15
+ ATE_estimate = float(treated_df['Y'].mean() - untreated_df['Y'].mean())
16
+ # Calculate Standard Error
17
+ se = math.sqrt(treated_df['Y'].sem() ** 2 + untreated_df['Y'].sem() ** 2)
18
+ # Build confidence interval
19
+ ci = stats.norm.interval((1-alpha), ATE_estimate, se)
20
+ CI_lower = float(ci[0])
21
+ CI_upper = float(ci[1])
22
+ # Results
23
+ results = (ATE_estimate, CI_lower, CI_upper)
24
+ return results
25
+
26
+
27
+
28
+ # Calculate the p-value for testing whether the ATE differs from a null hypothesis value.
29
+ def calculate_ate_pvalue(data: pd.DataFrame) -> Tuple[float, float, float]:
30
+ # Split into treated/untreated
31
+ treated_df = data[data['T'] == 1]
32
+ untreated_df = data[data['T'] == 0]
33
+ # Calculate ATE
34
+ ATE_estimate = float(treated_df['Y'].mean() - untreated_df['Y'].mean())
35
+ # Calculate Standard Error
36
+ se = math.sqrt(treated_df['Y'].sem() ** 2 + untreated_df['Y'].sem() ** 2)
37
+ # Calculate Test Stat & P-Value
38
+ t_statistic = (ATE_estimate - 0) / se
39
+ p_value = float(2 * (1 - stats.norm.cdf(abs(t_statistic))))
40
+ # Results
41
+ results = (ATE_estimate, t_statistic, p_value)
42
+ return results
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: causal-toolkit-bergeson
3
+ Version: 0.1.0
4
+ Summary: A Python package for causal inference methods including ATE estimation, propensity score methods, and meta-learners
5
+ Author-email: Rhett Bergeson <rhettbergeson@uchicago.edu>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/rhettbergeson/causal-toolkit-bergeson
8
+ Project-URL: Documentation, https://github.com/rhettbergeson/causal-toolkit-bergeson#readme
9
+ Project-URL: Repository, https://github.com/rhettbergeson/causal-toolkit-bergeson
10
+ Project-URL: Bug Tracker, https://github.com/rhettbergeson/causal-toolkit-bergeson/issues
11
+ Keywords: causal inference,statistics,machine learning,treatment effects
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
21
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: pandas>=1.3.0
26
+ Requires-Dist: numpy>=1.21.0
27
+ Requires-Dist: scipy>=1.7.0
28
+ Requires-Dist: scikit-learn>=1.0.0
29
+ Requires-Dist: lightgbm>=3.3.0
30
+ Requires-Dist: patsy>=0.5.0
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
33
+ Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
34
+ Requires-Dist: black>=22.0.0; extra == "dev"
35
+ Requires-Dist: pylint>=2.12.0; extra == "dev"
36
+ Requires-Dist: mypy>=0.950; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # causal-toolkit-bergeson
40
+
41
+ [![Tests](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions/workflows/tests.yml/badge.svg)](https://github.com/rhettbergeson/causal-toolkit-bergeson/actions)
42
+ [![PyPI version](https://badge.fury.io/py/causal-toolkit-bergeson.svg)](https://pypi.org/project/causal-toolkit-bergeson/)
43
+
44
+ A Python package for estimating causal effects. It collects the methods built in
45
+ UChicago's *Causal Models in Data Science* (ADSP 32029) course into one installable
46
+ toolkit:
47
+
48
+ - **Randomized experiments**: average treatment effect (ATE) with confidence
49
+ intervals and p-values
50
+ - **Propensity score methods**: inverse propensity weighting (IPW) and doubly
51
+ robust (AIPW) estimation of the ATE
52
+ - **Meta-learners**: S-, T- and X-learners and Double ML for estimating
53
+ conditional average treatment effects (CATE)
54
+
55
+ ## Installation
56
+
57
+ Requires Python 3.8+. Install from [PyPI](https://pypi.org/project/causal-toolkit-bergeson/):
58
+
59
+ ```bash
60
+ pip install causal-toolkit-bergeson
61
+ ```
62
+
63
+ ### From source (for development)
64
+
65
+ Clone the repository and install in editable mode with [uv](https://docs.astral.sh/uv/):
66
+
67
+ ```bash
68
+ # Clone the repository
69
+ git clone https://github.com/rhettbergeson/causal-toolkit-bergeson.git
70
+ cd causal-toolkit-bergeson
71
+
72
+ # Install in editable mode
73
+ uv pip install -e .
74
+
75
+ # Run the test suite to verify the installation
76
+ uv run pytest
77
+ ```
78
+
79
+ The package installs as `causal-toolkit-bergeson` but is imported as
80
+ `causal_toolkit_bergeson` (Python import names can't contain hyphens).
81
+
82
+ Using plain pip instead? `pip install -e ".[dev]"` installs the package along with
83
+ the testing and linting tools.
84
+
85
+ ## Quick start
86
+
87
+ ```python
88
+ import numpy as np
89
+ import pandas as pd
90
+ from causal_toolkit_bergeson import (
91
+ calculate_ate_ci, calculate_ate_pvalue, ipw, doubly_robust,
92
+ s_learner_discrete, t_learner_discrete, x_learner_discrete, double_ml_cate,
93
+ )
94
+
95
+ rng = np.random.default_rng(0)
96
+ n = 2000
97
+ ```
98
+
99
+ ### Randomized experiment
100
+
101
+ The RCT functions expect a binary treatment column named `T` and an outcome
102
+ column named `Y`.
103
+
104
+ ```python
105
+ rct = pd.DataFrame({"T": rng.binomial(1, 0.5, n)})
106
+ rct["Y"] = 1.5 * rct["T"] + rng.normal(0, 2, n) # true ATE = 1.5
107
+
108
+ ate, ci_lower, ci_upper = calculate_ate_ci(rct, alpha=0.05)
109
+ ate, t_stat, p_value = calculate_ate_pvalue(rct)
110
+ # ATE ≈ 1.39, 95% CI ≈ (1.21, 1.56), p < 0.001
111
+ ```
112
+
113
+ ### Observational data (confounded treatment)
114
+
115
+ ```python
116
+ x1, x2 = rng.normal(size=n), rng.normal(size=n)
117
+ t = rng.binomial(1, 1 / (1 + np.exp(-(0.5 * x1 + 0.3 * x2)))) # x1, x2 drive treatment
118
+ y = 2.0 * t + x1 + 0.5 * x2 + rng.normal(0, 0.5, n) # true ATE = 2.0
119
+ obs = pd.DataFrame({"x1": x1, "x2": x2, "t": t, "y": y})
120
+
121
+ # ATE with propensity score methods
122
+ ipw(obs, "x1 + x2", T="t", Y="y") # ≈ 1.99
123
+ doubly_robust(obs, "x1 + x2", T="t", Y="y") # ≈ 1.98
124
+
125
+ # CATE with meta-learners: fit on train, score test
126
+ train, test = obs.iloc[:1600], obs.iloc[1600:]
127
+ X = ["x1", "x2"]
128
+
129
+ s_out = s_learner_discrete(train, test, X, "t", "y")
130
+ t_out = t_learner_discrete(train, test, X, "t", "y")
131
+ x_out = x_learner_discrete(train, test, X, "t", "y")
132
+ dml_out = double_ml_cate(train, test, X, "t", "y")
133
+
134
+ dml_out["cate"].mean() # ≈ 2.00 (S/T/X-learners give ≈ 2.02–2.04)
135
+ ```
136
+
137
+ ## API reference
138
+
139
+ All functions can be imported from the top level of the package.
140
+
141
+ ### Randomized experiments (`rct.py`)
142
+
143
+ #### `calculate_ate_ci(data, alpha=0.05)`
144
+
145
+ Difference-in-means ATE with a normal-approximation confidence interval.
146
+
147
+ | Parameter | Type | Description |
148
+ |---|---|---|
149
+ | `data` | `pd.DataFrame` | Must contain a binary treatment column `T` (0/1) and an outcome column `Y` |
150
+ | `alpha` | `float` | Significance level; the interval has coverage `1 - alpha` (default `0.05`) |
151
+
152
+ **Returns** `(ate, ci_lower, ci_upper)`, a tuple of floats. The standard error is
153
+ `sqrt(SE_treated² + SE_control²)`.
154
+
155
+ #### `calculate_ate_pvalue(data)`
156
+
157
+ Two-sided test of H₀: ATE = 0, using a normal approximation.
158
+
159
+ | Parameter | Type | Description |
160
+ |---|---|---|
161
+ | `data` | `pd.DataFrame` | Must contain columns `T` (0/1) and `Y` |
162
+
163
+ **Returns** `(ate, t_statistic, p_value)`, a tuple of floats.
164
+
165
+ ### Propensity score methods (`propensity.py`)
166
+
167
+ Both functions estimate the propensity score e(x) = P(T = 1 | X) with an
168
+ unpenalized logistic regression. The covariates are specified as a
169
+ [patsy](https://patsy.readthedocs.io/) formula, for example `"x1 + x2"` or
170
+ `"age + C(region)"`.
171
+
172
+ #### `ipw(df, ps_formula, T, Y)`
173
+
174
+ ATE by inverse propensity weighting: mean of `(T − e(x)) / (e(x)(1 − e(x))) · Y`.
175
+
176
+ | Parameter | Type | Description |
177
+ |---|---|---|
178
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
179
+ | `ps_formula` | `str` | Patsy right-hand-side formula for the propensity model |
180
+ | `T` | `str` | Name of the binary treatment column |
181
+ | `Y` | `str` | Name of the outcome column |
182
+
183
+ **Returns** the estimated ATE as a `float`.
184
+
185
+ #### `doubly_robust(df, formula, T, Y)`
186
+
187
+ ATE by augmented IPW. The estimator combines the propensity model with separate
188
+ linear outcome models for the treated and control groups. It stays consistent
189
+ if *either* the propensity model or the outcome models are correctly specified.
190
+
191
+ | Parameter | Type | Description |
192
+ |---|---|---|
193
+ | `df` | `pd.DataFrame` | Data containing the treatment, outcome and covariates |
194
+ | `formula` | `str` | Patsy formula used for both the propensity and outcome models |
195
+ | `T` | `str` | Name of the binary treatment column |
196
+ | `Y` | `str` | Name of the outcome column |
197
+
198
+ **Returns** the estimated ATE as a `float`.
199
+
200
+ ### Meta-learners (`meta_learners.py`)
201
+
202
+ All four functions share the same signature and return value. They fit models
203
+ on `train` and estimate the CATE for every row of `test`. The underlying
204
+ models are LightGBM regressors with default hyperparameters.
205
+
206
+ | Parameter | Type | Description |
207
+ |---|---|---|
208
+ | `train` | `pd.DataFrame` | Training data (covariates, treatment and outcome) |
209
+ | `test` | `pd.DataFrame` | Data to score; it needs the covariate columns |
210
+ | `X` | `list[str]` | Covariate column names |
211
+ | `T` | `str` | Treatment column name |
212
+ | `y` | `str` | Outcome column name |
213
+
214
+ **Returns** a copy of `test` with an added `cate` column.
215
+
216
+ | Function | Treatment | Method |
217
+ |---|---|---|
218
+ | `s_learner_discrete` | Binary | One model on `X + T`. CATE = prediction with T=1 minus prediction with T=0 |
219
+ | `t_learner_discrete` | Binary | Separate outcome models for the treated and control groups. CATE = difference of their predictions |
220
+ | `x_learner_discrete` | Binary | Imputes individual effects from T-learner models, models them within each group, then blends with a logistic propensity score |
221
+ | `double_ml_cate` | Binary **or continuous** | Residualizes T and Y on X with 5-fold cross-fitting, then fits a weighted model to the ratio `Ỹ / T̃` |
222
+
223
+ ## Running the tests
224
+
225
+ ```bash
226
+ uv run pytest
227
+ ```
228
+
229
+ This runs the suite in `tests/` with a coverage report: terminal output plus an
230
+ HTML report in `htmlcov/`.
231
+
232
+ ## Notes
233
+
234
+ - LightGBM prints `[LightGBM] [Info]` messages while it trains. These are
235
+ informational, not errors.
236
+
237
+ ## License
238
+
239
+ MIT. See [LICENSE](https://github.com/rhettbergeson/causal-toolkit-bergeson/blob/main/LICENSE).
240
+
241
+ ---
242
+
243
+ *AI disclosure: README drafted with Claude Opus 5.5 (Anthropic) and reviewed by me.*
@@ -0,0 +1,13 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ causal_toolkit_bergeson/__init__.py
5
+ causal_toolkit_bergeson/meta_learners.py
6
+ causal_toolkit_bergeson/propensity.py
7
+ causal_toolkit_bergeson/rct.py
8
+ causal_toolkit_bergeson.egg-info/PKG-INFO
9
+ causal_toolkit_bergeson.egg-info/SOURCES.txt
10
+ causal_toolkit_bergeson.egg-info/dependency_links.txt
11
+ causal_toolkit_bergeson.egg-info/requires.txt
12
+ causal_toolkit_bergeson.egg-info/top_level.txt
13
+ tests/test_meta_learners.py
@@ -0,0 +1,13 @@
1
+ pandas>=1.3.0
2
+ numpy>=1.21.0
3
+ scipy>=1.7.0
4
+ scikit-learn>=1.0.0
5
+ lightgbm>=3.3.0
6
+ patsy>=0.5.0
7
+
8
+ [dev]
9
+ pytest>=7.0.0
10
+ pytest-cov>=3.0.0
11
+ black>=22.0.0
12
+ pylint>=2.12.0
13
+ mypy>=0.950
@@ -0,0 +1 @@
1
+ causal_toolkit_bergeson
@@ -0,0 +1,77 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "causal-toolkit-bergeson"
7
+ version = "0.1.0"
8
+ description = "A Python package for causal inference methods including ATE estimation, propensity score methods, and meta-learners"
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ license = {text = "MIT"}
12
+ authors = [
13
+ {name = "Rhett Bergeson", email = "rhettbergeson@uchicago.edu"}
14
+ ]
15
+ keywords = ["causal inference", "statistics", "machine learning", "treatment effects"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Science/Research",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.8",
22
+ "Programming Language :: Python :: 3.9",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Topic :: Scientific/Engineering :: Mathematics",
26
+ "Topic :: Scientific/Engineering :: Information Analysis",
27
+ ]
28
+
29
+ dependencies = [
30
+ "pandas>=1.3.0",
31
+ "numpy>=1.21.0",
32
+ "scipy>=1.7.0",
33
+ "scikit-learn>=1.0.0",
34
+ "lightgbm>=3.3.0",
35
+ "patsy>=0.5.0",
36
+ ]
37
+
38
+ [project.optional-dependencies]
39
+ dev = [
40
+ "pytest>=7.0.0",
41
+ "pytest-cov>=3.0.0",
42
+ "black>=22.0.0",
43
+ "pylint>=2.12.0",
44
+ "mypy>=0.950",
45
+ ]
46
+
47
+ # Installed automatically by `uv run`, so `uv run pytest` works after a plain
48
+ # `uv pip install -e .` (optional-dependencies above are NOT installed by uv run)
49
+ [dependency-groups]
50
+ dev = [
51
+ "pytest>=7.0.0",
52
+ "pytest-cov>=3.0.0",
53
+ ]
54
+
55
+ [project.urls]
56
+ Homepage = "https://github.com/rhettbergeson/causal-toolkit-bergeson"
57
+ Documentation = "https://github.com/rhettbergeson/causal-toolkit-bergeson#readme"
58
+ Repository = "https://github.com/rhettbergeson/causal-toolkit-bergeson"
59
+ "Bug Tracker" = "https://github.com/rhettbergeson/causal-toolkit-bergeson/issues"
60
+
61
+ [tool.pytest.ini_options]
62
+ testpaths = ["tests"]
63
+ python_files = ["test_*.py"]
64
+ python_classes = ["Test*"]
65
+ python_functions = ["test_*"]
66
+ addopts = "-v --cov=causal_toolkit_bergeson --cov-report=html --cov-report=term"
67
+
68
+ [tool.black]
69
+ line-length = 88
70
+ target-version = ['py38', 'py39', 'py310', 'py311']
71
+ include = '\.pyi?$'
72
+
73
+ [tool.mypy]
74
+ python_version = "3.8"
75
+ warn_return_any = true
76
+ warn_unused_configs = true
77
+ disallow_untyped_defs = false
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,212 @@
1
+ # AI disclosure: Test code drafted with Claude Opus 5.5 (Anthropic); reviewed and run by me.
2
+ #
3
+ # Pytest tests for the meta-learners in causal_toolkit_bergeson/meta_learners.py.
4
+ # Run from the repository root with: uv run pytest
5
+ #
6
+ # How pytest works here (quick primer):
7
+ # - pytest finds every function whose name starts with `test_` and runs it.
8
+ # - A test PASSES if it finishes without raising an exception.
9
+ # - A test FAILS if any `assert` is False (or the code under test crashes).
10
+ # - simple_data() / continuous_treatment_data() do NOT start with `test_`,
11
+ # so pytest treats them as ordinary helpers, not tests.
12
+
13
+ import numpy as np
14
+ import pandas as pd
15
+
16
+ # Imported from the package's top level so __init__.py exports are exercised too
17
+ from causal_toolkit_bergeson import (
18
+ s_learner_discrete,
19
+ t_learner_discrete,
20
+ x_learner_discrete,
21
+ double_ml_cate,
22
+ )
23
+
24
+
25
+ # =============================================================================
26
+ # Test data generation (provided by the assignment; copied as-is)
27
+ # NOTE: Not decorated with @pytest.fixture because Gradescope doesn't support
28
+ # it here. Each test calls these directly, so data is regenerated per test.
29
+ # The fixed seeds make every call return identical data, so tests are
30
+ # deterministic (same result every run).
31
+ # =============================================================================
32
+
33
+ def simple_data():
34
+ """Generate simple data with known treatment effect"""
35
+ np.random.seed(42)
36
+ n = 1000
37
+
38
+ # Covariates
39
+ x1 = np.random.normal(0, 1, n)
40
+ x2 = np.random.normal(0, 1, n)
41
+
42
+ # Treatment assignment (confounded)
43
+ prob_t = 1 / (1 + np.exp(-(0.5 * x1 + 0.3 * x2)))
44
+ t = np.random.binomial(1, prob_t, n)
45
+
46
+ # Outcome with constant treatment effect = 2.0
47
+ y = 2.0 * t + x1 + 0.5 * x2 + np.random.normal(0, 0.5, n)
48
+
49
+ df = pd.DataFrame({'x1': x1, 'x2': x2, 't': t, 'y': y})
50
+
51
+ # Split into train/test
52
+ train = df.iloc[:800].copy()
53
+ test = df.iloc[800:].copy()
54
+
55
+ return train, test
56
+
57
+
58
+ def continuous_treatment_data():
59
+ """Generate data with continuous treatment"""
60
+ np.random.seed(789)
61
+ n = 1000
62
+
63
+ # Covariates
64
+ x1 = np.random.normal(0, 1, n)
65
+ x2 = np.random.normal(0, 1, n)
66
+
67
+ # Continuous treatment
68
+ t = 10 + x1 + 2*x2 + np.random.normal(0, 1, n)
69
+
70
+ # Outcome: linear effect of treatment
71
+ y = t + x1 + 0.5*x2 + np.random.normal(0, 0.5, n)
72
+
73
+ df = pd.DataFrame({'x1': x1, 'x2': x2, 't': t, 'y': y})
74
+
75
+ train = df.iloc[:800].copy()
76
+ test = df.iloc[800:].copy()
77
+
78
+ return train, test
79
+
80
+
81
+ # =============================================================================
82
+ # Shared constants
83
+ # Column names match the data generators above.
84
+ # TRUE_EFFECT comes from the data-generating process: y = 2.0 * t + ...
85
+ # TOLERANCE is deliberately loose (25% of the true effect). LightGBM with
86
+ # default settings on 800 rows won't hit 2.0 exactly, and S-learners in
87
+ # particular tend to shrink the effect toward 0 (the tree may not split on t
88
+ # everywhere). A tight tolerance would make the test "flaky" — failing for
89
+ # reasons of estimation noise rather than an actual bug.
90
+ # =============================================================================
91
+
92
+ X = ['x1', 'x2']
93
+ T = 't'
94
+ Y = 'y'
95
+
96
+ TRUE_EFFECT = 2.0 # binary-treatment data: constant CATE of 2.0
97
+ TRUE_EFFECT_CONTINUOUS = 1.0 # continuous-treatment data: dy/dt = 1.0
98
+ TOLERANCE = 0.5
99
+
100
+
101
+ # =============================================================================
102
+ # S-Learner tests (5)
103
+ # Pattern for every test: 1) generate data 2) call function 3) assert
104
+ # =============================================================================
105
+
106
+ def test_s_learner_returns_dataframe():
107
+ """S-learner output should be a pandas DataFrame."""
108
+ train, test = simple_data()
109
+
110
+ result = s_learner_discrete(train, test, X, T, Y)
111
+
112
+ assert isinstance(result, pd.DataFrame)
113
+
114
+
115
+ def test_s_learner_has_cate_column():
116
+ """S-learner output should contain a 'cate' column, with one row per test row."""
117
+ train, test = simple_data()
118
+
119
+ result = s_learner_discrete(train, test, X, T, Y)
120
+
121
+ assert 'cate' in result.columns
122
+ # Extra guard: the function should score every test row (no rows dropped/added)
123
+ assert len(result) == len(test)
124
+
125
+
126
+ def test_s_learner_constant_effect():
127
+ """With a constant true effect of 2.0, the average estimated CATE should be close to 2.0."""
128
+ train, test = simple_data()
129
+
130
+ result = s_learner_discrete(train, test, X, T, Y)
131
+
132
+ # The ATE is the mean of the CATEs across the test set. We compare the
133
+ # ATE (not each individual CATE) because individual tree predictions are
134
+ # noisy; averaging over 200 rows smooths that noise out.
135
+ estimated_ate = result['cate'].mean()
136
+ assert abs(estimated_ate - TRUE_EFFECT) < TOLERANCE, (
137
+ f"Estimated ATE {estimated_ate:.3f} not within {TOLERANCE} of {TRUE_EFFECT}"
138
+ )
139
+
140
+
141
+ def test_s_learner_return_numeric_cate():
142
+ """CATE values should be a numeric dtype (e.g., float), not object/string."""
143
+ train, test = simple_data()
144
+
145
+ result = s_learner_discrete(train, test, X, T, Y)
146
+
147
+ assert pd.api.types.is_numeric_dtype(result['cate'])
148
+
149
+
150
+ def test_s_learner_no_nan_values():
151
+ """No CATE value should be NaN."""
152
+ train, test = simple_data()
153
+
154
+ result = s_learner_discrete(train, test, X, T, Y)
155
+
156
+ # .isna().any() is True if at least one NaN exists, so we assert it's False
157
+ assert not result['cate'].isna().any()
158
+
159
+
160
+ # =============================================================================
161
+ # T-Learner and X-Learner tests (1 each)
162
+ # =============================================================================
163
+
164
+ def test_t_learner_returns_dataframe():
165
+ """T-learner output should be a pandas DataFrame."""
166
+ train, test = simple_data()
167
+
168
+ result = t_learner_discrete(train, test, X, T, Y)
169
+
170
+ assert isinstance(result, pd.DataFrame)
171
+
172
+
173
+ def test_x_learner_returns_dataframe():
174
+ """X-learner output should be a pandas DataFrame."""
175
+ train, test = simple_data()
176
+
177
+ result = x_learner_discrete(train, test, X, T, Y)
178
+
179
+ assert isinstance(result, pd.DataFrame)
180
+
181
+
182
+ # =============================================================================
183
+ # Double ML tests (2)
184
+ # =============================================================================
185
+
186
+ def test_double_ml_returns_dataframe():
187
+ """Double ML output should be a pandas DataFrame (binary-treatment data)."""
188
+ train, test = simple_data()
189
+
190
+ result = double_ml_cate(train, test, X, T, Y)
191
+
192
+ assert isinstance(result, pd.DataFrame)
193
+
194
+
195
+ def test_double_ml_continuous_treatment():
196
+ """Double ML should run on a continuous treatment and return a usable result.
197
+
198
+ Why only Double ML gets this test: the S/T/X-learners above are the
199
+ "_discrete" versions — they split or set T to 0/1, which makes no sense for
200
+ a continuous T. Double ML works on residuals (T - E[T|X]), so it handles
201
+ any numeric treatment.
202
+ """
203
+ train, test = continuous_treatment_data()
204
+
205
+ result = double_ml_cate(train, test, X, T, Y)
206
+
207
+ # "Works with continuous T" = runs without crashing AND returns a usable result
208
+ assert isinstance(result, pd.DataFrame)
209
+ assert 'cate' in result.columns
210
+ assert len(result) == len(test)
211
+ assert pd.api.types.is_numeric_dtype(result['cate'])
212
+ assert not result['cate'].isna().any()