statspai.plots

plots

Visualization module for StatsPAI.

Provides publication-quality academic plots: - binscatter: Binned scatter plots with residualization (Cattaneo et al. 2024) - coefplot: Coefficient comparison forest plots - event_study_plot: DID event study (via CausalResult) - rdplot: RD visualization (via rd module) - marginsplot: Marginal effects (via postestimation) - interactive: Interactive plot editor with data protection

counterfactual_data

counterfactual_data(result: Any) -> DataFrame

Normalise a fitted result into a tidy counterfactual frame.

Parameters:

Name	Type	Description	Default
result	object	A StatsPAI result carrying an observed-vs-counterfactual time series: a sp.causal_impact result, any sp.synth family result, or an sp.its ITSResult.	required

Returns:

Type	Description
DataFrame	Columns time, observed, counterfactual, point_effect plus, when the result provides them, cf_lower, cf_upper, effect_lower, effect_upper, post, cumulative_effect.

Raises:

Type	Description
TypeError	If result does not expose a recognised counterfactual contract.

Examples:

>>> import statspai as sp
>>> res = sp.its(df, y="y", time="t", intervention=30)
>>> sp.counterfactual_data(res).columns.tolist()
['time', 'observed', 'counterfactual', 'point_effect', 'post', ...]

counterfactual_plot

counterfactual_plot(result: Any, *, ax: Any = None, figsize: Sequence[float] = (10.0, 7.0), bands: bool = True, show_effect: bool = True, title: Optional[str] = None) -> Any

Plot observed vs counterfactual with an uncertainty band.

The figure has a trajectory panel (observed solid, counterfactual dashed, shaded band, intervention marker) and, by default, a lower panel of the pointwise treatment effect with a zero reference line.

Parameters:

Name	Type	Description	Default
result	object	Any result supported by :func:counterfactual_data.	required
ax	Axes	Draw the trajectory panel into this axis instead of a new figure. When given, the effect panel is suppressed (single-axis mode).	None
figsize	sequence of float	Figure size when a new figure is created.	(10, 7)
bands	bool	Shade the counterfactual / effect uncertainty bands when available.	True
show_effect	bool	Add the lower pointwise-effect panel.	True
title	str	Figure title. Defaults to the result's method.	None

Returns:

Type	Description
Figure	The figure (or the parent figure of ax).

Examples:

>>> import statspai as sp
>>> res = sp.causal_impact(df, ...)
>>> fig = sp.counterfactual_plot(res)

set_theme

set_theme(name: str = 'academic', palette: Optional[str] = None, font_scale: float = 1.0) -> None

Set global matplotlib theme for publication-quality plots.

Supports three theme sources:

• StatsPAI: 'academic', 'aea', 'minimal', 'cn_journal'
• matplotlib: 'ggplot', 'fivethirtyeight', 'bmh', 'dark_background', 'grayscale', 'classic', etc.
• seaborn: 'seaborn-whitegrid', 'seaborn-darkgrid', 'seaborn-ticks', 'seaborn-paper', 'seaborn-talk', etc.

Parameters:

Name	Type	Description	Default
name	str	Theme name. Use list_themes() to see all available options. 'default' resets to matplotlib defaults.	'academic'
palette	str	Color palette name. Defaults to matching the theme. Only applies to StatsPAI themes.	None
font_scale	float	Scale factor for all font sizes.	1.0

Examples:

>>> import statspai as sp
>>> sp.set_theme('academic')          # clean serif, no top/right spines
>>> sp.set_theme('aea')               # AER journal specifications
>>> sp.set_theme('ggplot')            # R ggplot2 style
>>> sp.set_theme('seaborn-whitegrid') # seaborn white grid
>>> sp.set_theme('fivethirtyeight')   # FiveThirtyEight journalism style
>>> sp.set_theme('dark_background')   # dark theme for slides
>>> sp.set_theme('default')           # reset to matplotlib defaults

list_themes

list_themes() -> Dict[str, list]

List all available themes grouped by source.

Returns:

Type	Description
dict	Keys: 'statspai', 'matplotlib', 'seaborn'. Values: list of theme name strings.

Examples:

>>> import statspai as sp
>>> themes = sp.list_themes()
>>> themes['statspai']
['academic', 'aea', 'minimal', 'cn_journal']

use_chinese

use_chinese(style: str = 'auto') -> str

One-line fix for Chinese text rendering in matplotlib.

Call this before creating any plots. Automatically detects the best Chinese font on your system (macOS, Windows, Linux).

Parameters:

Name	Type	Description	Default
style	str	'auto': auto-detect the best available Chinese font 'serif': prefer serif fonts (宋体 Songti SC, SimSun) 'sans': prefer sans-serif fonts (苹方 PingFang, 黑体 SimHei) Any specific font name, e.g. 'Songti SC', 'SimHei'	'auto'

Returns:

Type	Description
str	The font name that was configured.

Examples:

>>> import statspai as sp
>>> sp.use_chinese()           # auto-detect best font
>>> sp.use_chinese('serif')    # prefer 宋体
>>> sp.use_chinese('sans')     # prefer 黑体/苹方
>>> sp.use_chinese('Kaiti SC') # use specific font