Metadata-Version: 2.4
Name: dml-plotting
Version: 0.1.6
Summary: Plotting utilities for comparing event-study estimates across estimators.
Author: Corey Gelb-Bicknell
License-Expression: MIT
Project-URL: Homepage, https://github.com/coreygb1/2604_aipw
Project-URL: Repository, https://github.com/coreygb1/2604_aipw
Project-URL: Issues, https://github.com/coreygb1/2604_aipw/issues
Keywords: economics,event-study,plotting,causal-inference,dml,aipw
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: oi-tools>=0.8.0
Dynamic: license-file

# 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

```bash
pip install dml-plotting
```

## Quick Start

```python
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:

```python
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.

```python
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:

```bash
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

```bash
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:

```bash
git tag v0.1.5
git push origin v0.1.5
```
