Plotting

The primary plotting entry point is SuperGLM.plot(). The standalone functions below are the underlying renderers and can be used directly with TermInference objects for advanced customization.

For the public API, engine="matplotlib" is the chart/export path, while engine="plotly" is the interactive multi-term main-effect explorer path. Single-term main effects should use matplotlib.

Use SuperGLM.plot_data() when you want the plain effect / density / grid data needed to recreate charts in your own plotting stack.

Grouped categorical levels

Grouped categorical levels can be drawn as one visual group without changing the model rows used for scoring, inference tables, or exports:

model.plot("age_band", grouped_level_display="auto")
model.plot("age_band", grouped_level_display="expanded")
model.plot("age_band", grouped_level_display="collapsed")

"auto" collapses grouped ordered-categorical terms and leaves unordered categoricals expanded. Collapsed exposure bars sum the original member levels.

plot_term(ti, *, model=None, X=None, sample_weight=None, interval='pointwise', show_exposure=True, show_knots=False, figsize=None, title=None, subtitle=None, grouped_level_display='auto')

Plot a single term's relativity.

This is the core single-term plotting function. All term types (spline, polynomial, numeric, categorical) are handled.

Parameters:

Name	Type	Description	Default
ti	TermInference	Inference result from :meth:SuperGLM.term_inference.	required
X	pandas or eager Polars DataFrame	Training data for sample_weight overlays.	None
sample_weight	array - like	Exposure / frequency weights.	None
interval	('pointwise', 'simultaneous', 'both', None)	Band style. For categoricals, simultaneous/both fall back to pointwise.	"pointwise"
show_exposure	bool	Show sample_weight distribution (density strip for continuous, vertical bars for categorical).	True
show_knots	bool	Show interior knot ticks (spline only).	False
figsize	tuple	Figure size.	None
title	str	Title and subtitle.	None
subtitle	str	Title and subtitle.	None

Returns:

Type	Description
Figure

plot_relativities(terms, *, model=None, X=None, sample_weight=None, ncols=2, figsize=None, with_ci=True, interval='pointwise', show_exposure=True, show_knots=False, title=None, subtitle=None, grouped_level_display='auto')

Create a grid of relativity plots from TermInference objects.

Parameters:

Name	Type	Description	Default
terms	list[TermInference]	Per-term inference objects from :meth:SuperGLM.term_inference.	required
X	pandas or eager Polars DataFrame	Training data for sample_weight density overlays.	None
sample_weight	array - like	Exposure / frequency weights.	None
sample_weight	array - like	Alias for sample_weight.	None
ncols	int	Number of subplot columns (default 2).	2
figsize	tuple	Figure size. Auto-sized if None.	None
with_ci	bool	When False, forces interval=None (no bands).	True
interval	('pointwise', 'simultaneous', 'both', None)	"pointwise": orange CI band only. "simultaneous": blue simultaneous band only. "both": nested (simultaneous outside, pointwise inside). None: no uncertainty bands. For categorical/numeric terms, "simultaneous" and "both" silently fall back to pointwise CI.	"pointwise"
show_exposure	bool	Show sample_weight density strip below continuous panels (default True).	True
show_knots	bool	Show interior knot positions as minor x-axis ticks (default False).	False
title	str	Figure-level title and subtitle.	None
subtitle	str	Figure-level title and subtitle.	None

Returns:

Type	Description
Figure

plot_interaction(model, name, *, engine='matplotlib', with_ci=True, figsize=None, colormap=None, show_contours=True, n_points=200, interaction_view='surface', surface_opacity=0.96, show_main_effect_walls=False, X=None, sample_weight=None)

Plot an interaction surface/effect.

Parameters:

Name	Type	Description	Default
model	SuperGLM	A fitted model with the named interaction.	required
name	str	Interaction name, e.g. "DrivAge:Area".	required
engine	('matplotlib', 'plotly')	Plotting backend. "plotly" requires plotly to be installed.	"matplotlib"
with_ci	bool	Show confidence bands where applicable (varying-coefficient only).	True
figsize	tuple	Figure size for matplotlib.	None
colormap	str	Colormap / colorscale name.	None
show_contours	bool	For surface plots: show iso-relativity contour lines on the surface (default True).	True
n_points	int	Grid resolution for interaction curves/surfaces. For surface plots this produces an n_points x n_points evaluation grid.	200
interaction_view	('surface', 'contour', 'contour_pair')	Plotly view for continuous x continuous interactions. "surface" (default) returns the 3D surface. "contour" returns a 2D contour map. "contour_pair" returns a two-panel figure with the interaction contour and an exposure HDR-mass contour view. Ignored by matplotlib and non-surface interaction types.	"surface"
surface_opacity	float	Opacity for Plotly 3D surface interactions (default 0.96). Ignored by other interaction plot types and the matplotlib backend.	0.96
show_main_effect_walls	bool	For Plotly 3D surface plots: project parent main-effect curves on the surface walls (default False).	False
X	pandas or eager Polars DataFrame	Training data. When provided with sample_weight, overlays an sample_weight-weighted density on surface plots (projected on the floor for 3D plotly, contour overlay for matplotlib).	None
sample_weight	array - like	Exposure weights corresponding to rows of X.	None

Returns:

Type	Description
Figure or Figure

Diagnostic plots

See Diagnostics for plot_diagnostics() — the GLM/GAM 4-panel diagnostic figure with simulation-based Q-Q envelopes.