Visualization

Tier: Public API

See also: Pipeline · Distances · Concepts

Pipeline class providing visualization methods for PhenoMe.

Module Breakdown:

_dr_plots.py: Dimensionality reduction visualizations (PCA, t-SNE, UMAP) and centroid plots.
_distance_plots.py: Distance distributions, reference comparison plots, and property correlations.
_image_display.py: Raw and transformed image visualization with channel-wise controls.
_interpretability_plots.py: Visualizing feature importance and drivers for embedding axes.
_component_correlation_plots.py: Faceted plots of correlations between embeddings and properties.
_group_enrichment_plots.py: Faceted Z-score enrichment plots for metadata groups.
_helpers.py: Shared utilities for Plotly and Matplotlib layout/styling.

Interdependencies: The following private plot functions are intended for use by PhenoMeAnalysis:

_plot_property_correlations_plotly (from _distance_plots.py): Used for embedding-property correlation analysis.
_display_multivariate_interpretability (from _interpretability_plots.py): Used for explaining embedding axes.

Visualization

Method

`plot_pca`

_DRPlotsMixin.plot_pca(
    self,
    n_components: int = 2,
    color_by: str | None = None,
    figsize: tuple[int, int] = (10, 8),
    source: Literal['embeddings', 'properties', 'combined'] = 'embeddings',
    property_keys: list[str] | None = None,
    filters: dict[str, typing.Any | list[typing.Any]] | None = None,
    exclude: dict[str, typing.Any | list[typing.Any]] | None = None,
    hover_features: list[str] | None = None,
    return_fig: bool = False,
    render_mode: Literal['auto', 'svg', 'webgl'] = 'webgl',
    normalize: bool = True,
    sample_size: int | None = None,
    **dr_kwargs: Any
) -> Any

Plot PCA of embeddings, properties, or combined features (Plotly, WebGL by default).

Method

`plot_tsne`

_DRPlotsMixin.plot_tsne(
    self,
    n_components: int = 2,
    perplexity: float = 30.0,
    color_by: str | None = None,
    figsize: tuple[int, int] = (10, 8),
    source: Literal['embeddings', 'properties', 'combined'] = 'embeddings',
    property_keys: list[str] | None = None,
    filters: dict[str, typing.Any | list[typing.Any]] | None = None,
    exclude: dict[str, typing.Any | list[typing.Any]] | None = None,
    hover_features: list[str] | None = None,
    return_fig: bool = False,
    render_mode: Literal['auto', 'svg', 'webgl'] = 'webgl',
    normalize: bool = True,
    sample_size: int | None = None,
    **dr_kwargs: Any
) -> Any

Plot t-SNE of embeddings, properties, or combined features (Plotly, WebGL by default).

Method

`plot_umap`

_DRPlotsMixin.plot_umap(
    self,
    n_components: int = 2,
    n_neighbors: int = 15,
    min_dist: float = 0.1,
    color_by: str | None = None,
    figsize: tuple[int, int] = (10, 8),
    source: Literal['embeddings', 'properties', 'combined'] = 'embeddings',
    property_keys: list[str] | None = None,
    filters: dict[str, typing.Any | list[typing.Any]] | None = None,
    exclude: dict[str, typing.Any | list[typing.Any]] | None = None,
    hover_features: list[str] | None = None,
    return_fig: bool = False,
    render_mode: Literal['auto', 'svg', 'webgl'] = 'webgl',
    normalize: bool = True,
    sample_size: int | None = None,
    **dr_kwargs: Any
) -> Any

Plot UMAP of embeddings, properties, or combined features (Plotly, WebGL by default).

Method

`plot_counts`

PhenoMeVisualization.plot_counts(
    self,
    group_by: list[str] | None = None,
    return_fig: bool = False,
    plot: bool = True
) -> Any

Plot count of images grouped by metadata using Plotly.

Args:

group_by: List of metadata keys to group by.
return_fig: If True, return the Plotly figure instead of displaying it.
plot: If True (default), create and display a Plotly plot. If False, print results as text.

Method

`plot_centroids`

_DRPlotsMixin.plot_centroids(
    self,
    group_by: str | list[str],
    method: Literal['pca', 'tsne', 'umap'] = 'pca',
    n_components: int = 2,
    filters: dict[str, typing.Any | list[typing.Any]] | None = None,
    exclude: dict[str, typing.Any | list[typing.Any]] | None = None,
    source: Literal['embeddings', 'properties', 'combined'] = 'embeddings',
    property_keys: list[str] | None = None,
    show_points: bool = True,
    show_centroids: bool = True,
    figsize: tuple[int, int] = (10, 8),
    return_fig: bool = False,
    normalize: bool = True,
    **dr_kwargs: Any
) -> Any

Plot centroids of groups in reduced embedding space.

Method

`plot_image_by_index`

_ImageDisplayMixin.plot_image_by_index(
    self,
    idx: int,
    distance_results: pandas.DataFrame | None = None,
    channels: int | list | None = None,
    figsize: tuple = (6, 6),
    title_fields: list[str] | None = None,
    show_extra_info: bool = True,
    apply_transforms: bool = False,
    downsample: int | None = 720,
    ax: Any = None,
    return_fig: bool = False,
    show_mask_overlay: bool = False
) -> Any

Plot a specific image by its index.

Args:

idx: Image index in results
distance_results: Optional distance computation results DataFrame
channels: specific channels to plot
figsize: Figure size
title_fields: Optional list of field names to display in title
show_extra_info: If True, prints detailed information after plotting
apply_transforms: If True, apply pipeline image_transforms
downsample: If not None, approximate desired size (in pixels) for the longest image edge when downsampling. The final image size may differ slightly due to integer stepping. If None, no downsampling.
ax: Optional matplotlib axes to plot on. If provided, a new figure is not created.
return_fig: If True, return the displayed image as a NumPy array and do not open a matplotlib figure. Mask overlay, when requested, is composited onto that array.
show_mask_overlay: If True, draws the segmentation mask as a semi-transparent yellow overlay with a crisp contour. Requires masks to have been discovered via mask_dir in find_files. Useful for verifying that masks load correctly and spatially align with their images.

Returns:

The image as a NumPy array when return_fig is True; otherwise None.

Method

`image_preview_png_bytes`

_ImageDisplayMixin.image_preview_png_bytes(
    self,
    idx: int,
    distance_results: pandas.DataFrame | None = None,
    channels: int | list | None = None,
    title_fields: list[str] | None = None,
    show_extra_info: bool = False,
    apply_transforms: bool = True,
    downsample: int | None = 720
) -> tuple

Rasterize the same view as plot_image_by_index to PNG bytes.

Used by the interactive explorer with ipywidgets.Image because matplotlib display() / plt.show() from Plotly click callbacks does not reliably target a nested Output widget (output goes to the cell or nowhere).

When show_extra_info is True, also emits the same details as plot_image_by_index via logging and returns their text for UI display.

Returns:

(png_bytes, details_text_or_none) — details_text_or_none is the formatted extra-info block when show_extra_info is True and details exist.

Method

`print_distance_summary`

_DistancePlotsMixin.print_distance_summary(
    self,
    distance_results: pandas.DataFrame,
    group_by: str | None = None,
    dist_range: tuple = (0, 100)
) -> None

Print distance summary statistics without plotting. Safe to use when enable_plots=False.

Args:

distance_results: DataFrame containing ‘distance’ column
group_by: Metadata key to group by
dist_range: Tuple of (min, max) distances to include