geomexp.visualization package

Submodules

geomexp.visualization.visualization module

Visualization module for clustering algorithms.

Provides plotting utilities for clustering analysis with consistent styling. All visual configuration flows through PlotStyle, which must be passed to ClusterVisualizer to ensure uniform appearance across all figures.

class geomexp.visualization.visualization.PlotStyle(figsize=(3.5, 3.5), dpi=300, point_size=1.5, center_size=15, center_linewidth=0.8, alpha_data=0.7, alpha_contour=0.15, color_palette=None, center_color='black', center_marker='o', arrow_color='black', arrow_linewidth=0.8, arrow_head_width=0.15, arrow_head_length=0.2, arrow_scale=1, contour_color='black', contour_linewidth=0.5, contour_alpha=0.9, curve_linewidth=0.8, curve_alpha=0.7, kde_color='gray', kde_linewidth=0.4, kde_alpha=0.6, loss_linewidth=1.0, decision_boundary_resolution=300, decision_boundary_show_points=True, decision_boundary_show_contour_lines=True, decision_boundary_show_centers=True, decision_boundary_show_regions=True, decision_boundary_color=None, axis_linewidth=0.6, grid_alpha=0.15, grid_linewidth=0.3, fontsize=9, use_latex=True)[source]

Bases: object

Central styling configuration for all cluster visualisations.

Every plot produced by ClusterVisualizer reads its visual parameters from this object, ensuring that all figures in a study share a uniform appearance. Construct a PlotStyle instance first, then pass it to ClusterVisualizer(style).

Parameters:

  • figsize (tuple[float, float])

  • dpi (int)

  • point_size (float)

  • center_size (float)

  • center_linewidth (float)

  • alpha_data (float)

  • alpha_contour (float)

  • color_palette (list[str] | None)

  • center_color (str)

  • center_marker (str)

  • arrow_color (str)

  • arrow_linewidth (float)

  • arrow_head_width (float)

  • arrow_head_length (float)

  • arrow_scale (float)

  • contour_color (str)

  • contour_linewidth (float)

  • contour_alpha (float)

  • curve_linewidth (float)

  • curve_alpha (float)

  • kde_color (str)

  • kde_linewidth (float)

  • kde_alpha (float)

  • loss_linewidth (float)

  • decision_boundary_resolution (int)

  • decision_boundary_show_points (bool)

  • decision_boundary_show_contour_lines (bool)

  • decision_boundary_show_centers (bool)

  • decision_boundary_show_regions (bool)

  • decision_boundary_color (str | None)

  • axis_linewidth (float)

  • grid_alpha (float)

  • grid_linewidth (float)

  • fontsize (float)

  • use_latex (bool)

figsize

Default figure size (width, height) in inches.

dpi

Resolution in dots per inch.

point_size

Scatter point size for data points.

center_size

Scatter point size for cluster centers.

center_linewidth

Edge line width for center markers.

alpha_data

Opacity of data points.

alpha_contour

Opacity of coloured decision regions.

color_palette

List of hex colour strings cycled over clusters.

center_color

Colour of center markers.

center_marker

Marker shape for centers.

arrow_color

Colour of index vector arrows.

arrow_linewidth

Line width of index vector arrows.

arrow_head_width

Head width of index vector arrows.

arrow_head_length

Head length of index vector arrows.

arrow_scale

Multiplicative scaling applied to index vector arrows for visibility.

contour_color

Colour of decision boundary lines.

contour_linewidth

Line width of decision boundary contours.

contour_alpha

Opacity of decision boundary contour lines.

curve_linewidth

Line width of expectile level-set contours.

curve_alpha

Opacity of expectile level-set contour lines.

kde_color

Colour of KDE density contour lines.

kde_linewidth

Line width of KDE density contour lines.

kde_alpha

Opacity of KDE density contour lines.

loss_linewidth

Line width of loss function curves.

decision_boundary_resolution

Grid resolution for boundary computation.

decision_boundary_show_points

Whether to overlay data points on boundary plots.

decision_boundary_show_contour_lines

Whether to draw boundary contour lines.

decision_boundary_show_centers

Whether to show center markers on boundary plots.

decision_boundary_show_regions

Whether to fill decision regions with colour.

decision_boundary_color

Override colour for boundary lines (None uses palette).

axis_linewidth

Width of axis spines and tick marks.

grid_alpha

Opacity of grid lines.

grid_linewidth

Width of grid lines.

fontsize

Base font size for labels and titles.

use_latex

Whether to enable LaTeX rendering via text.usetex.

figsize: tuple[float, float] = (3.5, 3.5)
dpi: int = 300
point_size: float = 1.5
center_size: float = 15
center_linewidth: float = 0.8
alpha_data: float = 0.7
alpha_contour: float = 0.15
color_palette: list[str] | None = None
center_color: str = 'black'
center_marker: str = 'o'
arrow_color: str = 'black'
arrow_linewidth: float = 0.8
arrow_head_width: float = 0.15
arrow_head_length: float = 0.2
arrow_scale: float = 1
contour_color: str = 'black'
contour_linewidth: float = 0.5
contour_alpha: float = 0.9
curve_linewidth: float = 0.8
curve_alpha: float = 0.7
kde_color: str = 'gray'
kde_linewidth: float = 0.4
kde_alpha: float = 0.6
loss_linewidth: float = 1.0
decision_boundary_resolution: int = 300
decision_boundary_show_points: bool = True
decision_boundary_show_contour_lines: bool = True
decision_boundary_show_centers: bool = True
decision_boundary_show_regions: bool = True
decision_boundary_color: str | None = None
axis_linewidth: float = 0.6
grid_alpha: float = 0.15
grid_linewidth: float = 0.3
fontsize: float = 9
use_latex: bool = True
class geomexp.visualization.visualization.ClusterVisualizer(style)[source]

Bases: object

Plotting engine for cluster analysis visualisations.

All plotting methods read visual configuration from the style attribute. A PlotStyle instance must be passed at construction time; there is no default.

Parameters:

style (PlotStyle) – A PlotStyle instance that governs all visual parameters.

Raises:

TypeError – If style is not a PlotStyle.

Example

>>> style = PlotStyle(figsize=(5, 4), use_latex=False)
>>> viz = ClusterVisualizer(style)
plot_cluster_assignments(X, result, ax=None, show_centers=True, show_indices=True, show_legend=False, title=None)[source]

Plot data points coloured by cluster assignment.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • show_centers (bool) – Whether to overlay center markers.

  • show_indices (bool) – Whether to draw index vector arrows.

  • show_legend (bool) – Whether to show a cluster legend.

  • title (str | None) – Optional axes title.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_decision_boundaries(X, result, ax=None, title=None, resolution=None, show_points=None, show_contour_lines=None, show_centers=None, show_regions=None, x_lim=None, y_lim=None, boundary_color=None)[source]

Plot decision boundaries (and optionally regions, data points, centers).

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • resolution (int | None) – Grid resolution for boundary computation. Defaults to self.style.decision_boundary_resolution.

  • show_points (bool | None) – Overlay data points. Defaults to style setting.

  • show_contour_lines (bool | None) – Draw boundary contour lines. Defaults to style setting.

  • show_centers (bool | None) – Show center markers. Defaults to style setting.

  • show_regions (bool | None) – Fill decision regions with colour. Defaults to style setting.

  • x_lim (tuple[float, float] | None) – Manual x-axis limits.

  • y_lim (tuple[float, float] | None) – Manual y-axis limits.

  • boundary_color (str | None) – Override colour for boundary lines.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_density_contours(X, ax=None, title=None, levels=20, bandwidth=0.2)[source]

Plot KDE density contours of the data.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • levels (int) – Number of contour levels.

  • bandwidth (float) – KDE bandwidth parameter.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_density_with_boundaries(X, result, ax=None, title=None, resolution=300, kde_levels=20, kde_bandwidth=0.2, show_centers=True, x_lim=None, y_lim=None)[source]

Overlay KDE density contours with decision boundary lines.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • resolution (int) – Grid resolution for boundary computation.

  • kde_levels (int) – Number of KDE contour levels.

  • kde_bandwidth (float) – KDE bandwidth parameter.

  • show_centers (bool) – Whether to overlay center markers.

  • x_lim (tuple[float, float] | None) – Manual x-axis limits.

  • y_lim (tuple[float, float] | None) – Manual y-axis limits.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_expectile_curves(center, index_vector, cost_levels=None, ax=None, title=None, show_index_arrow=True, curve_color=None, extent=3.0, resolution=300)[source]

Plot level curves of the expectile loss around a single center.

Parameters:

  • center (ndarray) – Center point of shape (2,).

  • index_vector (ndarray) – Index vector of shape (2,).

  • cost_levels (ndarray | None) – Loss values at which to draw contours.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • show_index_arrow (bool) – Whether to draw the index vector arrow.

  • curve_color (str | None) – Override colour for contour lines.

  • extent (float) – Half-width of the plotting window around center.

  • resolution (int) – Grid resolution.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_loss_comparison(loss_functions, x_range=(-3, 3), n_points=300, ax=None, title=None, show_legend=True)[source]

Plot one-dimensional loss function comparisons.

Parameters:

  • loss_functions (list[tuple[str, Callable[[ndarray], ndarray]]]) – List of (name, callable) pairs.

  • x_range (tuple[float, float]) – Domain (x_min, x_max) for the plot.

  • n_points (int) – Number of evaluation points.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • show_legend (bool) – Whether to display a legend.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

create_comparison_figure(X, results, plot_type='assignments', nrows=None, ncols=None, figsize=None, align_labels=True, **plot_kwargs)[source]

Create a multi-panel comparison figure.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • results (list[tuple[str, ClusterResult]]) – List of (name, ClusterResult) pairs for each panel.

  • plot_type (str) – One of "assignments", "boundaries", or "density".

  • nrows (int | None) – Number of subplot rows (inferred if None).

  • ncols (int | None) – Number of subplot columns (inferred if None).

  • figsize (tuple[float, float] | None) – Override figure size.

  • align_labels (bool) – Whether to align cluster labels across panels via permutation matching.

  • **plot_kwargs (Any) – Extra keyword arguments forwarded to the per-panel plot method.

Return type:

Figure

Returns:

The matplotlib Figure containing the comparison.

static save_figure(fig, filename, dpi=None, transparent=False)[source]

Save a figure to disk.

Parameters:

  • fig (Figure) – The figure to save.

  • filename (str) – Output file path (extension determines format).

  • dpi (int | None) – Override resolution (None uses the figure’s default).

  • transparent (bool) – Whether to use a transparent background.

Return type:

None

Module contents

Visualization utilities module.

class geomexp.visualization.ClusterVisualizer(style)[source]

Bases: object

Plotting engine for cluster analysis visualisations.

All plotting methods read visual configuration from the style attribute. A PlotStyle instance must be passed at construction time; there is no default.

Parameters:

style (PlotStyle) – A PlotStyle instance that governs all visual parameters.

Raises:

TypeError – If style is not a PlotStyle.

Example

>>> style = PlotStyle(figsize=(5, 4), use_latex=False)
>>> viz = ClusterVisualizer(style)
plot_cluster_assignments(X, result, ax=None, show_centers=True, show_indices=True, show_legend=False, title=None)[source]

Plot data points coloured by cluster assignment.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • show_centers (bool) – Whether to overlay center markers.

  • show_indices (bool) – Whether to draw index vector arrows.

  • show_legend (bool) – Whether to show a cluster legend.

  • title (str | None) – Optional axes title.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_decision_boundaries(X, result, ax=None, title=None, resolution=None, show_points=None, show_contour_lines=None, show_centers=None, show_regions=None, x_lim=None, y_lim=None, boundary_color=None)[source]

Plot decision boundaries (and optionally regions, data points, centers).

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • resolution (int | None) – Grid resolution for boundary computation. Defaults to self.style.decision_boundary_resolution.

  • show_points (bool | None) – Overlay data points. Defaults to style setting.

  • show_contour_lines (bool | None) – Draw boundary contour lines. Defaults to style setting.

  • show_centers (bool | None) – Show center markers. Defaults to style setting.

  • show_regions (bool | None) – Fill decision regions with colour. Defaults to style setting.

  • x_lim (tuple[float, float] | None) – Manual x-axis limits.

  • y_lim (tuple[float, float] | None) – Manual y-axis limits.

  • boundary_color (str | None) – Override colour for boundary lines.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_density_contours(X, ax=None, title=None, levels=20, bandwidth=0.2)[source]

Plot KDE density contours of the data.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • levels (int) – Number of contour levels.

  • bandwidth (float) – KDE bandwidth parameter.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_density_with_boundaries(X, result, ax=None, title=None, resolution=300, kde_levels=20, kde_bandwidth=0.2, show_centers=True, x_lim=None, y_lim=None)[source]

Overlay KDE density contours with decision boundary lines.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • result (ClusterResult) – Clustering result.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • resolution (int) – Grid resolution for boundary computation.

  • kde_levels (int) – Number of KDE contour levels.

  • kde_bandwidth (float) – KDE bandwidth parameter.

  • show_centers (bool) – Whether to overlay center markers.

  • x_lim (tuple[float, float] | None) – Manual x-axis limits.

  • y_lim (tuple[float, float] | None) – Manual y-axis limits.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_expectile_curves(center, index_vector, cost_levels=None, ax=None, title=None, show_index_arrow=True, curve_color=None, extent=3.0, resolution=300)[source]

Plot level curves of the expectile loss around a single center.

Parameters:

  • center (ndarray) – Center point of shape (2,).

  • index_vector (ndarray) – Index vector of shape (2,).

  • cost_levels (ndarray | None) – Loss values at which to draw contours.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • show_index_arrow (bool) – Whether to draw the index vector arrow.

  • curve_color (str | None) – Override colour for contour lines.

  • extent (float) – Half-width of the plotting window around center.

  • resolution (int) – Grid resolution.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

plot_loss_comparison(loss_functions, x_range=(-3, 3), n_points=300, ax=None, title=None, show_legend=True)[source]

Plot one-dimensional loss function comparisons.

Parameters:

  • loss_functions (list[tuple[str, Callable[[ndarray], ndarray]]]) – List of (name, callable) pairs.

  • x_range (tuple[float, float]) – Domain (x_min, x_max) for the plot.

  • n_points (int) – Number of evaluation points.

  • ax (Axes | None) – Matplotlib axes (created if None).

  • title (str | None) – Optional axes title.

  • show_legend (bool) – Whether to display a legend.

Return type:

Figure

Returns:

The matplotlib Figure containing the plot.

create_comparison_figure(X, results, plot_type='assignments', nrows=None, ncols=None, figsize=None, align_labels=True, **plot_kwargs)[source]

Create a multi-panel comparison figure.

Parameters:

  • X (ndarray) – Data array of shape (n_samples, 2).

  • results (list[tuple[str, ClusterResult]]) – List of (name, ClusterResult) pairs for each panel.

  • plot_type (str) – One of "assignments", "boundaries", or "density".

  • nrows (int | None) – Number of subplot rows (inferred if None).

  • ncols (int | None) – Number of subplot columns (inferred if None).

  • figsize (tuple[float, float] | None) – Override figure size.

  • align_labels (bool) – Whether to align cluster labels across panels via permutation matching.

  • **plot_kwargs (Any) – Extra keyword arguments forwarded to the per-panel plot method.

Return type:

Figure

Returns:

The matplotlib Figure containing the comparison.

static save_figure(fig, filename, dpi=None, transparent=False)[source]

Save a figure to disk.

Parameters:

  • fig (Figure) – The figure to save.

  • filename (str) – Output file path (extension determines format).

  • dpi (int | None) – Override resolution (None uses the figure’s default).

  • transparent (bool) – Whether to use a transparent background.

Return type:

None

class geomexp.visualization.PlotStyle(figsize=(3.5, 3.5), dpi=300, point_size=1.5, center_size=15, center_linewidth=0.8, alpha_data=0.7, alpha_contour=0.15, color_palette=None, center_color='black', center_marker='o', arrow_color='black', arrow_linewidth=0.8, arrow_head_width=0.15, arrow_head_length=0.2, arrow_scale=1, contour_color='black', contour_linewidth=0.5, contour_alpha=0.9, curve_linewidth=0.8, curve_alpha=0.7, kde_color='gray', kde_linewidth=0.4, kde_alpha=0.6, loss_linewidth=1.0, decision_boundary_resolution=300, decision_boundary_show_points=True, decision_boundary_show_contour_lines=True, decision_boundary_show_centers=True, decision_boundary_show_regions=True, decision_boundary_color=None, axis_linewidth=0.6, grid_alpha=0.15, grid_linewidth=0.3, fontsize=9, use_latex=True)[source]

Bases: object

Central styling configuration for all cluster visualisations.

Every plot produced by ClusterVisualizer reads its visual parameters from this object, ensuring that all figures in a study share a uniform appearance. Construct a PlotStyle instance first, then pass it to ClusterVisualizer(style).

Parameters:

  • figsize (tuple[float, float])

  • dpi (int)

  • point_size (float)

  • center_size (float)

  • center_linewidth (float)

  • alpha_data (float)

  • alpha_contour (float)

  • color_palette (list[str] | None)

  • center_color (str)

  • center_marker (str)

  • arrow_color (str)

  • arrow_linewidth (float)

  • arrow_head_width (float)

  • arrow_head_length (float)

  • arrow_scale (float)

  • contour_color (str)

  • contour_linewidth (float)

  • contour_alpha (float)

  • curve_linewidth (float)

  • curve_alpha (float)

  • kde_color (str)

  • kde_linewidth (float)

  • kde_alpha (float)

  • loss_linewidth (float)

  • decision_boundary_resolution (int)

  • decision_boundary_show_points (bool)

  • decision_boundary_show_contour_lines (bool)

  • decision_boundary_show_centers (bool)

  • decision_boundary_show_regions (bool)

  • decision_boundary_color (str | None)

  • axis_linewidth (float)

  • grid_alpha (float)

  • grid_linewidth (float)

  • fontsize (float)

  • use_latex (bool)

figsize

Default figure size (width, height) in inches.

dpi

Resolution in dots per inch.

point_size

Scatter point size for data points.

center_size

Scatter point size for cluster centers.

center_linewidth

Edge line width for center markers.

alpha_data

Opacity of data points.

alpha_contour

Opacity of coloured decision regions.

color_palette

List of hex colour strings cycled over clusters.

center_color

Colour of center markers.

center_marker

Marker shape for centers.

arrow_color

Colour of index vector arrows.

arrow_linewidth

Line width of index vector arrows.

arrow_head_width

Head width of index vector arrows.

arrow_head_length

Head length of index vector arrows.

arrow_scale

Multiplicative scaling applied to index vector arrows for visibility.

contour_color

Colour of decision boundary lines.

contour_linewidth

Line width of decision boundary contours.

contour_alpha

Opacity of decision boundary contour lines.

curve_linewidth

Line width of expectile level-set contours.

curve_alpha

Opacity of expectile level-set contour lines.

kde_color

Colour of KDE density contour lines.

kde_linewidth

Line width of KDE density contour lines.

kde_alpha

Opacity of KDE density contour lines.

loss_linewidth

Line width of loss function curves.

decision_boundary_resolution

Grid resolution for boundary computation.

decision_boundary_show_points

Whether to overlay data points on boundary plots.

decision_boundary_show_contour_lines

Whether to draw boundary contour lines.

decision_boundary_show_centers

Whether to show center markers on boundary plots.

decision_boundary_show_regions

Whether to fill decision regions with colour.

decision_boundary_color

Override colour for boundary lines (None uses palette).

axis_linewidth

Width of axis spines and tick marks.

grid_alpha

Opacity of grid lines.

grid_linewidth

Width of grid lines.

fontsize

Base font size for labels and titles.

use_latex

Whether to enable LaTeX rendering via text.usetex.

figsize: tuple[float, float] = (3.5, 3.5)
dpi: int = 300
point_size: float = 1.5
center_size: float = 15
center_linewidth: float = 0.8
alpha_data: float = 0.7
alpha_contour: float = 0.15
color_palette: list[str] | None = None
center_color: str = 'black'
center_marker: str = 'o'
arrow_color: str = 'black'
arrow_linewidth: float = 0.8
arrow_head_width: float = 0.15
arrow_head_length: float = 0.2
arrow_scale: float = 1
contour_color: str = 'black'
contour_linewidth: float = 0.5
contour_alpha: float = 0.9
curve_linewidth: float = 0.8
curve_alpha: float = 0.7
kde_color: str = 'gray'
kde_linewidth: float = 0.4
kde_alpha: float = 0.6
loss_linewidth: float = 1.0
decision_boundary_resolution: int = 300
decision_boundary_show_points: bool = True
decision_boundary_show_contour_lines: bool = True
decision_boundary_show_centers: bool = True
decision_boundary_show_regions: bool = True
decision_boundary_color: str | None = None
axis_linewidth: float = 0.6
grid_alpha: float = 0.15
grid_linewidth: float = 0.3
fontsize: float = 9
use_latex: bool = True