dml-plotting 0.1.6

Plotting utilities for comparing event-study estimates across estimators.

dml-plotting

dml-plotting provides lightweight plotting utilities for comparing event-study estimates across estimators, including support for publication-style line plots with optional confidence bands.

Install

pip install dml-plotting

Quick Start

from dml_plotting import example_event_study_input, plot_event_study

plot_event_study(
    example_event_study_input(),
    output_path="event_study.png",
    title="ERA pooled ATT event-study estimates across estimators",
    y_limits=(0.05, 0.05),
)

To add confidence bands and a caption:

from dml_plotting import example_event_study_input, plot_event_study

plot_event_study(
    example_event_study_input(),
    output_path="event_study_with_ci.png",
    title="ERA pooled ATT event-study estimates across estimators",
    caption="Confidence bands show 95 percent intervals around each series.",
    show_confidence_bands=True,
    y_limits=(0.05, 0.05),
)

Control-Group Size Plotter

Use ControlGroupSizePoint for each observed run, then pass three cumulative covariate panels to plot_control_group_size_tradeoffs_grid(). The control group sample-size axis is log-scaled and defaults to running from 1,000 through 1 billion people.

from dml_plotting import (
    ControlGroupSizePanel,
    ControlGroupSizePoint,
    SQRT_ASYMPTOTIC,
    XLOGX,
    plot_control_group_size_tradeoffs_grid,
)

fit_specs = {
    "runtime_minutes": XLOGX,
    "outcome_mse": XLOGX,
    "pooled_att_estimate": SQRT_ASYMPTOTIC,
}

basic_points = [
    ControlGroupSizePoint(20, outcome_mse=0.99, runtime_minutes=3.2, pooled_att_estimate=-2900),
    ControlGroupSizePoint(40, outcome_mse=0.81, runtime_minutes=7.4, pooled_att_estimate=-1850),
    ControlGroupSizePoint(80, outcome_mse=0.65, runtime_minutes=17.5, pooled_att_estimate=-950),
]

panels = [
    ControlGroupSizePanel("Basic covariates", basic_points, feature_count=42, fit_specs=fit_specs),
    ControlGroupSizePanel("Basic + county indicators", basic_points, feature_count=96, fit_specs=fit_specs),
    ControlGroupSizePanel("Basic + county + tract characteristics", basic_points, feature_count=178, fit_specs=fit_specs),
]

plot_control_group_size_tradeoffs_grid(
    panels,
    output_path="control_group_size_grid.png",
    title="DoubleML runtime and performance: Low-complexity LightGBM models on ERA data",
    footnote="LightGBM parameters: num_leaves=31, learning_rate=0.05, n_estimators=250.",
    x_limits=(1_000, 100_000_000),
    show_fit_lines={"outcome_mse": False},
    y_axis_limits={
        "runtime_minutes": (0, 600),
        "outcome_mse": (0.4, 1.05),
        "pooled_att_estimate": (-3200, 100),
    },
)

colors and show_fit_lines accept any subset of runtime_minutes, outcome_mse, and pooled_att_estimate. By default, runtime uses OI navy, outcome-model MSE uses OI red, and pooled ATT uses OI blue.

For a quick smoke test with bundled example data:

python -m dml_plotting.examples

This writes example images to dist/control_group_size_plot_examples/.

The former aipw_analysis import path is still available as a compatibility alias in this package.

Public API

• EventStudySeries: dataclass for one event-study series
• plot_event_study(): save a multi-series event-study figure
• ControlGroupSizePoint: dataclass for one runtime/performance run
• ControlGroupSizePanel: dataclass for one covariate-specification panel
• plot_control_group_size_tradeoffs_grid(): save the 2x3 control-group-size figure
• example_event_study_input(): generate example plotting inputs

Development

source .venv/bin/activate
python -m pip install -e . --no-build-isolation
python -m build --no-isolation
python -m twine check dist/*

Publishing

This repo includes GitHub Actions trusted publishing in .github/workflows/publish.yml. Publishing is triggered by pushing a tag like:

git tag v0.1.5
git push origin v0.1.5