Visualization API

The visualization module provides comprehensive plotting and analysis tools for SOMs.

SOM Visualizer

Base class for all visualization methods.

class torchsom.visualization.base.SOMVisualizer(som, config=None)[source]

Bases: object

Factory class for handling Self-Organizing Map visualizations.

This class acts as a factory that creates the appropriate topology-specific visualizer (HexagonalVisualizer or RectangularVisualizer) based on the SOM’s topology.

Parameters:
plot_all(quantization_errors, topographic_errors, bmus_data_map, data, target, component_names=None, save_path=None, training_errors=True, distance_map=True, hit_map=True, score_map=True, rank_map=True, metric_map=True, component_planes=True)[source]

Plot all visualizations using topology-specific visualizer.

Parameters:

  • quantization_errors (list[float]) – List of quantization errors [epochs]

  • topographic_errors (list[float]) – List of topographic errors [epochs]

  • bmus_data_map (dict[tuple[int, int], list[int]]) – Pre-computed BMU to data indices mapping

  • data (torch.Tensor) – Input data tensor [batch_size, n_features]

  • target (torch.Tensor) – Labels tensor for data points [batch_size]

  • component_names (Optional[list[str]]) – Names for each component/feature

  • save_path (Optional[Union[str, Path]]) – Path to save visualizations

  • training_errors (bool) – Whether to plot training learning curves

  • distance_map (bool) – Whether to plot distance map

  • hit_map (bool) – Whether to plot hit map

  • score_map (bool) – Whether to plot score map

  • rank_map (bool) – Whether to plot rank map

  • metric_map (bool) – Whether to plot metric map

  • component_planes (bool) – Whether to plot component planes

Return type:

None

plot_classification_map(*args, **kwargs)[source]

Plot classification map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_cluster_map(*args, **kwargs)[source]

Plot clustering results overlaid on SOM grid.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_cluster_quality_comparison(*args, **kwargs)[source]

Compare clustering quality metrics across different methods.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_clustering_comparison_grid(*args, **kwargs)[source]

Plot a grid comparing different clustering methods and feature spaces.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_component_planes(*args, **kwargs)[source]

Plot component planes using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_distance_map(*args, **kwargs)[source]

Plot distance map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_elbow_analysis(*args, **kwargs)[source]

Plot elbow analysis for optimal K selection in K-means.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_grid(*args, **kwargs)[source]

Plot grid visualization using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_hit_map(*args, **kwargs)[source]

Plot hit map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_metric_map(*args, **kwargs)[source]

Plot metric map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_rank_map(*args, **kwargs)[source]

Plot rank map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_score_map(*args, **kwargs)[source]

Plot score map using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_silhouette_analysis(*args, **kwargs)[source]

Plot silhouette analysis for clustering results.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

plot_training_errors(*args, **kwargs)[source]

Plot training errors using topology-specific visualizer.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

Example

from torchsom import SOM
from torchsom.visualization import SOMVisualizer
import torch

data = torch.randn(500, 3)
som = SOM(x=12, y=10, num_features=3, epochs=20)
som.initialize_weights(data, mode="pca")
q_errors, t_errors = som.fit(data)

viz = SOMVisualizer(som)
viz.plot_all(
    quantization_errors=q_errors,
    topographic_errors=t_errors,
    data=data,
    target=None,
    save_path=None,
)

Visualization Configuration

Configuration settings for SOM visualizations.

class torchsom.visualization.config.VisualizationConfig(figsize=(12, 8), fontsize=<factory>, fontweight=<factory>, cmap='viridis', dpi=300, grid_alpha=0.3, colorbar_pad=0.01, save_format='png', hex_radius=0.5, hex_border_color='black', hex_border_width=0.3)[source]

Bases: object

Configuration settings for SOM visualizations.

Parameters:

  • figsize (tuple[int, int])

  • fontsize (dict[str, int])

  • fontweight (dict[str, str])

  • cmap (str)

  • dpi (int)

  • grid_alpha (float)

  • colorbar_pad (float)

  • save_format (str)

  • hex_radius (float)

  • hex_border_color (str)

  • hex_border_width (float)

cmap: str = 'viridis'
colorbar_pad: float = 0.01
dpi: int = 300
figsize: tuple[int, int] = (12, 8)
fontsize: dict[str, int]
fontweight: dict[str, str]
grid_alpha: float = 0.3
hex_border_color: str = 'black'
hex_border_width: float = 0.3
hex_radius: float = 0.5
save_format: str = 'png'

Supported Formats

  • PNG (default, web-friendly)

  • PDF (vector, publication-ready)

  • SVG (vector, scalable)

  • JPEG (compressed, smaller files)

Notes

  • The visualizer is a factory that forwards to topology-specific implementations (hexagonal or rectangular).

  • For supervised maps (metric/score/rank/classification), you can either pass data and target directly or precompute bmus_data_map = som.build_map("bmus_data", data, return_indices=True) to speed up repeated plots.