drcurves 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.
- drcurves-0.1.0/LICENSE +21 -0
- drcurves-0.1.0/PKG-INFO +272 -0
- drcurves-0.1.0/README.md +221 -0
- drcurves-0.1.0/pyproject.toml +70 -0
- drcurves-0.1.0/setup.cfg +4 -0
- drcurves-0.1.0/src/drcurves/__init__.py +291 -0
- drcurves-0.1.0/src/drcurves/balance.py +153 -0
- drcurves-0.1.0/src/drcurves/bootstrap.py +126 -0
- drcurves-0.1.0/src/drcurves/check.py +183 -0
- drcurves-0.1.0/src/drcurves/did.py +56 -0
- drcurves-0.1.0/src/drcurves/models.py +96 -0
- drcurves-0.1.0/src/drcurves/nuisance.py +481 -0
- drcurves-0.1.0/src/drcurves/pooled.py +630 -0
- drcurves-0.1.0/src/drcurves/riesz.py +261 -0
- drcurves-0.1.0/src/drcurves/simulate.py +150 -0
- drcurves-0.1.0/src/drcurves.egg-info/PKG-INFO +272 -0
- drcurves-0.1.0/src/drcurves.egg-info/SOURCES.txt +19 -0
- drcurves-0.1.0/src/drcurves.egg-info/dependency_links.txt +1 -0
- drcurves-0.1.0/src/drcurves.egg-info/requires.txt +28 -0
- drcurves-0.1.0/src/drcurves.egg-info/top_level.txt +1 -0
- drcurves-0.1.0/tests/test_drcurves.py +332 -0
drcurves-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ryan O'Sullivan
|
|
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.
|
drcurves-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: drcurves
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Doubly robust, partially pooled dose-response curves for continuous treatments
|
|
5
|
+
Author: Ryan O'Sullivan
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/raz1470/continuous-dr-learner
|
|
8
|
+
Project-URL: Documentation, https://raz1470.github.io/continuous-dr-learner/
|
|
9
|
+
Project-URL: Walkthrough, https://raz1470.github.io/continuous-dr-learner/walkthrough.html
|
|
10
|
+
Project-URL: Repository, https://github.com/raz1470/continuous-dr-learner
|
|
11
|
+
Project-URL: Issues, https://github.com/raz1470/continuous-dr-learner/issues
|
|
12
|
+
Project-URL: Changelog, https://github.com/raz1470/continuous-dr-learner/blob/main/CHANGELOG.md
|
|
13
|
+
Keywords: causal inference,dose-response,continuous treatment,doubly robust,double machine learning,hierarchical model,partial pooling,difference-in-differences
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: numpy>=1.23
|
|
27
|
+
Requires-Dist: scipy>=1.8
|
|
28
|
+
Requires-Dist: pandas>=1.5
|
|
29
|
+
Requires-Dist: scikit-learn>=1.2
|
|
30
|
+
Provides-Extra: plot
|
|
31
|
+
Requires-Dist: matplotlib>=3.5; extra == "plot"
|
|
32
|
+
Provides-Extra: experiments
|
|
33
|
+
Requires-Dist: doubleml>=0.9; extra == "experiments"
|
|
34
|
+
Requires-Dist: matplotlib>=3.5; extra == "experiments"
|
|
35
|
+
Requires-Dist: causal-curve; extra == "experiments"
|
|
36
|
+
Requires-Dist: playwright; extra == "experiments"
|
|
37
|
+
Provides-Extra: dev
|
|
38
|
+
Requires-Dist: pytest; extra == "dev"
|
|
39
|
+
Requires-Dist: ruff; extra == "dev"
|
|
40
|
+
Requires-Dist: matplotlib>=3.5; extra == "dev"
|
|
41
|
+
Requires-Dist: nbconvert; extra == "dev"
|
|
42
|
+
Requires-Dist: ipykernel; extra == "dev"
|
|
43
|
+
Provides-Extra: docs
|
|
44
|
+
Requires-Dist: sphinx>=7; extra == "docs"
|
|
45
|
+
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
|
|
46
|
+
Requires-Dist: numpydoc>=1.6; extra == "docs"
|
|
47
|
+
Requires-Dist: myst-nb>=1.0; extra == "docs"
|
|
48
|
+
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
|
|
49
|
+
Requires-Dist: matplotlib>=3.5; extra == "docs"
|
|
50
|
+
Dynamic: license-file
|
|
51
|
+
|
|
52
|
+
# drcurves
|
|
53
|
+
|
|
54
|
+
**Doubly robust dose-response curves for continuous treatments, for one population or many groups.**
|
|
55
|
+
|
|
56
|
+
How does the outcome change as the dose changes: discount depth and margin, handle time and
|
|
57
|
+
satisfaction, notifications per week and retention? `drcurves` estimates the whole curve, not one
|
|
58
|
+
slope, from observational data:
|
|
59
|
+
|
|
60
|
+
- **Doubly robust.** The curve stays close to the truth if either the outcome model or the dose
|
|
61
|
+
model is right (Kennedy et al. 2017).
|
|
62
|
+
- **Many curves at once.** A curve per store, product or customer issue, partially pooled across a
|
|
63
|
+
hierarchy (region → store), so small groups borrow strength from their parents.
|
|
64
|
+
- **Choose your assumption.** Adjust for measured confounders; or, with a pre-period outcome, use
|
|
65
|
+
difference-in-differences (`y_pre=`) when a stable trait you can't measure drives both the dose
|
|
66
|
+
and the outcome, or adjust for the lagged outcome (`design="lagged"`) when doses respond to past
|
|
67
|
+
outcomes. A placebo check tests the DiD assumption.
|
|
68
|
+
- **Sensible defaults.** Every nuisance model is a stack of a spline regression and gradient
|
|
69
|
+
boosting, which in our simulations beat boosting alone and the existing packages.
|
|
70
|
+
|
|
71
|
+
It accompanies the article *Estimating Continuous Treatment Effects: Doubly Robust Dose-Response
|
|
72
|
+
Curves*. Early release: the API may change before 1.0.
|
|
73
|
+
|
|
74
|
+
## Resources
|
|
75
|
+
|
|
76
|
+
| | |
|
|
77
|
+
|---|---|
|
|
78
|
+
| 📚 [Documentation](https://raz1470.github.io/continuous-dr-learner/) | User guide, examples and API reference |
|
|
79
|
+
| 📖 [Walkthrough](https://raz1470.github.io/continuous-dr-learner/walkthrough.html) | The article: why one slope isn't enough, and the method step by step on simulated data |
|
|
80
|
+
| 📓 [One curve](https://github.com/raz1470/continuous-dr-learner/blob/main/examples/01_one_curve.ipynb) | Fit with the defaults and read the results |
|
|
81
|
+
| 🏪 [Curves for many groups](https://github.com/raz1470/continuous-dr-learner/blob/main/examples/02_group_curves.ipynb) | A curve per store, pooled across regions |
|
|
82
|
+
| 🎯 [Checking the bands](https://raz1470.github.io/continuous-dr-learner/guide/checking_bands.html) | `coverage_check` on your own data |
|
|
83
|
+
| 🔬 [Research](https://raz1470.github.io/continuous-dr-learner/research.html) | How often the 95% bands contain the true curve |
|
|
84
|
+
| 📝 [Changelog](https://github.com/raz1470/continuous-dr-learner/blob/main/CHANGELOG.md) | What changed in each release |
|
|
85
|
+
|
|
86
|
+
## Install
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pip install drcurves
|
|
90
|
+
pip install "drcurves[plot]" # adds matplotlib for model.plot()
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Quick start
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
import numpy as np
|
|
97
|
+
from drcurves import fit_dose_response
|
|
98
|
+
from drcurves.simulate import sim_nonlinear
|
|
99
|
+
|
|
100
|
+
X, A, Y, truth = sim_nonlinear(n=3000, curve="inverted_u_centred", seed=1)
|
|
101
|
+
|
|
102
|
+
model = fit_dose_response(X, A, Y) # cross-fit, doubly robust, smooth curve
|
|
103
|
+
print(model.diagnostics()) # overlap and fit checks: read these first
|
|
104
|
+
|
|
105
|
+
grid = np.linspace(*np.quantile(A, [0.05, 0.95]), 50)
|
|
106
|
+
est, se = model.curve(grid) # curve and pointwise standard errors
|
|
107
|
+
est, lo, hi, _ = model.band(grid) # 95% band for the whole curve
|
|
108
|
+
lift, se = model.contrast(-1.0, 0.0) # effect of moving the dose from -1 to 0
|
|
109
|
+
best = model.optimal_dose(grid) # dose that maximises the outcome, with an interval
|
|
110
|
+
model.plot(truth=truth) # needs matplotlib
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Many groups
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from drcurves.simulate import sim_hierarchical
|
|
117
|
+
df, _, _ = sim_hierarchical(seed=0) # region, store, x0..x2, A, Y
|
|
118
|
+
|
|
119
|
+
model = fit_dose_response(df[["x0", "x1", "x2"]], df["A"], df["Y"],
|
|
120
|
+
groups=df[["region", "store"]]) # top -> bottom
|
|
121
|
+
store, se = model.curve(grid, ("r0", "r0_s03")) # a store's curve, shrunk toward its region
|
|
122
|
+
region, _ = model.curve(grid, ("r0",))
|
|
123
|
+
new, _ = model.curve(grid, ("r0", "unseen")) # a new store gets its region's curve
|
|
124
|
+
model.plot(paths=[("r0",), ("r0", "r0_s03")])
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
| Your data | `groups=` | What you get |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| One population | `None` | One curve |
|
|
130
|
+
| Groups, no hierarchy | `df[["store"]]` | One curve per store, shrunk toward the overall curve |
|
|
131
|
+
| Nested hierarchy | `df[["region", "store"]]` | Stores shrunk toward their region, regions toward the overall curve |
|
|
132
|
+
|
|
133
|
+
Levels must be nested; crossed groupings (store × channel) aren't supported. Shrinkage acts on each
|
|
134
|
+
group's shape; its overall level is left nearly free. `path=None` under partial pooling is a
|
|
135
|
+
"typical group" curve; for the population average, fit with `groups=None`.
|
|
136
|
+
|
|
137
|
+
## Choosing the assumption
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
# Measured confounders explain who got which dose (the default)
|
|
141
|
+
model = fit_dose_response(X, A, Y_post)
|
|
142
|
+
|
|
143
|
+
# A stable trait you can't measure drives dose and outcome: difference-in-differences
|
|
144
|
+
model = fit_dose_response(X, A, Y_post, y_pre=Y_pre)
|
|
145
|
+
|
|
146
|
+
# The dose responds to past outcomes: adjust for the lagged outcome instead
|
|
147
|
+
model = fit_dose_response(X, A, Y_post, y_pre=Y_pre, design="lagged")
|
|
148
|
+
|
|
149
|
+
# Placebo for DiD: the curve on two pre-periods should be flat. Judge it by size, not significance.
|
|
150
|
+
from drcurves import placebo_check
|
|
151
|
+
pc = placebo_check(X, A, Y_pre, Y_prepre, main=model)
|
|
152
|
+
pc["relative"] # largest placebo deviation / range of the real curve; small is good
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Comparing doses under DiD needs *strong* parallel trends: units on different doses would have
|
|
156
|
+
followed the same path had their doses been equal (Callaway, Goodman-Bacon & Sant'Anna 2024).
|
|
157
|
+
|
|
158
|
+
In simulation ([`experiments/sim_did.py`](https://github.com/raz1470/continuous-dr-learner/blob/main/experiments/sim_did.py)), each design wins in its own world, and the placebo tells
|
|
159
|
+
them apart (RMSE of the curve; placebo = largest deviation of the pre-period curve from flat):
|
|
160
|
+
|
|
161
|
+
| | Adjust for X | Lagged outcome | DiD | Placebo |
|
|
162
|
+
|---|---|---|---|---|
|
|
163
|
+
| A stable hidden trait drives the dose | 1.06 | 0.29 | **0.04** | 0.03 (flat) |
|
|
164
|
+
| The dose responds to past outcomes | 0.24 | **0.05** | 0.16 | 0.16 (not flat) |
|
|
165
|
+
|
|
166
|
+
A clearly non-flat placebo is a reason to prefer the lagged design, or to report both.
|
|
167
|
+
|
|
168
|
+
## Options worth knowing
|
|
169
|
+
|
|
170
|
+
- **Models.** `outcome_model=` and `gps=GPS(mean_model=..., scale_model=...)` take any sklearn
|
|
171
|
+
regressor. The default for each is `default_model()`.
|
|
172
|
+
- **Weights.** For a continuous dose the default is `GPS()`, density-based weights. `BalancingWeights()`
|
|
173
|
+
(entropy balancing; population curve only) is an alternative. A dose with ≤ 30 distinct values
|
|
174
|
+
(tiers, counts) uses `DiscreteGPS` automatically.
|
|
175
|
+
- **Uncertainty.** `band(simultaneous=False)` for pointwise bands; `draws()` for any other summary.
|
|
176
|
+
A group with no data (a new store) gets its parent's curve with a wider, predictive band that adds
|
|
177
|
+
the spread between groups (`predictive=True`, the default). The bands include the variance from
|
|
178
|
+
estimating m(a) (`nuisance_var=True`, Kennedy et al. 2017);
|
|
179
|
+
`bootstrap_curves()` refits the whole pipeline and is the only option that includes
|
|
180
|
+
nuisance-model uncertainty (slow). `coverage_check()` runs a plasmode simulation on your own data
|
|
181
|
+
to check how often the bands cover a known curve, and returns calibrated critical values.
|
|
182
|
+
- **Repeated units.** `fold_groups=` keeps a customer's rows in one cross-fitting fold; `cluster=`
|
|
183
|
+
makes the robust covariance types cluster-robust.
|
|
184
|
+
- **Inputs.** `X` may be a DataFrame (non-numeric columns are coded) and may contain missing values.
|
|
185
|
+
Errors and warnings flag mismatched lengths, a constant or missing dose, groups with fewer than
|
|
186
|
+
10 rows, a point mass in the dose, and poor overlap after fitting.
|
|
187
|
+
- **Speed.** About 45 s for 3,000 rows and 50 confounders on 2 cores; `n_jobs=-1` runs the
|
|
188
|
+
cross-fitting folds in parallel.
|
|
189
|
+
|
|
190
|
+
## When to use something else
|
|
191
|
+
|
|
192
|
+
- **One population curve, a few confounders, working in R:** [npcausal](https://github.com/ehkennedy/npcausal)
|
|
193
|
+
(Kennedy's own implementation) is close in accuracy.
|
|
194
|
+
- **Staggered adoption with a continuous dose:** [contdid](https://github.com/bcallaway11/contdid) (R) or
|
|
195
|
+
`diff_diff.ContinuousDiD` (Python).
|
|
196
|
+
- **You only need an average slope and trust linearity:** DoubleML's partially linear model.
|
|
197
|
+
- **Unmeasured confounders with no pre-period:** no estimator fixes this; you need a different design
|
|
198
|
+
(an instrument, a discontinuity or an experiment).
|
|
199
|
+
|
|
200
|
+
## How it compares
|
|
201
|
+
|
|
202
|
+
One population curve, 10 simulated datasets per setting. RMSE of the centred curve / share of doses
|
|
203
|
+
where the 95% band contains the truth.
|
|
204
|
+
|
|
205
|
+
| | 5 confounders | 50 confounders | Harder data |
|
|
206
|
+
|---|---|---|---|
|
|
207
|
+
| **drcurves**, default | **0.06** / 75% | **0.04** / 93% | **0.25** / 75% |
|
|
208
|
+
| drcurves, `BalancingWeights()` | 0.07 / 88% | 0.05 / 90% | 0.39 / 18% |
|
|
209
|
+
| [npcausal](https://github.com/ehkennedy/npcausal) (R) | 0.08 / 90% | 0.18 / 77% | 0.30 / 13% |
|
|
210
|
+
| [causal-curve](https://github.com/ronikobrosly/causal-curve) (Python) | 0.54 / 100% | 0.30 / 100% | 0.44 / 100% |
|
|
211
|
+
| drcurves with boosting alone | 0.19 / 94% | 3.43 / 87% | 3.07 / 97% |
|
|
212
|
+
|
|
213
|
+
The harder data has thresholds, interactions and heavy-tailed noise; there, boosting alone gave the
|
|
214
|
+
best outcome model (0.18 with balancing weights, but 43% coverage). No learner wins everywhere,
|
|
215
|
+
which is why the default stacks two. causal-curve's bands are 25+ times wider than the others'.
|
|
216
|
+
These are our simulations with each package's defaults; treat the ranking as indicative.
|
|
217
|
+
|
|
218
|
+
## How it works
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
1. cross-fit mu(x, a) = E[Y | X, A] and pi(a | x) (density of the dose given X)
|
|
222
|
+
2. pseudo-outcome xi = (Y - mu(X, A)) * varpi(A) / pi(A | X) + m(A)
|
|
223
|
+
3. regress xi on A with penalised splines:
|
|
224
|
+
theta_store(a) = B(a)' (beta_global + b_region + b_store)
|
|
225
|
+
ridge penalties on the deviations b shrink small groups toward their parent (tuned by GCV)
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
`varpi` is the marginal density of the dose and `m(a)` the outcome model averaged over X. The
|
|
229
|
+
pseudo-outcome's mean, given the dose, is the true curve if either nuisance model is right.
|
|
230
|
+
|
|
231
|
+
## Caveats
|
|
232
|
+
|
|
233
|
+
- Everything assumes the design you chose is right: unconfoundedness given X, or (strong) parallel
|
|
234
|
+
trends for DiD. Double robustness protects against a wrong model, not a missing variable.
|
|
235
|
+
- Report curves over the observed dose range. Weights are capped at the 99th percentile by default
|
|
236
|
+
(`max_weight_quantile`), trading a little bias for a lot of variance.
|
|
237
|
+
- The 95% bands are slightly optimistic: in our simulations they contained the true curve 75-93% of
|
|
238
|
+
the time (stores 81%), mostly because capping the weights leaves a small bias. Check with
|
|
239
|
+
`coverage_check` before relying on them; details on the [research page](https://raz1470.github.io/continuous-dr-learner/research.html).
|
|
240
|
+
- Experimental, not supported: `drcurves.riesz` (learned Riesz weights).
|
|
241
|
+
|
|
242
|
+
## Reproduce the article
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
pip install -e ".[experiments,dev]"
|
|
246
|
+
python experiments/sim1_nonlinear.py
|
|
247
|
+
python experiments/sim2_double_robustness.py 30
|
|
248
|
+
python experiments/sim3_hierarchical_shrinkage.py 5
|
|
249
|
+
python experiments/compare_causal_curve.py 10; python experiments/compare_npcausal.py 10 # npcausal needs R
|
|
250
|
+
python experiments/compare_stacked.py 10; python experiments/compare_hard.py 10
|
|
251
|
+
python experiments/sim_did.py 10; python experiments/sim_did.py 8 --past-outcome
|
|
252
|
+
python experiments/sim4_uncertainty.py single 42; python experiments/sim4_uncertainty.py stores 15
|
|
253
|
+
python experiments/sim6_intervals.py 15
|
|
254
|
+
python tools/build_article.py # -> article/index.html
|
|
255
|
+
pytest # add -m slow for the experimental tests
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Interval coverage studies are on the [research page](https://raz1470.github.io/continuous-dr-learner/research.html); the API is in the
|
|
259
|
+
[documentation](https://raz1470.github.io/continuous-dr-learner/api/index.html); open work is in [`BACKLOG.md`](https://github.com/raz1470/continuous-dr-learner/blob/main/BACKLOG.md).
|
|
260
|
+
|
|
261
|
+
## References
|
|
262
|
+
|
|
263
|
+
- Kennedy, Ma, McHugh & Small (2017). Non-parametric methods for doubly robust estimation of continuous treatment effects. *JRSS-B* 79(4).
|
|
264
|
+
- Callaway, Goodman-Bacon & Sant'Anna (2024). Difference-in-differences with a continuous treatment. arXiv:2107.02637.
|
|
265
|
+
- Chernozhukov et al. (2018). Double/debiased machine learning. *Econometrics Journal* 21(1).
|
|
266
|
+
- Valentin, Detommaso, Li, Opper & Brueckner (2025). On double robustness in double machine learning. NeurIPS 2025 Workshop CauScien.
|
|
267
|
+
- Tübbicke (2022). Entropy balancing for continuous treatments. *Journal of Econometric Methods* 11(1).
|
|
268
|
+
- Franklin, Schneeweiss, Polinski & Rassen (2014). Plasmode simulation for the evaluation of pharmacoepidemiologic methods. *CSDA* 72.
|
|
269
|
+
- Marra & Wood (2012). Coverage properties of confidence intervals for GAM components. *Scand. J. Statistics* 39(1).
|
|
270
|
+
- Eilers & Marx (1996). Flexible smoothing with B-splines and penalties. *Statistical Science* 11(2).
|
|
271
|
+
|
|
272
|
+
[MIT licence](https://github.com/raz1470/continuous-dr-learner/blob/main/LICENSE).
|
drcurves-0.1.0/README.md
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# drcurves
|
|
2
|
+
|
|
3
|
+
**Doubly robust dose-response curves for continuous treatments, for one population or many groups.**
|
|
4
|
+
|
|
5
|
+
How does the outcome change as the dose changes: discount depth and margin, handle time and
|
|
6
|
+
satisfaction, notifications per week and retention? `drcurves` estimates the whole curve, not one
|
|
7
|
+
slope, from observational data:
|
|
8
|
+
|
|
9
|
+
- **Doubly robust.** The curve stays close to the truth if either the outcome model or the dose
|
|
10
|
+
model is right (Kennedy et al. 2017).
|
|
11
|
+
- **Many curves at once.** A curve per store, product or customer issue, partially pooled across a
|
|
12
|
+
hierarchy (region → store), so small groups borrow strength from their parents.
|
|
13
|
+
- **Choose your assumption.** Adjust for measured confounders; or, with a pre-period outcome, use
|
|
14
|
+
difference-in-differences (`y_pre=`) when a stable trait you can't measure drives both the dose
|
|
15
|
+
and the outcome, or adjust for the lagged outcome (`design="lagged"`) when doses respond to past
|
|
16
|
+
outcomes. A placebo check tests the DiD assumption.
|
|
17
|
+
- **Sensible defaults.** Every nuisance model is a stack of a spline regression and gradient
|
|
18
|
+
boosting, which in our simulations beat boosting alone and the existing packages.
|
|
19
|
+
|
|
20
|
+
It accompanies the article *Estimating Continuous Treatment Effects: Doubly Robust Dose-Response
|
|
21
|
+
Curves*. Early release: the API may change before 1.0.
|
|
22
|
+
|
|
23
|
+
## Resources
|
|
24
|
+
|
|
25
|
+
| | |
|
|
26
|
+
|---|---|
|
|
27
|
+
| 📚 [Documentation](https://raz1470.github.io/continuous-dr-learner/) | User guide, examples and API reference |
|
|
28
|
+
| 📖 [Walkthrough](https://raz1470.github.io/continuous-dr-learner/walkthrough.html) | The article: why one slope isn't enough, and the method step by step on simulated data |
|
|
29
|
+
| 📓 [One curve](https://github.com/raz1470/continuous-dr-learner/blob/main/examples/01_one_curve.ipynb) | Fit with the defaults and read the results |
|
|
30
|
+
| 🏪 [Curves for many groups](https://github.com/raz1470/continuous-dr-learner/blob/main/examples/02_group_curves.ipynb) | A curve per store, pooled across regions |
|
|
31
|
+
| 🎯 [Checking the bands](https://raz1470.github.io/continuous-dr-learner/guide/checking_bands.html) | `coverage_check` on your own data |
|
|
32
|
+
| 🔬 [Research](https://raz1470.github.io/continuous-dr-learner/research.html) | How often the 95% bands contain the true curve |
|
|
33
|
+
| 📝 [Changelog](https://github.com/raz1470/continuous-dr-learner/blob/main/CHANGELOG.md) | What changed in each release |
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install drcurves
|
|
39
|
+
pip install "drcurves[plot]" # adds matplotlib for model.plot()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Quick start
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import numpy as np
|
|
46
|
+
from drcurves import fit_dose_response
|
|
47
|
+
from drcurves.simulate import sim_nonlinear
|
|
48
|
+
|
|
49
|
+
X, A, Y, truth = sim_nonlinear(n=3000, curve="inverted_u_centred", seed=1)
|
|
50
|
+
|
|
51
|
+
model = fit_dose_response(X, A, Y) # cross-fit, doubly robust, smooth curve
|
|
52
|
+
print(model.diagnostics()) # overlap and fit checks: read these first
|
|
53
|
+
|
|
54
|
+
grid = np.linspace(*np.quantile(A, [0.05, 0.95]), 50)
|
|
55
|
+
est, se = model.curve(grid) # curve and pointwise standard errors
|
|
56
|
+
est, lo, hi, _ = model.band(grid) # 95% band for the whole curve
|
|
57
|
+
lift, se = model.contrast(-1.0, 0.0) # effect of moving the dose from -1 to 0
|
|
58
|
+
best = model.optimal_dose(grid) # dose that maximises the outcome, with an interval
|
|
59
|
+
model.plot(truth=truth) # needs matplotlib
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Many groups
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from drcurves.simulate import sim_hierarchical
|
|
66
|
+
df, _, _ = sim_hierarchical(seed=0) # region, store, x0..x2, A, Y
|
|
67
|
+
|
|
68
|
+
model = fit_dose_response(df[["x0", "x1", "x2"]], df["A"], df["Y"],
|
|
69
|
+
groups=df[["region", "store"]]) # top -> bottom
|
|
70
|
+
store, se = model.curve(grid, ("r0", "r0_s03")) # a store's curve, shrunk toward its region
|
|
71
|
+
region, _ = model.curve(grid, ("r0",))
|
|
72
|
+
new, _ = model.curve(grid, ("r0", "unseen")) # a new store gets its region's curve
|
|
73
|
+
model.plot(paths=[("r0",), ("r0", "r0_s03")])
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
| Your data | `groups=` | What you get |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| One population | `None` | One curve |
|
|
79
|
+
| Groups, no hierarchy | `df[["store"]]` | One curve per store, shrunk toward the overall curve |
|
|
80
|
+
| Nested hierarchy | `df[["region", "store"]]` | Stores shrunk toward their region, regions toward the overall curve |
|
|
81
|
+
|
|
82
|
+
Levels must be nested; crossed groupings (store × channel) aren't supported. Shrinkage acts on each
|
|
83
|
+
group's shape; its overall level is left nearly free. `path=None` under partial pooling is a
|
|
84
|
+
"typical group" curve; for the population average, fit with `groups=None`.
|
|
85
|
+
|
|
86
|
+
## Choosing the assumption
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
# Measured confounders explain who got which dose (the default)
|
|
90
|
+
model = fit_dose_response(X, A, Y_post)
|
|
91
|
+
|
|
92
|
+
# A stable trait you can't measure drives dose and outcome: difference-in-differences
|
|
93
|
+
model = fit_dose_response(X, A, Y_post, y_pre=Y_pre)
|
|
94
|
+
|
|
95
|
+
# The dose responds to past outcomes: adjust for the lagged outcome instead
|
|
96
|
+
model = fit_dose_response(X, A, Y_post, y_pre=Y_pre, design="lagged")
|
|
97
|
+
|
|
98
|
+
# Placebo for DiD: the curve on two pre-periods should be flat. Judge it by size, not significance.
|
|
99
|
+
from drcurves import placebo_check
|
|
100
|
+
pc = placebo_check(X, A, Y_pre, Y_prepre, main=model)
|
|
101
|
+
pc["relative"] # largest placebo deviation / range of the real curve; small is good
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Comparing doses under DiD needs *strong* parallel trends: units on different doses would have
|
|
105
|
+
followed the same path had their doses been equal (Callaway, Goodman-Bacon & Sant'Anna 2024).
|
|
106
|
+
|
|
107
|
+
In simulation ([`experiments/sim_did.py`](https://github.com/raz1470/continuous-dr-learner/blob/main/experiments/sim_did.py)), each design wins in its own world, and the placebo tells
|
|
108
|
+
them apart (RMSE of the curve; placebo = largest deviation of the pre-period curve from flat):
|
|
109
|
+
|
|
110
|
+
| | Adjust for X | Lagged outcome | DiD | Placebo |
|
|
111
|
+
|---|---|---|---|---|
|
|
112
|
+
| A stable hidden trait drives the dose | 1.06 | 0.29 | **0.04** | 0.03 (flat) |
|
|
113
|
+
| The dose responds to past outcomes | 0.24 | **0.05** | 0.16 | 0.16 (not flat) |
|
|
114
|
+
|
|
115
|
+
A clearly non-flat placebo is a reason to prefer the lagged design, or to report both.
|
|
116
|
+
|
|
117
|
+
## Options worth knowing
|
|
118
|
+
|
|
119
|
+
- **Models.** `outcome_model=` and `gps=GPS(mean_model=..., scale_model=...)` take any sklearn
|
|
120
|
+
regressor. The default for each is `default_model()`.
|
|
121
|
+
- **Weights.** For a continuous dose the default is `GPS()`, density-based weights. `BalancingWeights()`
|
|
122
|
+
(entropy balancing; population curve only) is an alternative. A dose with ≤ 30 distinct values
|
|
123
|
+
(tiers, counts) uses `DiscreteGPS` automatically.
|
|
124
|
+
- **Uncertainty.** `band(simultaneous=False)` for pointwise bands; `draws()` for any other summary.
|
|
125
|
+
A group with no data (a new store) gets its parent's curve with a wider, predictive band that adds
|
|
126
|
+
the spread between groups (`predictive=True`, the default). The bands include the variance from
|
|
127
|
+
estimating m(a) (`nuisance_var=True`, Kennedy et al. 2017);
|
|
128
|
+
`bootstrap_curves()` refits the whole pipeline and is the only option that includes
|
|
129
|
+
nuisance-model uncertainty (slow). `coverage_check()` runs a plasmode simulation on your own data
|
|
130
|
+
to check how often the bands cover a known curve, and returns calibrated critical values.
|
|
131
|
+
- **Repeated units.** `fold_groups=` keeps a customer's rows in one cross-fitting fold; `cluster=`
|
|
132
|
+
makes the robust covariance types cluster-robust.
|
|
133
|
+
- **Inputs.** `X` may be a DataFrame (non-numeric columns are coded) and may contain missing values.
|
|
134
|
+
Errors and warnings flag mismatched lengths, a constant or missing dose, groups with fewer than
|
|
135
|
+
10 rows, a point mass in the dose, and poor overlap after fitting.
|
|
136
|
+
- **Speed.** About 45 s for 3,000 rows and 50 confounders on 2 cores; `n_jobs=-1` runs the
|
|
137
|
+
cross-fitting folds in parallel.
|
|
138
|
+
|
|
139
|
+
## When to use something else
|
|
140
|
+
|
|
141
|
+
- **One population curve, a few confounders, working in R:** [npcausal](https://github.com/ehkennedy/npcausal)
|
|
142
|
+
(Kennedy's own implementation) is close in accuracy.
|
|
143
|
+
- **Staggered adoption with a continuous dose:** [contdid](https://github.com/bcallaway11/contdid) (R) or
|
|
144
|
+
`diff_diff.ContinuousDiD` (Python).
|
|
145
|
+
- **You only need an average slope and trust linearity:** DoubleML's partially linear model.
|
|
146
|
+
- **Unmeasured confounders with no pre-period:** no estimator fixes this; you need a different design
|
|
147
|
+
(an instrument, a discontinuity or an experiment).
|
|
148
|
+
|
|
149
|
+
## How it compares
|
|
150
|
+
|
|
151
|
+
One population curve, 10 simulated datasets per setting. RMSE of the centred curve / share of doses
|
|
152
|
+
where the 95% band contains the truth.
|
|
153
|
+
|
|
154
|
+
| | 5 confounders | 50 confounders | Harder data |
|
|
155
|
+
|---|---|---|---|
|
|
156
|
+
| **drcurves**, default | **0.06** / 75% | **0.04** / 93% | **0.25** / 75% |
|
|
157
|
+
| drcurves, `BalancingWeights()` | 0.07 / 88% | 0.05 / 90% | 0.39 / 18% |
|
|
158
|
+
| [npcausal](https://github.com/ehkennedy/npcausal) (R) | 0.08 / 90% | 0.18 / 77% | 0.30 / 13% |
|
|
159
|
+
| [causal-curve](https://github.com/ronikobrosly/causal-curve) (Python) | 0.54 / 100% | 0.30 / 100% | 0.44 / 100% |
|
|
160
|
+
| drcurves with boosting alone | 0.19 / 94% | 3.43 / 87% | 3.07 / 97% |
|
|
161
|
+
|
|
162
|
+
The harder data has thresholds, interactions and heavy-tailed noise; there, boosting alone gave the
|
|
163
|
+
best outcome model (0.18 with balancing weights, but 43% coverage). No learner wins everywhere,
|
|
164
|
+
which is why the default stacks two. causal-curve's bands are 25+ times wider than the others'.
|
|
165
|
+
These are our simulations with each package's defaults; treat the ranking as indicative.
|
|
166
|
+
|
|
167
|
+
## How it works
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
1. cross-fit mu(x, a) = E[Y | X, A] and pi(a | x) (density of the dose given X)
|
|
171
|
+
2. pseudo-outcome xi = (Y - mu(X, A)) * varpi(A) / pi(A | X) + m(A)
|
|
172
|
+
3. regress xi on A with penalised splines:
|
|
173
|
+
theta_store(a) = B(a)' (beta_global + b_region + b_store)
|
|
174
|
+
ridge penalties on the deviations b shrink small groups toward their parent (tuned by GCV)
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
`varpi` is the marginal density of the dose and `m(a)` the outcome model averaged over X. The
|
|
178
|
+
pseudo-outcome's mean, given the dose, is the true curve if either nuisance model is right.
|
|
179
|
+
|
|
180
|
+
## Caveats
|
|
181
|
+
|
|
182
|
+
- Everything assumes the design you chose is right: unconfoundedness given X, or (strong) parallel
|
|
183
|
+
trends for DiD. Double robustness protects against a wrong model, not a missing variable.
|
|
184
|
+
- Report curves over the observed dose range. Weights are capped at the 99th percentile by default
|
|
185
|
+
(`max_weight_quantile`), trading a little bias for a lot of variance.
|
|
186
|
+
- The 95% bands are slightly optimistic: in our simulations they contained the true curve 75-93% of
|
|
187
|
+
the time (stores 81%), mostly because capping the weights leaves a small bias. Check with
|
|
188
|
+
`coverage_check` before relying on them; details on the [research page](https://raz1470.github.io/continuous-dr-learner/research.html).
|
|
189
|
+
- Experimental, not supported: `drcurves.riesz` (learned Riesz weights).
|
|
190
|
+
|
|
191
|
+
## Reproduce the article
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pip install -e ".[experiments,dev]"
|
|
195
|
+
python experiments/sim1_nonlinear.py
|
|
196
|
+
python experiments/sim2_double_robustness.py 30
|
|
197
|
+
python experiments/sim3_hierarchical_shrinkage.py 5
|
|
198
|
+
python experiments/compare_causal_curve.py 10; python experiments/compare_npcausal.py 10 # npcausal needs R
|
|
199
|
+
python experiments/compare_stacked.py 10; python experiments/compare_hard.py 10
|
|
200
|
+
python experiments/sim_did.py 10; python experiments/sim_did.py 8 --past-outcome
|
|
201
|
+
python experiments/sim4_uncertainty.py single 42; python experiments/sim4_uncertainty.py stores 15
|
|
202
|
+
python experiments/sim6_intervals.py 15
|
|
203
|
+
python tools/build_article.py # -> article/index.html
|
|
204
|
+
pytest # add -m slow for the experimental tests
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Interval coverage studies are on the [research page](https://raz1470.github.io/continuous-dr-learner/research.html); the API is in the
|
|
208
|
+
[documentation](https://raz1470.github.io/continuous-dr-learner/api/index.html); open work is in [`BACKLOG.md`](https://github.com/raz1470/continuous-dr-learner/blob/main/BACKLOG.md).
|
|
209
|
+
|
|
210
|
+
## References
|
|
211
|
+
|
|
212
|
+
- Kennedy, Ma, McHugh & Small (2017). Non-parametric methods for doubly robust estimation of continuous treatment effects. *JRSS-B* 79(4).
|
|
213
|
+
- Callaway, Goodman-Bacon & Sant'Anna (2024). Difference-in-differences with a continuous treatment. arXiv:2107.02637.
|
|
214
|
+
- Chernozhukov et al. (2018). Double/debiased machine learning. *Econometrics Journal* 21(1).
|
|
215
|
+
- Valentin, Detommaso, Li, Opper & Brueckner (2025). On double robustness in double machine learning. NeurIPS 2025 Workshop CauScien.
|
|
216
|
+
- Tübbicke (2022). Entropy balancing for continuous treatments. *Journal of Econometric Methods* 11(1).
|
|
217
|
+
- Franklin, Schneeweiss, Polinski & Rassen (2014). Plasmode simulation for the evaluation of pharmacoepidemiologic methods. *CSDA* 72.
|
|
218
|
+
- Marra & Wood (2012). Coverage properties of confidence intervals for GAM components. *Scand. J. Statistics* 39(1).
|
|
219
|
+
- Eilers & Marx (1996). Flexible smoothing with B-splines and penalties. *Statistical Science* 11(2).
|
|
220
|
+
|
|
221
|
+
[MIT licence](https://github.com/raz1470/continuous-dr-learner/blob/main/LICENSE).
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "drcurves"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Doubly robust, partially pooled dose-response curves for continuous treatments"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Ryan O'Sullivan" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"causal inference", "dose-response", "continuous treatment", "doubly robust",
|
|
16
|
+
"double machine learning", "hierarchical model", "partial pooling", "difference-in-differences",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 3 - Alpha",
|
|
20
|
+
"Intended Audience :: Science/Research",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3.10",
|
|
24
|
+
"Programming Language :: Python :: 3.11",
|
|
25
|
+
"Programming Language :: Python :: 3.12",
|
|
26
|
+
"Programming Language :: Python :: 3.13",
|
|
27
|
+
"Topic :: Scientific/Engineering :: Mathematics",
|
|
28
|
+
]
|
|
29
|
+
# Lower bounds are the oldest versions tested in CI (the "oldest" job in ci.yml).
|
|
30
|
+
dependencies = ["numpy>=1.23", "scipy>=1.8", "pandas>=1.5", "scikit-learn>=1.2"]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
plot = ["matplotlib>=3.5"]
|
|
34
|
+
experiments = ["doubleml>=0.9", "matplotlib>=3.5", "causal-curve", "playwright"]
|
|
35
|
+
dev = ["pytest", "ruff", "matplotlib>=3.5", "nbconvert", "ipykernel"]
|
|
36
|
+
docs = [
|
|
37
|
+
"sphinx>=7",
|
|
38
|
+
"pydata-sphinx-theme>=0.15",
|
|
39
|
+
"numpydoc>=1.6",
|
|
40
|
+
"myst-nb>=1.0",
|
|
41
|
+
"sphinx-copybutton>=0.5",
|
|
42
|
+
"matplotlib>=3.5",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[project.urls]
|
|
46
|
+
Homepage = "https://github.com/raz1470/continuous-dr-learner"
|
|
47
|
+
Documentation = "https://raz1470.github.io/continuous-dr-learner/"
|
|
48
|
+
Walkthrough = "https://raz1470.github.io/continuous-dr-learner/walkthrough.html"
|
|
49
|
+
Repository = "https://github.com/raz1470/continuous-dr-learner"
|
|
50
|
+
Issues = "https://github.com/raz1470/continuous-dr-learner/issues"
|
|
51
|
+
Changelog = "https://github.com/raz1470/continuous-dr-learner/blob/main/CHANGELOG.md"
|
|
52
|
+
|
|
53
|
+
[tool.setuptools.dynamic]
|
|
54
|
+
version = { attr = "drcurves.__version__" }
|
|
55
|
+
|
|
56
|
+
[tool.setuptools.packages.find]
|
|
57
|
+
where = ["src"]
|
|
58
|
+
|
|
59
|
+
[tool.pytest.ini_options]
|
|
60
|
+
pythonpath = ["src"]
|
|
61
|
+
markers = ["slow: long-running tests of experimental features (run with -m slow)"]
|
|
62
|
+
addopts = "-m 'not slow'"
|
|
63
|
+
|
|
64
|
+
[tool.ruff]
|
|
65
|
+
line-length = 110
|
|
66
|
+
extend-exclude = ["experiments", "tools/build_article.py", "tools/svg.py"]
|
|
67
|
+
|
|
68
|
+
[tool.ruff.lint]
|
|
69
|
+
# Errors only (syntax and pyflakes): style isn't enforced on this codebase.
|
|
70
|
+
select = ["E9", "F"]
|
drcurves-0.1.0/setup.cfg
ADDED