Skip to content
PhenoMePhenoMe

Interactive explorer

Tier: Public API

See also: Visualization · Pipeline

Factory

Section titled “Factory”

create_interactive_explorer

Section titled “create_interactive_explorer”
create_interactive_explorer(
    pheno_me: '_InteractiveExplorerProtocol',
    filters: 'dict[str, Any] | None' = None,
    exclude: 'dict[str, Any] | None' = None,
    hover_features: 'list[str] | None' = None
) -> PhenoMeInteractive

Launch an interactive explorer for phenotyping results in Jupyter.

Creates a :class:PhenoMeInteractive instance and displays it. Use in Jupyter notebooks to explore embeddings via PCA/t-SNE/UMAP with instant color switching, highlight mode, box/lasso multi-selection, and click-to-inspect image viewing.

Args:

  • pheno_me: Processed PhenoMe instance with embeddings and optional properties. Must have run process_images() first.
  • filters: Optional metadata filters to restrict which images are shown. Dict mapping metadata keys to allowed values or lists of values. Example: {'condition': 'Control', 'time': ['24h', '48h']}.
  • exclude: Optional metadata exclusions (same structure as filters).
  • hover_features: Optional list of metadata or property keys to show in hover tooltips. If None, uses metadata keys from the pipeline. For Google Colab, use create_colab_interactive_explorer.

Returns:

  • PhenoMeInteractive: The explorer instance. Call .show() again to re-display.

Example:

>>> from phenome import PhenoMe, load_dinov2_model
>>> wrapper = load_dinov2_model()
>>> pheno = PhenoMe(seed=42)
>>> pheno.find_files("data/")
>>> pheno.process_images(wrapper)
>>> explorer = pheno.create_interactive_explorer(
...     filters={'condition': 'Treatment'},
...     hover_features=['drug', 'area', 'eccentricity'],
... )

Colab

Section titled “Colab”

create_colab_interactive_explorer

Section titled “create_colab_interactive_explorer”
create_colab_interactive_explorer(
    pheno_me: '_InteractiveExplorerProtocol',
    filters: 'dict[str, Any] | None' = None,
    exclude: 'dict[str, Any] | None' = None
) -> ColabInteractiveExplorer

Launch the interactive explorer built only for Google Colab.

Shows Embedding and Appearance controls, an SVG scatter of the embedding, and the image for a clicked point. Highlight, box/lasso selection, and filter editors are not included. filters and exclude still restrict which images are reduced when Compute is pressed.

Local Jupyter notebooks should use :func:create_interactive_explorer. That explorer is not adapted for Colab.

Widget updates run inside the button and click callbacks. Colab does not show updates made from a background thread.

Args:

  • pheno_me: Processed PhenoMe instance with embeddings. Must have run process_images() first.
  • filters: Optional metadata filters. Dict mapping metadata keys to allowed values or lists of values.
  • exclude: Optional metadata exclusions (same structure as filters).

Returns:

The explorer. Call .show() again to re-display it.

Example:

>>> explorer = pheno.create_colab_interactive_explorer()

Class PhenoMeInteractive

Section titled “Class PhenoMeInteractive”

High-performance interactive explorer for PhenoMe results.

Optimized for large datasets using WebGL and efficient data handling. Provides a unified interface for 2D/3D exploration with:

  • Instant colour switching (no recomputation).

  • Highlight mode (shows all points, emphasises a subset).

  • Multi-select categorical highlight and live stats bar.

  • Click-to-inspect image viewer.

  • 2D box/lasso selection with CSV export of selected rows in the Selection section (Plotly modebar: pan, zoom, box/lasso, PNG).

    Key design:

    • Color changes are instant (no recomputation, only visual update).
    • Filter and Exclude (separate collapsible sections under Embedding) restrict data before recomputation; same field + search + multi-select pattern as Highlight.
    • Method/Source/Dim or metadata filter changes trigger dimensionality reduction (expensive).
    • Highlight mode shows ALL data points but visually emphasises a matching subset (translucent halo + dimmed non-matching points) instead of hiding the rest. This lets the user “find” a group in context.
    • Multi-value highlight: categorical fields use filter + multi-select (OR).
    • Live stats bar (total / highlighted / selected / lasso-box).
    • Selected point: clicking a point shows a black ring (hollow marker) for inspection.

  • Multi-selection: box / lasso on the 2D plot stores a persistent set of image indices; the side panel shows a thumbnail grid (single-click traceback + image id, double-click full view with back to grid).

Interactive exploration

Section titled “Interactive exploration”
Method

set_filters

PhenoMeInteractive.set_filters(
    self,
    filters: 'dict | None' = None,
    exclude: 'dict | None' = None
) -> None

Programmatically update the metadata filters and exclusions and recompute.

Since filters/exclude change the data subset, this triggers a full recomputation.

Method

close

PhenoMeInteractive.close(
    self
) -> None

Cancel pending debounce timers (call before discarding the explorer).

Method

show

PhenoMeInteractive.show(
    self
) -> None

Display the interactive dashboard.

Only one widget tree stays visible. Jupyter clears the cell output before the new dashboard is displayed.