Plotting

pymgcv.plot provides plotting utilities for visualizing GAM models. Plotting is performed using matplotlib.

For an overall plot of the partial effects of a gam model, use plot_gam.
For more fine control over the plotting, specific terms can be plotted onto a single matplotlib axis, using the functions:

plot_gam

plot_gam(
    gam: AbstractGAM,
    *,
    ncols: int = 2,
    residuals: bool = False,
    to_plot: type | UnionType | dict[str, list[TermLike]] = TermLike,
    kwargs_mapper: dict[Callable, dict[str, Any]] | None = None,
) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes | numpy.ndarray]

Plot a gam model.

Parameters:

gam (AbstractGAM) –

The fitted gam object to plot.
ncols (int, default: 2 ) –

The number of columns before wrapping axes.
residuals (bool, default: False ) –

Whether to plot the residuals (where possible). Defaults to False.
to_plot (type | UnionType | dict[str, list[TermLike]], default: TermLike ) –

Which terms to plot. If a type, only plots terms of that type (e.g. to_plot = S | T to plot smooths). If a dictionary, it should map the target names to an iterable of terms to plot (similar to how models are specified).
kwargs_mapper (dict[Callable, dict[str, Any]] | None, default: None ) –
Used to pass keyword arguments to the underlying plot functions. A dictionary mapping the plotting function to kwargs. For example, to disable the confidence intervals on the 1d plots, set kwargs_mapper to
```
from pymgcv.plot import plot_continuous_1d
{plot_continuous_1d: {"fill_between_kwargs": {"disable": True}}}
```

plot_continuous_1d

plot_continuous_1d(
    *,
    target: str,
    term: TermLike,
    gam: AbstractGAM,
    data: DataFrame | None = None,
    eval_density: int = 100,
    level: str | None = None,
    n_standard_errors: int | float = 2,
    residuals: bool = False,
    plot_kwargs: dict[str, Any] | None = None,
    fill_between_kwargs: dict[str, Any] | None = None,
    scatter_kwargs: dict[str, Any] | None = None,
    ax: Axes | None = None,
) -> Axes

Plot 1D smooth or linear terms with confidence intervals.

Note

For terms with numeric "by" variables, the "by" variable is set to 1, showing the unscaled effect of the smooth.

Parameters:

target (str) –

Name of the response variable from the model specification.
term (TermLike) –

The model term to plot. Must be a univariate term (single variable).
gam (AbstractGAM) –

GAM model containing the term to plot.
data (DataFrame | None, default: None ) –

DataFrame used for plotting partial residuals and determining axis limits. Defaults to the data used for training.
eval_density (int, default: 100 ) –

Number of evaluation points along the variable range for plotting the smooth curve. Higher values give smoother curves but increase computation time. Default is 100.
level (str | None, default: None ) –

Must be provided for smooths with a categorical "by" variable or a RandomWigglyCurve basis. Specifies the level to plot.
n_standard_errors (int | float, default: 2 ) –

Number of standard errors for confidence intervals.
residuals (bool, default: False ) –

Whether to plot partial residuals.
plot_kwargs (dict[str, Any] | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.plot for the main curve.
fill_between_kwargs (dict[str, Any] | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.fill_between for the confidence interval band. Pass {"disable": True} to disable the confidence interval band.
scatter_kwargs (dict[str, Any] | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.scatter for partial residuals (ignored if residuals=False).
ax (Axes | None, default: None ) –

Matplotlib Axes object to plot on. If None, uses current axes.

Returns:

Axes –

The matplotlib Axes object with the plot.

plot_continuous_2d

plot_continuous_2d(
    *,
    target: str,
    term: TermLike,
    gam: AbstractGAM,
    data: DataFrame | None = None,
    eval_density: int = 50,
    level: str | None = None,
    contour_kwargs: dict | None = None,
    contourf_kwargs: dict | None = None,
    scatter_kwargs: dict | None = None,
    ax: Axes | None = None,
) -> Axes

Plot 2D smooth surfaces as contour plots with data overlay.

This function is essential for understanding bivariate relationships and interactions between two continuous variables.

Parameters:

target (str) –

Name of the response variable from the model specification.
term (TermLike) –

The bivariate term to plot. Must have exactly two variables. Can be S('x1', 'x2') or T('x1', 'x2').
gam (AbstractGAM) –

GAM model containing the term to plot.
data (DataFrame | None, default: None ) –

DataFrame containing the variables for determining plot range and showing data points. Should typically be the training data.
eval_density (int, default: 50 ) –

Number of evaluation points along each axis, creating an eval_density × eval_density grid. Higher values give smoother surfaces but increase computation time. Default is 50.
level (str | None, default: None ) –

Must be provided for smooths with a categorical "by" variable or a RandomWigglyCurve basis. Specifies the level to plot.
contour_kwargs (dict | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.contour for the contour lines.
contourf_kwargs (dict | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.contourf for the filled contours.
scatter_kwargs (dict | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.scatter for the data points overlay. Pass {"disable": True} to avoid plotting.
ax (Axes | None, default: None ) –

Matplotlib Axes object to plot on. If None, uses current axes.

Returns:

Axes –

The matplotlib Axes object with the plot, allowing further customization.

Raises:

ValueError –

If the term doesn't have exactly two variables.

plot_categorical

plot_categorical(
    *,
    target: str,
    term: L,
    gam: AbstractGAM,
    data: DataFrame | None = None,
    residuals: bool = False,
    n_standard_errors: int | float = 2,
    errorbar_kwargs: dict[str, Any] | None = None,
    scatter_kwargs: dict[str, Any] | None = None,
    ax: Axes | None = None,
) -> Axes

Plot categorical terms with error bars and partial residuals.

Creates a plot showing:

The estimated effect of each category level as points.
Error bars representing confidence intervals.
Partial residuals as jittered scatter points.

Parameters:

target (str) –

Name of the response variable from the model specification.
term (L) –

The categorical term to plot. Must be a L term with a single categorical variable.
gam (AbstractGAM) –

GAM model containing the term to plot.
data (DataFrame | None, default: None ) –

DataFrame containing the categorical variable and response.
residuals (bool, default: False ) –

Whether to plot partial residuals (jittered on x-axis).
n_standard_errors (int | float, default: 2 ) –

Number of standard errors for confidence intervals.
errorbar_kwargs (dict[str, Any] | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.errorbar.
scatter_kwargs (dict[str, Any] | None, default: None ) –

Keyword arguments passed to matplotlib.pyplot.scatter.
ax (Axes | None, default: None ) –

Matplotlib Axes object to plot on. If None, uses current axes.