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 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.
@@ -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).
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+