API Reference: Visualization

Visualization tools for dimensionality reduction embeddings and analysis.

This module provides visualization capabilities for the moddr package, enabling the creation of plots for embedding analysis, community visualization, and comparative evaluation of dimensionality reduction results.

moddr.visualization.visualization.display_embeddings(embeddings: list[~moddr.embedding_state.EmbeddingState], figsize_columns: int = 2, figsize: tuple[int, int] = (15, 15), show_edges: bool = True, node_cmap: <module 'matplotlib.cm' from '/home/docs/checkouts/readthedocs.org/user_builds/moddr/envs/latest/lib/python3.10/site-packages/matplotlib/cm.py'> = <matplotlib.colors.ListedColormap object>, edge_cmap: <module 'matplotlib.cm' from '/home/docs/checkouts/readthedocs.org/user_builds/moddr/envs/latest/lib/python3.10/site-packages/matplotlib/cm.py'> = <matplotlib.colors.ListedColormap object>, show_edge_cbar: bool = False, show_node_cbar: bool = False, show_title: bool = True, show_community_centers: bool = False, node_color_attribute: str | None = None, node_label_attribute: str | None = None) → Figure[source]

Display multiple embeddings as network graphs in a subplot grid.

This function creates a visualization of multiple EmbeddingState objects, showing nodes, edges, and various attributes in a customizable grid layout.

Parameters:

  • embeddings (list[EmbeddingState]) – List of EmbeddingState objects to visualize.

  • figsize_columns (int) – Number of columns in the subplot grid. Default is 2.

  • figsize (tuple[int, int]) – Size of each individual subplot (width, height). Default is (15, 15).

  • show_edges (bool) – Whether to display edges based on the graph of the EmbeddingState. Default is True.

  • node_cmap (plt.cm) – Colormap for node colors. Default is plt.cm.viridis.

  • edge_cmap (plt.cm) – Colormap for edge colors. Default is plt.cm.viridis.

  • show_edge_cbar (bool) – Whether to show colorbar for edge weights. Default is False.

  • show_node_cbar (bool) – Whether to show colorbar for node colors. Default is False.

  • show_title (bool) – Whether to display titles for each subplot. Default is True.

  • show_community_centers (bool) – Whether to display community centers as larger nodes. Default is False.

  • node_color_attribute (str | None) – Graph node attribute to use for node coloring. If None, tries to use labels from EmbeddingState. Otherwise, falls back to default colors. Default is None.

  • node_label_attribute (str | None) – Graph node attribute to use for node labels. Use “id” for node IDs or specify custom attribute name. Default is None.

Returns:

matplotlib Figure object containing the visualization.

Return type:

plt.Figure

moddr.visualization.visualization.plot_community_graphs(embeddings: list[~moddr.embedding_state.EmbeddingState], figsize_columns: int = 2, figsize: tuple[int, int] = (15, 15), node_cmap: <module 'matplotlib.cm' from '/home/docs/checkouts/readthedocs.org/user_builds/moddr/envs/latest/lib/python3.10/site-packages/matplotlib/cm.py'> = <matplotlib.colors.ListedColormap object>, edge_cmap: <module 'matplotlib.cm' from '/home/docs/checkouts/readthedocs.org/user_builds/moddr/envs/latest/lib/python3.10/site-packages/matplotlib/cm.py'> = <matplotlib.colors.ListedColormap object>, only_communities: bool = False, community_ids: list[int] | None = None, show_boundary_edges: bool = False, unify_edge_colors: bool = False, show_title: bool = True, show_community_centers: bool = False, node_color_attribute: str | None = None, node_label_attribute: str | None = None) → Figure[source]

Display community-focused visualizations of embeddings.

This function creates visualizations that emphasize community structure, allowing filtering by specific communities and showing boundary connections.

Parameters:

  • embeddings (list[EmbeddingState]) – List of EmbeddingState objects to visualize.

  • figsize_columns (int) – Number of columns in the subplot grid. Default is 2.

  • figsize (tuple[int, int]) – Size of each individual subplot (width, height). Default is (15, 15).

  • node_cmap (plt.cm) – Colormap for node colors. Default is plt.cm.viridis.

  • edge_cmap (plt.cm) – Colormap for edge colors. Default is plt.cm.viridis.

  • only_communities (bool) – If True, show only specified communities in community_ids. If False, show all nodes with highlighted communities. Default is False.

  • community_ids (list[int] | None) – List of specific community IDs to display. If None and only_communities=True, shows all communities. Default is None.

  • show_boundary_edges (bool) – Whether to include edges connecting to nodes outside each community. Default is False.

  • unify_edge_colors (bool) – If True, color edges by source node community. If False, use edge weights for coloring. Default is False.

  • show_title (bool) – Whether to display titles for each subplot. Default is True.

  • show_community_centers (bool) – Whether to display community centers as larger nodes. Default is False.

  • node_color_attribute (str | None) – Graph node attribute to use for node coloring. Default is None.

  • node_label_attribute (str | None) – Graph node attribute to use for node labels. Default is None.

Returns:

matplotlib Figure object containing the community visualization.

Return type:

plt.Figure

moddr.visualization.visualization.plot_metrics_report(data_df: DataFrame, division: list[any] | None = None, division_label: str | None = None, label_height: float = 0.1) → Figure[source]

Create a line plot visualization of metrics across different embeddings.

This function generates a comprehensive metrics report showing how different evaluation metrics vary across embedding objects, with optional grouping by parameter divisions.

Parameters:

  • data_df (pd.DataFrame) – DataFrame containing metrics data. Must include ‘obj_id’ column and numeric metric columns.

  • division (list[any] | None) – List of division values to group embeddings (e.g., resolution parameters). Length should match the number of embedding groups. Default is None.

  • division_label (str | None) – Label for the division parameter (e.g., “Resolution”). Required if division is provided. Default is None.

  • label_height (float) – Vertical position for division labels on the plot. Default is 0.1.

Returns:

matplotlib Figure object containing the metrics visualization.

Return type:

plt.Figure

Raises:

ValueError – If input validation fails.

Notes

  • The function automatically adds background shading for different parameter groups when division is provided.

  • Each metric is plotted with a unique marker and color.

  • The plot includes grid lines and a legend positioned outside the plot area.

moddr.visualization.visualization.plot_pos_movements(reference: ~moddr.embedding_state.EmbeddingState, target: ~moddr.embedding_state.EmbeddingState, figsize: tuple[int, int] = (15, 15), filtered_communities: list[int] | None = None, community_colors: bool = False, community_centers: bool = False, plot_target_nodes: bool = False, show_title: bool = True, node_cmap: <module 'matplotlib.cm' from '/home/docs/checkouts/readthedocs.org/user_builds/moddr/envs/latest/lib/python3.10/site-packages/matplotlib/cm.py'> = <matplotlib.colors.ListedColormap object>) → Figure[source]

Visualize node position movements between two embeddings using arrows.

This function creates a quiver plot showing how node positions change from a reference embedding to a target embedding, useful for analyzing the effects of layout algorithms or parameter changes.

Parameters:

  • reference (EmbeddingState) – Source EmbeddingState showing initial positions.

  • target (EmbeddingState) – Target EmbeddingState showing modified positions.

  • figsize (tuple[int, int]) – Figure size (width, height). Default is (15, 15).

  • filtered_communities (list[int] | None) – List of community IDs to focus on. If None, shows movements for all nodes. Default is None.

  • community_colors (bool) – Whether to color arrows by target community membership. Default is False.

  • community_centers (bool) – Whether to display community centers as black dots. Default is False.

  • plot_target_nodes (bool) – Whether to show target node positions as scatter points. Default is False.

  • show_title (bool) – Whether to display a descriptive title. Default is True.

  • node_cmap (plt.cm) – Colormap for arrow and node colors. Default is plt.cm.viridis.

Returns:

matplotlib Figure object containing the movement visualization.

Return type:

plt.Figure

Notes

  • Arrows point from reference positions to target positions.

  • Arrow length is scaled down when plot_target_nodes=True to avoid overlap.

  • The plot automatically adjusts axis limits to show all movements.