User Guide

Installation

Install the package with an editable install:

pip install -e .

Core Objects

PanelData wraps a balanced long panel and records the column names used by the runtime validators and estimators. The default columns are id, time_period, Y, G, and D.

ContDIDSpec records the requested estimand, aggregation, dose estimator, control group, and inference controls. The supported routes use continuous treatments and hard-fail unsupported treatment types or unsupported CCK/event-study combinations.

ContDIDResult stores the public result payload: estimand label, grid, estimate, standard error, optional critical value, confidence interval, confidence band, and metadata.

Display Tables and Plots

Use ContDIDResult.to_frame() when a notebook or downstream script needs a typed pandas.DataFrame. Use ContDIDResult.to_markdown() when a report, README, or release packet needs a compact table that can be pasted directly into Markdown. Pass boolean include_caption=True when the table should carry its own estimand, row count, axis, and critical value above the Markdown grid without printing the full metadata dictionary. Pass digits=3 or another integer from 0 through 12 when a manuscript table needs display-only rounding while the result object keeps the full stored estimates, standard errors, intervals, and metadata.

The Markdown table keeps the public display columns stable:

| Event time | Estimate | Std. error | Pointwise CI | Uniform band | Support |
| ---: | ---: | ---: | --- | --- | --- |
| -1 | -0.100000 | 0.200000 | [-0.500000, 0.300000] | not estimated (uniform band) | yes |
| 0 | 0.200000 | 0.100000 | [0.000000, 0.400000] | not estimated (uniform band) | yes |
| 1 | 0.500000 | 0.300000 | [0.100000, 0.900000] | not estimated (uniform band) | no |

The numeric cells use fixed six-decimal formatting by default, confidence intervals and uniform confidence bands are bracketed when present, and event-study support is rendered with yes/no event-study support labels.

Use ContDIDResult.save_plot() when a report or notebook needs a publication-style PNG directly from the checked result object. The plot uses the same dose or event_time axis as to_frame(), renders exported pointwise confidence intervals and uniform confidence bands when available, marks the zero reference line, and shows event-study support diagnostics when the result carries support metadata. The method writes only PNG output and returns the saved pathlib.Path.

Real-World Tutorial Provenance

The Medicare scaffold tutorial is descriptive-or-scaffold-only. Before reusing it in a notebook, inspect the walkthrough JSON output: source_surface must remain prepare_medicare_pps_panel and package_surfaces must point to the public estimators used by the example. Those fields keep the data-preparation step separate from the estimator calls, so the tutorial cannot be mistaken for licensed Medicare PPS replication evidence.

Supported Public Routes

The public API exposes:

  • simulate_contdid_data for synthetic panels.

  • estimate_dose_effects and estimate_dose_level_effects for ATT(d).

  • estimate_dose_slope_effects for ACRT(d).

  • estimate_eventstudy_effects for ATT(event_time).

  • estimate_eventstudy_slope_effects for ACRT(event_time).

  • build_confidence_band and compute_multiplier_bootstrap for inference payload construction.

CCK Boundary

The checked CCK dose route is deliberately narrow. It is only supported for aggregation="dose" with two observed time periods, one positive treatment-timing cohort, positive treatment timing to start in the post period, and an untreated D == 0 benchmark. Requests outside that shape hard-fail instead of falling through to an unchecked approximation.

The error messages are part of the documented boundary conditions. Staggered-adoption CCK requests raise cck estimator not supported with staggered adoption yet before the generic multi-period or event-study guards. CCK event-study requests raise event study not supported with cck estimator yet; base_period and control_group options must not relax that boundary. The supported event-study control groups are notyettreated and nevertreated for the parametric event-study routes.

The runtime CCK backend is a fixed quadratic polynomial scaffold used for the supported two-period dose surface. It does not implement the paper’s data-driven K-hat, Lepski, or npiv sieve selection, so it must not be described as full adaptive CCK. Event-study inference also requires locally identified post-treatment support with inference degrees of freedom before reporting uncertainty.

Data Rules

Real-world datasets used for cross-checks or regression tests should be placed under the repository-level data/ directory with source, license, and usage notes. Synthetic fixtures and generated Monte Carlo outputs may remain with their test or reproduction bundles.