EmbeddingAtlas
The embedding-atlas
package contains a component for the entire frontend user interface of Embedding Atlas.
npm install embedding-atlas
To use the React wrapper:
import { EmbeddingAtlas } from "embedding-atlas/react";
let coordinator: Coordinator; // The Mosaic coordinator.
<EmbeddingAtlas
coordinator={coordinator}
data={{
table: "data_table",
id: "id_column",
projection: { x: "x_column", y: "y_column" },
text: "text_column"
}}
...
/>
To use the Svelte wrapper:
import { EmbeddingAtlas } from "embedding-atlas/svelte";
let coordinator: Coordinator; // The Mosaic coordinator.
<EmbeddingAtlas
coordinator={coordinator}
data={{
table: "data_table",
id: "id_column",
projection: { x: "x_column", y: "y_column" },
text: "text_column"
}}
...
/>
If your application does not use React or Svelte, you may directly construct the component:
import { EmbeddingAtlas } from "embedding-atlas";
let coordinator: Coordinator; // The Mosaic coordinator.
let target = document.getElementById("container");
let props = {
coordinator: coordinator,
data: {
table: "data_table",
id: "id_column",
projection: { x: "x_column", y: "y_column" },
text: "text_column"
},
// ...
};
// Create and mount the component
let component = new EmbeddingAtlas(target, props);
// Update with new props
component.update(newProps);
// Destroy the component
component.destroy();
Properties
The view can be configured with the following properties (props):
coordinator Coordinator
Required. The Mosaic coordinator.
data { table: string; id: string; projection?: { x: string; y: string; } | null; neighbors?: string | null; text?: string | null; }
Required. The data source.
table string
Required. The name of the data table.
id string
Required. The column for unique row identifiers.
projection { x: string; y: string; } | null
The X and Y columns for the embedding projection view.
neighbors string | null
The column for pre-computed nearest neighbors. Each value in the column should be a dictionary with the format: { "ids": [id1, id2, ...], "distances": [distance1, distance2, ...] }
. "ids"
should be an array of row ids (as given by the idColumn
) of the neighbors, sorted by distance. "distances"
should contain the corresponding distances to each neighbor. Note that if searcher.nearestNeighbors
is specified, the UI will use the searcher instead.
text string | null
The column for text. The text will be used as content for the tooltip and search features.
colorScheme "light" | "dark" | null
The color scheme.
initialState EmbeddingAtlasState | null
The initial viewer state.
embeddingViewConfig EmbeddingViewConfig | null
Configuration for the embedding view. See docs for the EmbeddingView.
embeddingViewLabels Label[] | null
Labels for the embedding view.
searcher Searcher | null
An object that provides search functionalities, including full text search, vector search, and nearest neighbor queries. If not specified (undefined), a default full-text search with the text column will be used. If set to null, search will be disabled.
tableCellRenderers Record<string, CustomCell | "markdown">
Custom cell renderers for the table view.
onExportSelection ((predicate: string | null, format: "json" | "jsonl" | "csv" | "parquet") => Promise<void>) | null
A callback to export the currently selected points.
onExportApplication (() => Promise<void>) | null
A callback to download the application as archive.
onStateChange ((state: EmbeddingAtlasState) => void) | null
A callback when the state of the viewer changes. You may serialize the state to JSON and load it back.
cache Cache | null
A cache to speed up initialization of the viewer.
State
The EmbeddingAtlasState
interface describes the state of the Embedding Atlas UI.
You may set initialState
to a previously-saved state value to reload the UI to its previous state.
Properties of the state:
version string
Required. The version of Embedding Atlas that created this state.
timestamp number
Required. UNIX timestamp when this was created.
view any
The view configuration and state of the embedding view.
plots { id: string; title: string; spec: any; }[]
The list of plots.
plotStates Record<string, any>
The state of all plots.
predicate string | null
The selection predicate (SQL expression).