Visualization API

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

SOM Visualizer

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

Bases: object

Class for handling Self-Organizing Map visualizations.

Parameters:
plot_all(quantization_errors, topographic_errors, data, target=None, 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: hit map, score map, rank map, metric map, component planes.

Parameters:

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

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

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

  • target (Optional[torch.Tensor], optional) – Optional labels tensor for data points [batch_size]. Defaults to None.

  • component_names (Optional[List[str]], optional) – Names for each component/feature. If None, uses “Component {i+1}”. Defaults to None.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • training_errors (bool, optional) – Boolean to decide if the visualizer plots training learning curves. Defaults to True.

  • distance_map (bool, optional) – Boolean to decide if the visualizer plots distance map. Defaults to True.

  • hit_map (bool, optional) – Boolean to decide if the visualizer plots hit map. Defaults to True.

  • score_map (bool, optional) – Boolean to decide if the visualizer plots score map. Defaults to True.

  • rank_map (bool, optional) – Boolean to decide if the visualizer plots rank map. Defaults to True.

  • metric_map (bool, optional) – Boolean to decide if the visualizer plots metric map. Defaults to True.

  • component_planes (bool, optional) – Boolean to decide if the visualizer plots component planes. Defaults to True.

Return type:

None

plot_classification_map(data, target, fig_name='classification_map', save_path=None, gridsize=None)[source]

Plot classification map showing the most frequent label for each neuron.

Parameters:

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

  • target (torch.Tensor) – Labels tensor for data points [batch_size]. Must be encoded with values > 1 to avoid white cells like unactivated.

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to “classification_map”.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_component_planes(component_names=None, fig_name=None, save_path=None, gridsize=None)[source]

Plot component planes (CPs), so one plane by input feature.

Parameters:

  • component_names (Optional[List[str]], optional) – Names for each component/feature. If None, uses “Component {i+1}”. Defaults to None.

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to None.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_distance_map(fig_name='distance_map', save_path=None, gridsize=None)[source]

Plot the D-Matrix (distance map) of a trained SOM.

Parameters:

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to “distance_map”.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_grid(map, title, colorbar_label, filename, save_path=None, log_scale=False, cmap=None, show_values=False, gridsize=None, value_format='.2f', is_component_plane=False)[source]

Universal plotting function for both rectangular and hexagonal grids.

Parameters:

  • map (torch.Tensor) – Data to visualize. [row_neurons, col_neurons]

  • title (str) – Plot title.

  • colorbar_label (str) – Label for the colorbar.

  • filename (str) – The name of the file to save.

  • save_path (Optional[Union[str, Path]], optional) – Path to save the plot. Defaults to None.

  • log_scale (bool, optional) – Whether to use logarithmic scale for colors. Defaults to False.

  • cmap (Optional[str], optional) – Custom colormap to use. Defaults to None.

  • show_values (bool, optional) – Whether to show values in cells. Defaults to False.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

  • value_format (str, optional) – Format string for displayed values. Defaults to “.2f”.

  • is_component_plane (bool, optional) – Boolean to check if current plot is a component plane. Defaults to False.

Return type:

None

plot_hit_map(data, fig_name='hit_map', save_path=None, gridsize=None)[source]

Plot hit map showing the distribution of winning neurons from input data.

Parameters:

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

  • fig_name (Optional[str], optional) – The name of the file to save.. Defaults to “hit_map”.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_metric_map(data, target, reduction_parameter='mean', fig_name=None, save_path=None, gridsize=None)[source]

Plot target distribution of the corresponding input samples through SOM’s neurons.

Parameters:

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

  • target (torch.Tensor) – Optional labels tensor for data points [batch_size]. Defaults to None.

  • reduction_parameter (str, optional) – Decide the calculation to apply to each neuron, ‘mean’ or ‘std’. Defaults to “mean”.

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to None.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_rank_map(data, target, fig_name='rank_map', save_path=None, gridsize=None)[source]

Plot SOM ranked neurons visualization.

Parameters:

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

  • target (torch.Tensor) – Optional labels tensor for data points [batch_size]. Defaults to None.

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to “rank_map”.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_score_map(data, target, fig_name='score_map', save_path=None, gridsize=None)[source]

Plot SOM neuron representativeness visualization.

Parameters:

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

  • target (torch.Tensor) – Optional labels tensor for data points [batch_size]. Defaults to “score_map”.

  • fig_name (Optional[str], optional) – The name of the file to save. Defaults to None.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization. Defaults to None.

  • gridsize (Optional[Tuple[int, int]], optional) – Size of hexagonal grid. If None, calculated from map dimensions. Defaults to None.

Return type:

None

plot_training_errors(quantization_errors, topographic_errors, fig_name='training_errors', save_path=None)[source]

Plot training errors over epochs.

Parameters:

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

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

  • fig_name (Optional[str], optional) – The name of the file to save.. Defaults to “training_errors”.

  • save_path (Optional[Union[str, Path]], optional) – Optional path to save the visualization figure. Defaults to None.

Return type:

None

Visualization Configuration

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', hexgrid_size=None)[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)

  • hexgrid_size (int | None)

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
hexgrid_size: int | None = None
save_format: str = 'png'

Supported Formats

  • PNG (default, web-friendly)

  • PDF (vector, publication-ready)

  • SVG (vector, scalable)

  • JPEG (compressed, smaller files)