binscatter 0.3.0

Cross-backend binscatter plots.

Dataframe agnostic binscatter plots

TL;DR: Fast binscatter plots for all kinds of dataframes.

• Built on the narwhals dataframe abstraction, so pandas, Polars, DuckDB, Dask, and PySpark inputs all work out of the box.
• Uses plotly as graphics backend - because: (1) it's great (2) it uses narwhals as well, minimizing dependencies
• Lightweight - little dependencies
• Just works: by default picks the number of bins automatically via the DPI (Direct Plug-In) selector from Cattaneo et al. (2024) - no manual tuning

What are binscatter plots?

Binscatter plots group the x-axis into bins and plot average outcomes for each bin, giving a cleaner view of the relationship between two variables—possibly controlling for confounders. They show an estimate of the conditional mean, rather than all the underlying data as in a classical scatter plot.

Installation

pip install binscatter

---

Example

import plotly.express as px
from binscatter import binscatter

df = px.data.gapminder()
binscatter(df, "gdpPercap", "lifeExp")

By default binscatter chooses bins via the DPI (Direct Plug-In) selector; when you want more bins, override via num_bins.

binscatter(df, "gdpPercap", "lifeExp", num_bins=120)

This package implements binscatter plots following:

• Cattaneo, Matias D.; Crump, Richard K.; Farrell, Max H.; Feng, Yingjie (2024), “On Binscatter,” American Economic Review, 114(5), 1488–1514. DOI: 10.1257/aer.20221576

Tests

• Run the full backend matrix, including PySpark: just test
• Use the faster run without PySpark: just ftest