binscatter 0.3.1

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. Often we want more bins for a rawer look—use num_bins to specify the bin count:

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

See the demo notebook for more examples. This package implements binscatter following Cattaneo et al. (2024).

Tests

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