balance.stats_and_plots.love_plot

Love plot — visual covariate-imbalance diagnostic.

A “Love plot” (after Thomas Love) is the canonical visual for showing how much each covariate’s imbalance shrinks after applying weights. balance exposes a primitive (love_plot) operating on raw pd.Series inputs and a method shortcut (BalanceDFCovars.love_plot) that pulls the chosen metric off a fitted BalanceFrame’s lineage.

The primitive supports static seaborn output, plotly output, and ASCII text output. With both before and after it draws the canonical before-vs-after view; with only before it draws a single-series pre-adjust diagnostic.

balance.stats_and_plots.love_plot.love_plot(before: Series, after: Series | None = None, *, xlabel: str = 'ASMD', threshold: float | None = 0.1, ax: Axes | None = None, library: Literal['plotly', 'seaborn', 'balance'] = 'plotly', line: bool = False, order_by: Literal['before', 'after', 'diff', 'alphabetical', 'none'] = 'diff', show: bool = False, bar_width: int = 30, **layout_kwargs: Any) → Any[source]

Plot per-covariate imbalance, before vs. after weighting.

Parameters:

  • before – Per-covariate metric values before adjustment, or the only series to plot when after is None.

  • after – Per-covariate metric values after adjustment.

  • xlabel – Metric label for the x-axis and ASCII header.

  • threshold – Optional non-negative vertical/reference threshold. Pass None to skip it.

  • ax – Optional matplotlib Axes for library="seaborn".

  • library – One of "plotly" (default; interactive plotly.graph_objects.Figure), "seaborn" (static seaborn/matplotlib axes), or "balance" (ASCII string).

  • line – If True and both series are supplied, connect each before/after pair with a horizontal line.

  • order_by – Covariate sorting. "diff" (default) orders by signed after - before so the most-improved covariates are at the bottom and the most-worsened are at the top; "before" / "after" order by absolute pre / post values; "alphabetical" sorts by covariate name; "none" keeps input order.

  • show – For library="plotly", whether to call fig.show().

  • bar_width – Width of ASCII bars for library="balance".

  • **layout_kwargs – Additional Plotly layout options when library="plotly".

Returns:

matplotlib.axes.Axes for static output, plotly Figure for plotly output, or str for ASCII output.

Examples

>>> import pandas as pd
>>> from balance.stats_and_plots.love_plot import love_plot
>>> before = pd.Series({"age": 0.42, "income": 0.31})
>>> after = pd.Series({"age": 0.05, "income": 0.08})
>>> fig = love_plot(before, after)
>>> ax = love_plot(
...     before, after, library="seaborn", line=True
... )
>>> text = love_plot(
...     before, after, library="balance", line=True
... )