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)

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:

• som (BaseSOM)

• config (VisualizationConfig | None)

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)

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)

Plot classification map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_cluster_map(*args, **kwargs)

Plot clustering results overlaid on SOM grid.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_cluster_quality_comparison(*args, **kwargs)

Compare clustering quality metrics across different methods.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_clustering_comparison_grid(*args, **kwargs)

Plot a grid comparing different clustering methods and feature spaces.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_component_planes(*args, **kwargs)

Plot component planes using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_distance_map(*args, **kwargs)

Plot distance map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_elbow_analysis(*args, **kwargs)

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

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_grid(*args, **kwargs)

Plot grid visualization using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_hit_map(*args, **kwargs)

Plot hit map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_metric_map(*args, **kwargs)

Plot metric map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_rank_map(*args, **kwargs)

Plot rank map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_score_map(*args, **kwargs)

Plot score map using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_silhouette_analysis(*args, **kwargs)

Plot silhouette analysis for clustering results.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

plot_training_errors(*args, **kwargs)

Plot training errors using topology-specific visualizer.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

None

Example

import torch
from torchsom import SOM, SOMVisualizer

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

viz = SOMVisualizer(som=som)
viz.plot_distance_map()
viz.plot_hit_map(data=data)

See the Visualization Gallery gallery for every plot, including plot_all and the supervised maps.

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)

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).

• The supervised maps (metric/score/rank/classification) and plot_all require a pre-computed bmus_data_map = som.build_map("bmus_data", data=data); build it once and reuse it across plots.