Skip to content

Coefficient and diagnostic surfaces

This page documents 5 public symbols. Each entry includes its purpose, import path, full API docstring, and the maintained example that exercises it.

Conceptual guide

plot_coefficient_map

Plot one fitted local coefficient surface.

Property Value
Type function
Import from pygwrx.plotting import plot_coefficient_map
Signature plot_coefficient_map(model: 'Any', feature: 'Any', *, geometry: 'Any' = None, significance: 'Optional[str]' = None, alpha: 'float' = 0.05, theme: 'str' = 'default', ax: 'Optional[plt.Axes]' = None, figsize: 'Optional[Tuple[float, float]]' = None, cmap: 'Optional[str]' = None, vmin: 'Optional[float]' = None, vmax: 'Optional[float]' = None, marker_size: 'float' = 45.0, title: 'Optional[str]' = None) -> 'Tuple[plt.Figure, plt.Axes]'
Maintained example examples/plotting/01_surfaces_and_arrays.py

plot_coefficient_map 

plot_coefficient_map(
    model: Any,
    feature: Any,
    *,
    geometry: Any = None,
    significance: Optional[str] = None,
    alpha: float = 0.05,
    theme: str = "default",
    ax: Optional[Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    marker_size: float = 45.0,
    title: Optional[str] = None
) -> Tuple[plt.Figure, plt.Axes]

Plot one fitted local coefficient surface.

Parameters:

Name Type Description Default
model Any

Fitted pyGWRx regression model.

 required
feature Any

Feature name, zero-based coefficient index, or "intercept".

 required
geometry Any

Optional GeoDataFrame or GeoSeries aligned to calibration rows.

 None
significance Optional[str]

Optional correction method: adjusted, raw, bonferroni, bh, or by. Non-significant locations are grey.

 None
alpha float

Significance level.

 0.05
theme str

Plotting theme.

 'default'
ax Optional[Axes]

Existing axis.

 None
figsize Optional[Tuple[float, float]]

Figure size when ax is not supplied.

 None
cmap Optional[str]

Matplotlib colormap.

 None
vmin Optional[float]

Shared lower colour limit.

 None
vmax Optional[float]

Shared upper colour limit.

 None
marker_size float

Point size for coordinate maps.

 45.0
title Optional[str]

Optional title.

 None

Returns:

Type Description
Tuple[Figure, Axes]

Matplotlib (figure, axis).
Source code in src/pygwrx/plotting/surfaces.py 
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def plot_coefficient_map(
    model: Any,
    feature: Any,
    *,
    geometry: Any = None,
    significance: Optional[str] = None,
    alpha: float = 0.05,
    theme: str = "default",
    ax: Optional[plt.Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    marker_size: float = 45.0,
    title: Optional[str] = None,
) -> Tuple[plt.Figure, plt.Axes]:
    """Plot one fitted local coefficient surface.

    Args:
        model: Fitted pyGWRx regression model.
        feature: Feature name, zero-based coefficient index, or ``"intercept"``.
        geometry: Optional GeoDataFrame or GeoSeries aligned to calibration rows.
        significance: Optional correction method: ``adjusted``, ``raw``,
            ``bonferroni``, ``bh``, or ``by``. Non-significant locations are grey.
        alpha: Significance level.
        theme: Plotting theme.
        ax: Existing axis.
        figsize: Figure size when ``ax`` is not supplied.
        cmap: Matplotlib colormap.
        vmin: Shared lower colour limit.
        vmax: Shared upper colour limit.
        marker_size: Point size for coordinate maps.
        title: Optional title.

    Returns:
        Matplotlib ``(figure, axis)``.
    """
    with plotting_theme(theme):
        fig, axis = _figure_ax(ax, figsize, theme)
        view = parameter_view(model, feature)
        mask = None
        suffix = ""
        if significance is not None:
            mask, _, threshold = significance_mask(
                model, feature, alpha=alpha, correction=significance
            )
            suffix = f"; {significance} significance, α={alpha:g}"
        cmap_name, norm = resolve_color_scale(
            view.values, center_zero=None, vmin=vmin, vmax=vmax, cmap=cmap
        )
        artist = render_spatial_values(
            axis,
            view.values,
            coords=model_coords(model),
            geometry=geometry,
            cmap=cmap_name,
            norm=norm,
            mask=mask,
            marker_size=marker_size,
        )
        add_colorbar(fig, axis, artist, f"Coefficient: {view.label}")
        axis.set_title(title or f"{model.__class__.__name__}: {view.label}{suffix}")
        fig.tight_layout()
        return fig, axis

plot_significance_map

Dispatch to model-aware or historical array-based significance mapping.

Property Value
Type function
Import from pygwrx.plotting import plot_significance_map
Signature plot_significance_map(first, *args, **kwargs)
Maintained example examples/plotting/01_surfaces_and_arrays.py

plot_significance_map 

plot_significance_map(first, *args, **kwargs)

Dispatch to model-aware or historical array-based significance mapping.

Source code in src/pygwrx/plotting/__init__.py 
103
104
105
106
107
def plot_significance_map(first, *args, **kwargs):
    """Dispatch to model-aware or historical array-based significance mapping."""
    if hasattr(first, "coef_"):
        return _plot_model_significance_map(first, *args, **kwargs)
    return plot_array_significance_map(first, *args, **kwargs)

plot_model_significance_map

Map negative-significant, non-significant, and positive-significant areas.

Property Value
Type function
Import from pygwrx.plotting import plot_model_significance_map
Signature plot_model_significance_map(model, feature, *, geometry=None, correction: 'str' = 'adjusted', alpha: 'float' = 0.05, theme: 'str' = 'default', ax: 'Optional[plt.Axes]' = None, figsize: 'Optional[Tuple[float, float]]' = None, marker_size: 'float' = 45.0, title: 'Optional[str]' = None)
Maintained example examples/plotting/01_surfaces_and_arrays.py

plot_model_significance_map module-attribute 

plot_model_significance_map = _plot_model_significance_map

plot_local_diagnostic_map

Plot a fitted local diagnostic such as Local R² or Cook's distance.

Property Value
Type function
Import from pygwrx.plotting import plot_local_diagnostic_map
Signature plot_local_diagnostic_map(model, metric: 'str', *, geometry=None, theme: 'str' = 'default', ax: 'Optional[plt.Axes]' = None, figsize: 'Optional[Tuple[float, float]]' = None, cmap: 'Optional[str]' = None, vmin: 'Optional[float]' = None, vmax: 'Optional[float]' = None, marker_size: 'float' = 45.0, title: 'Optional[str]' = None)
Maintained example examples/plotting/01_surfaces_and_arrays.py

plot_local_diagnostic_map 

plot_local_diagnostic_map(
    model,
    metric: str,
    *,
    geometry=None,
    theme: str = "default",
    ax: Optional[Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    marker_size: float = 45.0,
    title: Optional[str] = None
)

Plot a fitted local diagnostic such as Local R² or Cook's distance.

Source code in src/pygwrx/plotting/surfaces.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def plot_local_diagnostic_map(
    model,
    metric: str,
    *,
    geometry=None,
    theme: str = "default",
    ax: Optional[plt.Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    marker_size: float = 45.0,
    title: Optional[str] = None,
):
    """Plot a fitted local diagnostic such as Local R² or Cook's distance."""
    with plotting_theme(theme):
        fig, axis = _figure_ax(ax, figsize, theme)
        values, label, center_zero = diagnostic_values(model, metric)
        cmap_name, norm = resolve_color_scale(
            values,
            center_zero=center_zero,
            vmin=vmin,
            vmax=vmax,
            cmap=cmap,
        )
        artist = render_spatial_values(
            axis,
            values,
            coords=model_coords(model),
            geometry=geometry,
            cmap=cmap_name,
            norm=norm,
            marker_size=marker_size,
        )
        add_colorbar(fig, axis, artist, label)
        axis.set_title(title or f"{model.__class__.__name__}: {label}")
        fig.tight_layout()
        return fig, axis

plot_local_collinearity

Plot local condition numbers or LCR-GWR ridge compensation.

Property Value
Type function
Import from pygwrx.plotting import plot_local_collinearity
Signature plot_local_collinearity(model, metric: 'str' = 'condition_number', *, geometry=None, theme: 'str' = 'default', ax: 'Optional[plt.Axes]' = None, figsize: 'Optional[Tuple[float, float]]' = None, cmap: 'str' = 'magma', marker_size: 'float' = 45.0, show_threshold: 'bool' = True, title: 'Optional[str]' = None)
Maintained example examples/plotting/02_diagnostics_and_comparison.py

plot_local_collinearity 

plot_local_collinearity(
    model,
    metric: str = "condition_number",
    *,
    geometry=None,
    theme: str = "default",
    ax: Optional[Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: str = "magma",
    marker_size: float = 45.0,
    show_threshold: bool = True,
    title: Optional[str] = None
)

Plot local condition numbers or LCR-GWR ridge compensation.

Source code in src/pygwrx/plotting/surfaces.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def plot_local_collinearity(
    model,
    metric: str = "condition_number",
    *,
    geometry=None,
    theme: str = "default",
    ax: Optional[plt.Axes] = None,
    figsize: Optional[Tuple[float, float]] = None,
    cmap: str = "magma",
    marker_size: float = 45.0,
    show_threshold: bool = True,
    title: Optional[str] = None,
):
    """Plot local condition numbers or LCR-GWR ridge compensation."""
    with plotting_theme(theme):
        fig, axis = _figure_ax(ax, figsize, theme)
        values, label, threshold = collinearity_values(model, metric)
        cmap_name, norm = resolve_color_scale(values, center_zero=False, cmap=cmap)
        artist = render_spatial_values(
            axis,
            values,
            coords=model_coords(model),
            geometry=geometry,
            cmap=cmap_name,
            norm=norm,
            marker_size=marker_size,
        )
        add_colorbar(fig, axis, artist, label)
        if show_threshold and threshold is not None:
            count = int(np.sum(values > threshold))
            axis.text(
                0.02,
                0.02,
                f"> {threshold:g}: {count}/{values.size}",
                transform=axis.transAxes,
                ha="left",
                va="bottom",
                bbox={"facecolor": "white", "edgecolor": "0.5", "alpha": 0.85},
            )
        axis.set_title(title or f"{model.__class__.__name__}: {label}")
        fig.tight_layout()
        return fig, axis

Runnable examples used on this page

examples/plotting/01_surfaces_and_arrays.py 
# SPDX-FileCopyrightText: 2026 Jinghao Hu
# SPDX-License-Identifier: MIT

"""Model-aware coefficient maps plus all historical array-based maps."""

# Allow this script to run directly from any working directory.
import sys
from pathlib import Path

_PROJECT_ROOT = Path(__file__).resolve().parents[2]
_EXAMPLES_ROOT = _PROJECT_ROOT / "examples"
_SRC_ROOT = _PROJECT_ROOT / "src"
for _path in (_SRC_ROOT, _EXAMPLES_ROOT):
    if str(_path) not in sys.path:
        sys.path.insert(0, str(_path))

import matplotlib

matplotlib.use("Agg", force=True)
import geopandas as gpd
import numpy as np
from _common import save_plot
from _models import surface_models
from shapely.geometry import Point

from pygwrx.plotting import (
    create_choropleth,
    plot_array_significance_map,
    plot_bandwidth,
    plot_coefficient_map,
    plot_coefficient_surface,
    plot_local_coefficients,
    plot_local_diagnostic_map,
    plot_local_r2,
    plot_model_significance_map,
    plot_multiple_coefficients,
    plot_significance_map,
)

X, y, coords, gwr, _, _ = surface_models()
coords_array = coords.to_numpy()
p_values = np.full_like(gwr.coef_, 0.02)
plots = {
    "coefficient_map.png": plot_coefficient_map(gwr, "x1", theme="paper"),
    "model_significance.png": plot_model_significance_map(gwr, "x1", correction="raw"),
    "dispatch_model_significance.png": plot_significance_map(gwr, "x1"),
    "local_diagnostic.png": plot_local_diagnostic_map(gwr, "local_r2"),
    "array_significance.png": plot_array_significance_map(
        coords_array, p_values, feature_idx=0, coefficients=gwr.coef_
    ),
    "dispatch_array_significance.png": plot_significance_map(
        coords_array, p_values, feature_idx=0, coefficients=gwr.coef_
    ),
    "local_coefficients.png": plot_local_coefficients(coords_array, gwr.coef_, 0, "x1"),
    "coefficient_surface.png": plot_coefficient_surface(
        coords_array, gwr.coef_, 0, interpolation="nearest"
    ),
    "array_local_r2.png": plot_local_r2(coords_array, gwr.local_r2_),
    "bandwidth_map.png": plot_bandwidth(
        coords_array, 2.0, sample_locations=coords_array[:3]
    ),
    "multiple_coefficients.png": plot_multiple_coefficients(
        coords_array, gwr.coef_, feature_names=["x1", "x2"], shared_scale=True
    ),
}
for name, result in plots.items():
    print(save_plot(result, name))
gdf = gpd.GeoDataFrame(
    {"value": gwr.coef_[:, 0]},
    geometry=[Point(x, y) for x, y in coords_array],
    crs="EPSG:3857",
)
print(save_plot(create_choropleth(gdf, "value"), "choropleth.png"))
examples/plotting/02_diagnostics_and_comparison.py 
# SPDX-FileCopyrightText: 2026 Jinghao Hu
# SPDX-License-Identifier: MIT

"""All general residual, bandwidth, comparison, and collinearity plots."""

# Allow this script to run directly from any working directory.
import sys
from pathlib import Path

_PROJECT_ROOT = Path(__file__).resolve().parents[2]
_EXAMPLES_ROOT = _PROJECT_ROOT / "examples"
_SRC_ROOT = _PROJECT_ROOT / "src"
for _path in (_SRC_ROOT, _EXAMPLES_ROOT):
    if str(_path) not in sys.path:
        sys.path.insert(0, str(_path))

import matplotlib

matplotlib.use("Agg", force=True)
from _common import save_plot
from _models import surface_models

from pygwrx.plotting import (
    compare_coefficient_surfaces,
    compare_model_diagnostics,
    plot_bandwidth_selection,
    plot_coefficient_variability,
    plot_diagnostic_panel,
    plot_kernel_weights,
    plot_local_collinearity,
    plot_local_diagnostics,
    plot_mgwr_bandwidths,
    plot_observed_vs_predicted,
    plot_qq,
    plot_residual_histogram,
    plot_residuals,
    plot_spatial_residuals,
)

X, y, coords, gwr, mgwr, lcr = surface_models()
plots = {
    "compare_surfaces.png": compare_coefficient_surfaces([gwr, mgwr], "x1"),
    "compare_diagnostics.png": compare_model_diagnostics([gwr, mgwr]),
    "kernel_weights.png": plot_kernel_weights(gwr, focus=3),
    "mgwr_bandwidths.png": plot_mgwr_bandwidths(mgwr),
    "residuals.png": plot_residuals(gwr.fitted_values_, gwr.residuals_),
    "residual_histogram.png": plot_residual_histogram(gwr.residuals_),
    "qq.png": plot_qq(gwr.residuals_),
    "spatial_residuals.png": plot_spatial_residuals(coords, gwr.residuals_),
    "observed_predicted.png": plot_observed_vs_predicted(y, gwr.fitted_values_),
    "bandwidth_selection.png": plot_bandwidth_selection(
        [10, 15, 20, 25], [14.0, 9.0, 7.5, 8.2], 20, criterion="AICc"
    ),
    "coefficient_variability.png": plot_coefficient_variability(
        gwr.coef_, feature_names=["x1", "x2"]
    ),
    "diagnostic_panel_arrays.png": plot_diagnostic_panel(
        y, gwr.fitted_values_, gwr.residuals_, coords
    ),
    "diagnostic_panel_model.png": plot_diagnostic_panel(gwr),
    "local_diagnostics.png": plot_local_diagnostics(
        coords, {"local_r2": gwr.local_r2_, "influence": gwr.influence_}
    ),
    "collinearity_gwr.png": plot_local_collinearity(gwr, "condition_number"),
    "collinearity_lcr.png": plot_local_collinearity(lcr, "local_lambda"),
}
for name, result in plots.items():
    print(save_plot(result, name))