Skip to main content

aip_sdk.embedding_explorer

Interactive embedding scatter explorer for notebooks and scripts.

Build an EmbeddingExplorer from local compute() results or from a completed platform run's coordinates, then call EmbeddingExplorer.panel() in Jupyter or EmbeddingExplorer.write_html() for static exports.

Requires the viz optional extra (pip install 'aip-sdk[viz]') for plotting and interactive lasso selection (plotly, ipywidgets, anywidget). Reading coordinates and building explorer frames needs only pandas; the embeddings extra is required for from_pipeline_output() only.

aip_sdk.embedding_explorer.CATEGORICAL_COLOR_COLUMNS​

aip_sdk.embedding_explorer.CATEGORICAL_COLOR_COLUMNS = ('source', 'scenario', 'image_id', 'input_id', 'intent', 'object_class', 'label')

No docstring is defined in the source.

aip_sdk.embedding_explorer.COLOR_SKIP_COLUMNS​

aip_sdk.embedding_explorer.COLOR_SKIP_COLUMNS = frozenset({'x', 'y', 'row_idx', 'pipeline_id', 'trustworthiness', 'cluster'})

No docstring is defined in the source.

aip_sdk.embedding_explorer.EmbeddingExplorer​

aip_sdk.embedding_explorer.EmbeddingExplorer(frames_by_pipeline: dict[str, pd.DataFrame], diagnostics_by_pipeline: dict[str, PipelineDiagnostics], row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None)

Plot-ready frames and pipeline metadata for every succeeded layout.

aip_sdk.embedding_explorer.EmbeddingExplorer.diagnostics_by_pipeline​

aip_sdk.embedding_explorer.EmbeddingExplorer.diagnostics_by_pipeline: dict[str, PipelineDiagnostics]

No docstring is defined in the source.

aip_sdk.embedding_explorer.EmbeddingExplorer.frames_by_pipeline​

aip_sdk.embedding_explorer.EmbeddingExplorer.frames_by_pipeline: dict[str, pd.DataFrame]

No docstring is defined in the source.

aip_sdk.embedding_explorer.EmbeddingExplorer.gallery_preamble_html​

aip_sdk.embedding_explorer.EmbeddingExplorer.gallery_preamble_html: str | None = None

No docstring is defined in the source.

aip_sdk.embedding_explorer.EmbeddingExplorer.panel​

aip_sdk.embedding_explorer.EmbeddingExplorer.panel(*, default_embedding_id: str | None = None) -> Any

Return the ipywidgets Embedding x Colour by explorer.

aip_sdk.embedding_explorer.EmbeddingExplorer.row_preview​

aip_sdk.embedding_explorer.EmbeddingExplorer.row_preview: RowPreviewFn | None = None

No docstring is defined in the source.

aip_sdk.embedding_explorer.EmbeddingExplorer.show​

aip_sdk.embedding_explorer.EmbeddingExplorer.show(*, default_embedding_id: str | None = None) -> Any

Display the explorer panel in the active Jupyter kernel.

aip_sdk.embedding_explorer.EmbeddingExplorer.write_html​

aip_sdk.embedding_explorer.EmbeddingExplorer.write_html(out_dir: str | Path) -> None

Write one static scatter per pipeline (default colour + clusters).

aip_sdk.embedding_explorer.FrameSource​

aip_sdk.embedding_explorer.FrameSource = Callable[[], pd.DataFrame] | pd.DataFrame

No docstring is defined in the source.

aip_sdk.embedding_explorer.GALLERY_ROW_CAP​

aip_sdk.embedding_explorer.GALLERY_ROW_CAP = 50

No docstring is defined in the source.

aip_sdk.embedding_explorer.NUMERIC_SAMPLE_CAP​

aip_sdk.embedding_explorer.NUMERIC_SAMPLE_CAP = 100

No docstring is defined in the source.

aip_sdk.embedding_explorer.NumericSampleValue​

aip_sdk.embedding_explorer.NumericSampleValue = float | tuple[float, float]

No docstring is defined in the source.

aip_sdk.embedding_explorer.PipelineDiagnostics​

aip_sdk.embedding_explorer.PipelineDiagnostics(pipeline_id: str, supervised: bool, supervision_column: str | None, trustworthiness: float | None)

Per-pipeline metadata consumed by the explorer UI.

aip_sdk.embedding_explorer.PipelineDiagnostics.from_embedding_pipeline​

aip_sdk.embedding_explorer.PipelineDiagnostics.from_embedding_pipeline(pipeline: EmbeddingPipeline) -> PipelineDiagnostics

Create diagnostics from an embedding pipeline.

Parameters

Returns

aip_sdk.embedding_explorer.PipelineDiagnostics.from_pipeline_result​

aip_sdk.embedding_explorer.PipelineDiagnostics.from_pipeline_result(result: PipelineResult) -> PipelineDiagnostics

Create diagnostics from a pipeline execution result.

Parameters

  • result PipelineResult: The pipeline result to extract metadata from.

Returns

aip_sdk.embedding_explorer.PipelineDiagnostics.pipeline_id​

aip_sdk.embedding_explorer.PipelineDiagnostics.pipeline_id: str

No docstring is defined in the source.

aip_sdk.embedding_explorer.PipelineDiagnostics.supervised​

aip_sdk.embedding_explorer.PipelineDiagnostics.supervised: bool

No docstring is defined in the source.

aip_sdk.embedding_explorer.PipelineDiagnostics.supervision_column​

aip_sdk.embedding_explorer.PipelineDiagnostics.supervision_column: str | None

No docstring is defined in the source.

aip_sdk.embedding_explorer.PipelineDiagnostics.trustworthiness​

aip_sdk.embedding_explorer.PipelineDiagnostics.trustworthiness: float | None

No docstring is defined in the source.

aip_sdk.embedding_explorer.RowPreviewFn​

aip_sdk.embedding_explorer.RowPreviewFn = Callable[[pd.Series], str]

No docstring is defined in the source.

aip_sdk.embedding_explorer.color_options​

aip_sdk.embedding_explorer.color_options(frame: pd.DataFrame, pipeline_id: str) -> dict[str, str]

Colour-by choices aligned with the platform Slices tab (§5.1).

aip_sdk.embedding_explorer.customdata_columns​

aip_sdk.embedding_explorer.customdata_columns(frame: pd.DataFrame, *, limit: int = 16, ensure: tuple[str, ...] = ()) -> list[str]

Plotly-safe hover columns — excludes byte buffers that break write_html.

Parameters

  • frame pd.DataFrame: Plot-ready explorer frame.
  • limit int: Maximum number of hover columns, including row_idx.
  • ensure tuple[str, ...]: Column names that must appear when JSON-safe (e.g. the active colour).

Returns

  • list[str]: Ordered column names safe for Plotly customdata encoding.

aip_sdk.embedding_explorer.default_color_for_embedding​

aip_sdk.embedding_explorer.default_color_for_embedding(pipeline_id: str, frame: pd.DataFrame, diagnostics: dict[str, PipelineDiagnostics]) -> str

Sensible default colour for the active embedding layout.

aip_sdk.embedding_explorer.display_explorer​

aip_sdk.embedding_explorer.display_explorer(frame: pd.DataFrame, *, color_by: str, title: str, on_selection: Any) -> Any

Display an interactive scatter with lasso selection wired to on_selection.

aip_sdk.embedding_explorer.embedding_dropdown_options​

aip_sdk.embedding_explorer.embedding_dropdown_options(frames: dict[str, pd.DataFrame], diagnostics: dict[str, PipelineDiagnostics]) -> list[tuple[str, str]]

Embedding selector labels — unsupervised first, then score-guided metrics.

aip_sdk.embedding_explorer.export_static_scatter​

aip_sdk.embedding_explorer.export_static_scatter(frame: pd.DataFrame, path: Path, *, color_by: str, title: str) -> None

Export a scatter plot to a static HTML file.

Parameters

  • frame pd.DataFrame: Data frame containing the points to plot.
  • path Path: Path where the HTML file will be saved.
  • color_by str: Column name to use for coloring points.
  • title str: Title for the plot.

Raises

aip_sdk.embedding_explorer.format_numeric_tick​

aip_sdk.embedding_explorer.format_numeric_tick(value: float) -> str

Format a numeric axis tick the same way as the platform colour bar.

Parameters

  • value float: Numeric tick value.

Returns

  • str: A compact human-readable label.

aip_sdk.embedding_explorer.from_compute​

aip_sdk.embedding_explorer.from_compute(df: pd.DataFrame, result: EmbeddingComputeResult, *, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> EmbeddingExplorer

Build an explorer from compute() output.

aip_sdk.embedding_explorer.from_pipeline_output​

aip_sdk.embedding_explorer.from_pipeline_output(df: pd.DataFrame, output: PipelineRunOutput, *, config: EmbedProjectConfig | None = None, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> EmbeddingExplorer

Build an explorer from run_pipelines() output.

aip_sdk.embedding_explorer.from_run​

aip_sdk.embedding_explorer.from_run(run: Any, *, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> EmbeddingExplorer

Build an explorer from a completed Run.

aip_sdk.embedding_explorer.from_run_output​

aip_sdk.embedding_explorer.from_run_output(df: pd.DataFrame, coordinates: pd.DataFrame, pipelines: tuple[EmbeddingPipeline, ...], *, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> EmbeddingExplorer

Build an explorer from a run output frame and tidy coordinates.

aip_sdk.embedding_explorer.interpolate_colormap​

aip_sdk.embedding_explorer.interpolate_colormap(normalized: float, direction: _ColorDirection) -> str

Return an RGB colour for normalized in [0, 1].

Parameters

  • normalized float: Position on the unit interval.
  • direction _ColorDirection: Metric semantics; None selects the viridis-like sequential map.

Returns

  • str: An rgb(r, g, b) string aligned with the platform Slices tab.

aip_sdk.embedding_explorer.is_numeric_color_column​

aip_sdk.embedding_explorer.is_numeric_color_column(frame: pd.DataFrame, column: str) -> bool

Whether column should use a continuous colour scale.

Parameters

  • frame pd.DataFrame: Plot-ready explorer frame.
  • column str: Candidate colour column.

Returns

  • bool: True when column is numeric and not a layout-only field.
aip_sdk.embedding_explorer.make_gallery_output(get_frame: FrameSource, *, placeholder: str, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> tuple[Any, Any]

Create an interactive lasso gallery widget for exploring selected points.

Parameters

  • get_frame FrameSource: Callable that returns the current data frame.
  • placeholder str: HTML placeholder text to display when no points are selected.
  • row_preview RowPreviewFn | None: Optional function to render individual row details.
  • gallery_preamble_html str | None: Optional HTML to display above the gallery.

Returns

  • Any: A tuple of (panel_widget, selection_callback), where panel_widget is the
  • Any: widget to display and selection_callback is the event handler.

Raises

aip_sdk.embedding_explorer.make_synced_sample_browser​

aip_sdk.embedding_explorer.make_synced_sample_browser(get_frame: FrameSource, color_dropdown: Any, *, also_observe: tuple[Any, ...] = (), row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> Any

Create an interactive sample browser widget synchronized with color column selection.

Parameters

  • get_frame FrameSource: Callable that returns the current data frame.
  • color_dropdown Any: Dropdown widget for selecting the color column.
  • also_observe tuple[Any, ...]: Additional widgets to observe for changes.
  • row_preview RowPreviewFn | None: Optional function to render individual row details.
  • gallery_preamble_html str | None: Optional HTML to display above the browser.

Returns

  • Any: The sample browser widget.

Raises

aip_sdk.embedding_explorer.make_unified_explorer_panel​

aip_sdk.embedding_explorer.make_unified_explorer_panel(frames_by_pipeline: dict[str, pd.DataFrame], diagnostics_by_pipeline: dict[str, PipelineDiagnostics], *, default_embedding_id: str | None = None, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> Any

One plot with Embedding x Colour by dropdowns (platform Slices tab shape).

aip_sdk.embedding_explorer.metric_direction​

aip_sdk.embedding_explorer.metric_direction(column: str) -> _ColorDirection

Resolve the platform-style metric direction for a colour column.

Parameters

  • column str: Frame column name, optionally prefixed with llm. or cv..

Returns

  • _ColorDirection: "higher_is_better", "lower_is_better", or None for magnitude-only
  • _ColorDirection: numerics.

aip_sdk.embedding_explorer.normalize_to_unit​

aip_sdk.embedding_explorer.normalize_to_unit(value: float, minimum: float, maximum: float) -> float

Map value into [0, 1] using the observed min/max.

Parameters

  • value float: Raw metric value to normalise.
  • minimum float: Lower bound of the observed range.
  • maximum float: Upper bound of the observed range.

Returns

  • float: A unit-interval position; 0.5 when minimum equals maximum.

aip_sdk.embedding_explorer.numeric_color_bounds​

aip_sdk.embedding_explorer.numeric_color_bounds(series: pd.Series) -> tuple[float, float]

Finite min/max for a numeric colour column.

Parameters

  • series pd.Series: Values for the active colour column.

Returns

  • tuple[float, float]: Observed finite bounds, or (0.0, 1.0) when no finite values exist.

aip_sdk.embedding_explorer.plotly_colorscale​

aip_sdk.embedding_explorer.plotly_colorscale(direction: _ColorDirection) -> list[list[str | float]]

Build a Plotly colorscale aligned with the platform Slices tab.

Parameters

  • direction _ColorDirection: Metric semantics for diverging vs sequential colour maps.

Returns

  • list[list[str | float]]: A Plotly colorscale list of [position, colour] pairs.

aip_sdk.embedding_explorer.provenance_html​

aip_sdk.embedding_explorer.provenance_html(pipeline_id: str, diagnostics: PipelineDiagnostics) -> str

Caption under the plot — honest about supervised geometry when applicable.

aip_sdk.embedding_explorer.require_viz​

aip_sdk.embedding_explorer.require_viz(*, interactive: bool = False) -> None

Raise unless the viz optional dependencies are importable.

aip_sdk.embedding_explorer.selection_gallery_html(frame: pd.DataFrame, indices: list[int], *, row_preview: RowPreviewFn | None = None, gallery_preamble_html: str | None = None) -> str

Render selected rows as a grid or table.

aip_sdk.embedding_explorer.supervision_column_from_pipeline_id​

aip_sdk.embedding_explorer.supervision_column_from_pipeline_id(pipeline_id: str) -> str

Last segment of umap.drones.<column>.