Examples

Synthetic Dose Example

from contdid import ContDIDSpec, PanelData
from contdid import estimate_dose_effects, simulate_contdid_data

frame = simulate_contdid_data(
    n=500,
    num_time_periods=2,
    num_groups=2,
    seed=1234,
)
panel = PanelData(frame=frame)
spec = ContDIDSpec(
    target_parameter="level",
    aggregation="dose",
    dose_est_method="parametric",
    control_group="nevertreated",
    bstrap=False,
)

result = estimate_dose_effects(panel, spec, degree=1, num_knots=0)
print(result.estimand)
print(result.grid[:3])
print(result.estimate[:3])

Worked Examples

The repository ships ready-to-run example scripts:

examples/plot_dose_curve.py
examples/medicare_release_walkthrough.py

The Medicare walkthrough uses a small scaffold panel that mirrors the Acemoglu-Finkelstein Medicare PPS application window. It must not be interpreted as a licensed replication of the original study.

Medicare Scaffold Walkthrough

The Medicare scaffold is the recommended real-world tutorial entry point. It mirrors the Acemoglu-Finkelstein Medicare PPS application window from the paper, using a small inspectable scaffold panel and noting the public-source boundary instead of claiming licensed 1980-1986 AHA replication.

The paper application uses AHA annual-survey hospital data for 1980-1986, fixes 1983 as the baseline year, and treats the 1983 Medicare inpatient share as the continuous dose. The public substitute source cms_hcris_hospital_cost_reports is labelled descriptive-or-scaffold-only because public HCRIS coverage starts in 1996. This means the scaffold can teach the package flow, but it is not licensed Medicare PPS replication evidence.

Use the package public API to inspect the source boundary before estimating:

import pandas as pd

from contdid import (
    ContDIDSpec,
    PanelData,
    estimate_eventstudy_effects,
    load_medicare_pps_source_options,
    prepare_medicare_pps_panel,
)

source_options = load_medicare_pps_source_options()
hcris = next(
    source for source in source_options["public_substitutes"]
    if source["id"] == "cms_hcris_hospital_cost_reports"
)
assert hcris["allowed_use"] == "descriptive-or-scaffold-only"
assert hcris["parity_claim_allowed"] is False

scaffold = pd.read_csv("data/medicare_scaffold/eventstudy_panel.csv")
prepared = prepare_medicare_pps_panel(
    scaffold,
    unit_column="id",
    year_column="time_period",
    outcome_column="Y",
    dose_column="D",
    source_id="cms_hcris_hospital_cost_reports",
)
assert prepared.metadata["allowed_use"] == "descriptive-or-scaffold-only"

spec = ContDIDSpec(
    target_parameter="level",
    aggregation="eventstudy",
    control_group="nevertreated",
    dose_est_method="parametric",
    bstrap=False,
)
result = estimate_eventstudy_effects(
    PanelData(scaffold),
    spec,
    degree=1,
    num_knots=0,
    base_period=1983,
)

display_table = result.to_frame()
print(display_table)

markdown_table = result.to_markdown(include_caption=True, digits=3)
print(markdown_table)

To generate output tables and figures, run:

python3 examples/medicare_release_walkthrough.py

That script writes Markdown and JSON output files while preserving the descriptive-or-scaffold-only label and the cms_hcris_hospital_cost_reports source boundary. Use ContDIDResult.to_frame() for notebook tables, ContDIDResult.to_markdown(include_caption=True, digits=3) for report-ready tables, and ContDIDResult.save_plot() for a PNG that draws the result axis, intervals, bands, zero lines, and event-study support markers. Do not relabel the scaffold as licensed Medicare PPS replication unless the licensed AHA 1980-1986 inputs are available.

The walkthrough JSON also keeps provenance inspectable for tutorial readers: source_surface identifies the data preparation function (prepare_medicare_pps_panel), while package_surfaces maps the public estimators used (estimate_dose_effects, estimate_dose_slope_effects, and estimate_eventstudy_effects). Inspect those fields as a provenance check before reusing the scaffold in another notebook or documentation page. Examples ========

Synthetic Dose Example

from contdid import ContDIDSpec, PanelData
from contdid import estimate_dose_effects, simulate_contdid_data

frame = simulate_contdid_data(
    n=500,
    num_time_periods=2,
    num_groups=2,
    seed=1234,
)
panel = PanelData(frame=frame)
spec = ContDIDSpec(
    target_parameter="level",
    aggregation="dose",
    dose_est_method="parametric",
    control_group="nevertreated",
    bstrap=False,
)

result = estimate_dose_effects(panel, spec, degree=1, num_knots=0)
print(result.estimand)
print(result.grid[:3])
print(result.estimate[:3])

Release Examples

The repository also ships checked release-example scripts:

examples/plot_dose_curve.py
examples/medicare_release_walkthrough.py

The Medicare walkthrough is an empirical scaffold unless licensed source data are available. It must not be interpreted as licensed application parity.

Real-world Medicare scaffold walkthrough

The checked Medicare scaffold is the recommended real-world tutorial entry point for release consumers. It mirrors the Acemoglu-Finkelstein Medicare PPS application window from the paper, but it deliberately uses a small checked scaffold and the public-source honesty boundary instead of claiming licensed 1980-1986 AHA parity.

The paper application uses AHA annual-survey hospital data for 1980-1986, fixes 1983 as the baseline year, and treats the 1983 Medicare inpatient share as the continuous dose. The checked public substitute registry records cms_hcris_hospital_cost_reports as descriptive-or-scaffold-only because public HCRIS coverage starts in 1996. Its parity_claim_allowed=False flag means the scaffold can teach the package flow, but it is not licensed Medicare PPS parity evidence.

The checked inputs are intentionally small and inspectable:

reproduction/phase9_release_examples/medicare-scaffold-demo/two_period_panel.csv
reproduction/phase9_release_examples/medicare-scaffold-demo/eventstudy_panel.csv
reproduction/phase9_release_examples/medicare-scaffold-demo/metadata.json
reproduction/medicare_pps/source_options.json

Use the package public API to inspect the source boundary before estimating:

import pandas as pd

from contdid import (
    ContDIDSpec,
    PanelData,
    estimate_eventstudy_effects,
    load_medicare_pps_source_options,
    prepare_medicare_pps_panel,
)

source_options = load_medicare_pps_source_options()
hcris = next(
    source for source in source_options["public_substitutes"]
    if source["id"] == "cms_hcris_hospital_cost_reports"
)
assert hcris["allowed_use"] == "descriptive-or-scaffold-only"
assert hcris["parity_claim_allowed"] is False

scaffold = pd.read_csv(
    "reproduction/phase9_release_examples/medicare-scaffold-demo/"
    "eventstudy_panel.csv"
)
prepared = prepare_medicare_pps_panel(
    scaffold,
    unit_column="id",
    year_column="time_period",
    outcome_column="Y",
    dose_column="D",
    source_id="cms_hcris_hospital_cost_reports",
)
assert prepared.metadata["allowed_use"] == "descriptive-or-scaffold-only"

spec = ContDIDSpec(
    target_parameter="level",
    aggregation="eventstudy",
    control_group="nevertreated",
    dose_est_method="parametric",
    bstrap=False,
)
result = estimate_eventstudy_effects(
    PanelData(scaffold),
    spec,
    degree=1,
    num_knots=0,
    base_period=1983,
)

display_table = result.to_frame()
print(display_table)

markdown_table = result.to_markdown(include_caption=True, digits=3)
print(markdown_table)

For docs-ready release outputs, run:

python3 examples/medicare_release_walkthrough.py

That script writes the checked Markdown and JSON consumer artifacts under reproduction/phase9_release_examples/consumer-outputs/ while preserving the descriptive-or-scaffold-only label and the cms_hcris_hospital_cost_reports source boundary. Use ContDIDResult.to_frame() for notebook tables, ContDIDResult.to_markdown(include_caption=True, digits=3) for docs-ready report tables, ContDIDResult.save_plot() for a checked PNG that draws the same result axis, intervals, bands, zero lines, and event-study support markers, and keep estimate_eventstudy_effects on the checked event-study route; do not relabel the scaffold as licensed Medicare PPS parity unless the licensed AHA 1980-1986 inputs are available and the parity contract is updated.

The checked walkthrough JSON also keeps the release route inspectable for tutorial readers: source_surface must stay prepare_medicare_pps_panel, while package_surfaces maps the public estimators used by the release packet (estimate_dose_effects, estimate_dose_slope_effects, and estimate_eventstudy_effects). Treat those fields as the tutorial provenance check before reusing the scaffold in another notebook or documentation page.