LandmarksWidget API¶

Reference for milume.peek and the synced widget handle it returns. For a walkthrough, see Quickstart.

`milume.peek`¶

Open a Milume surface on AnnData or SpatialData. This is the main notebook entry point; it constructs LandmarksWidget with the same keyword arguments.

import milume

w = milume.peek(adata, color="cell_type")
w = milume.peek(sdata)  # table, labels, image inferred

Returns a LandmarksWidget handle. Synced traitlets include w.selections and w.landmarks; join to adata with get_obs_names / assign_obs_mask.

Constructor parameters¶

Parameters¶

data, adata — AnnData with spatial coordinates, or SpatialData (volume inferred). milume.peek names this argument data; LandmarksWidget names the same argument adata.
spatial_key — obsm key for x/y coordinates (default "spatial").
color — obs column or var_names gene for point colour. When omitted, the first detected categorical column is used.
genes — Genes to pack for view-only colouring. None (default) packs every var_name; pass a name or list to restrict the eager catalog.
table, image, labels — SpatialData-only overrides for the inferred table, multiscale image, and labels layer.
contrast_limits — SpatialData-only image contrast (min, max) for the Inspect cube.

Notes¶

The widget keeps a reference to adata (no obs.copy(), no full-X densify at construct). Chrome follows the notebook cell width; height starts at 720px and is resizable. Marker radius comes from median nearest-neighbor distance. Neighbourhood expand runs in the browser from coordinates; no obsp graphs are required.

UI chrome (mode, neighbourhoods, raster controls) stays in the browser and is not part of the notebook API. Raster bins and probe scores are built client-side from the eager gene, embedding, and category packs.

Synced traitlets¶

These traitlets sync between Python and the browser. UI-only chrome (modes, sliders, undoredo) is not listed.

Selection & landmarks¶

Name	Type	Default	Meaning
`selections`	List[Dict]	`[]`	Region dicts; join to adata via `get_obs_names` / `assign_obs_mask`.
`landmarks`	List[Dict]	`[]`	Committed landmark annotations (round-trip with GeoDataFrame helpers).
`selected_kind`	str	`""`	Active item kind (`""` when none).
`selected_index`	int	`-1`	Index of active selection or landmark (`-1` when none).
`selected_type_indices`	List[Int]	`[]`	Legend indices for multi type focus when kind is `type`.

Inspect (SpatialData)¶

Name	Type	Default	Meaning
`inspect_cx`	float	`None`	Inspect cube centre X (µm); `None` until placed.
`inspect_cy`	float	`None`	Inspect cube centre Y (µm); `None` until placed.
`inspect_size_um`	float	`300.0`	Inspect window side length (µm; 300 µm square).
`volume`	dict	—	SpatialData Inspect cube config (Python-set).
`volume_cut`	List[Float]	`[]`	µm cut box; browser writes on slider release.

View & coloring¶

Name	Type	Default	Meaning
`active_category`	str	`""`	Category column mirrored from colour chrome.
`active_genes`	List[Unicode]	`[]`	View-only gene picks mirrored from chrome.

Advanced synced fields¶

Usually driven from notebook methods (set_render_mode, set_raster_basis, …) or browser chrome; documented for debugging and extensions.

Raster & render mode¶

Name	Type	Default	Meaning
`render_mode`	str	`"points"`	points \| raster
`raster_bin_size`	float	`0.0`	Synced widget state.
`raster_window_radius`	float	`0.0`	Synced widget state.
`raster_basis`	str	`"composition"`	genes \| embedding \| composition
`raster_embedding_key`	str	`""`	Synced widget state.
`raster_embedding_keys`	List[Unicode]	`[]`	Synced widget state.
`raster_embedding_dims`	List[Int]	`[]`	Synced widget state.
`raster_obs_key`	str	`""`	Synced widget state.
`raster_gene_mode`	str	`"active"`	Synced widget state.
`raster_origin_x`	float	`0.0`	Synced widget state.
`raster_origin_y`	float	`0.0`	Synced widget state.
`raster_n_cols`	int	`0`	Synced widget state.
`raster_n_rows`	int	`0`	Synced widget state.
`raster_n_bins`	int	`0`	Synced widget state.
`raster_bin_rows`	str	`""`	base64 int32
`raster_bin_cols`	str	`""`	Synced widget state.
`raster_bin_counts`	str	`""`	Synced widget state.
`raster_features`	str	`""`	base64 float32 row-major
`raster_feature_dim`	int	`0`	Synced widget state.
`raster_feature_labels`	List[Unicode]	`[]`	Synced widget state.
`raster_query_bin`	int	`-1`	-1 = none (pin)
`raster_similarity_enabled`	bool	`False`	Synced widget state.
`raster_threshold`	float	`0.0`	Synced widget state.
`raster_status`	str	`""`	Synced widget state.
`volume`	dict	—	SpatialData Inspect cube config (Python-set).
`volume_label_ids`	str	`""`	base64 int32, table order
`volume_cut`	List[Float]	`[]`	µm cut box; browser writes on slider release.

GeoDataFrame interchange¶

Convert w.landmarks to a durable GeoPandas table (and back). Control vertices live in a JSON vertices column; geometry is a GIS proxy. The widget does not own SpatialData — assign sdata['landmarks'] = gdf in the notebook if needed.

Requires optional geopandas and shapely.

`landmarks_to_geodataframe()`¶

def landmarks_to_geodataframe(landmarks: list[dict] | None)

Convert widget landmark dicts to a GeoDataFrame.

Parameters¶

landmarks — Landmark dicts from w.landmarks, or None / [] for an empty frame with contract columns (id, type, vertices, …).

Returns¶

geopandas.GeoDataFrame — Proxy geometry plus JSON vertices as the round-trip source of truth. Callers assign into SpatialData themselves (e.g. sdata["landmarks"] = gdf).

Examples¶

import milume
w = milume.peek(adata)
gdf = milume.landmarks_to_geodataframe(w.landmarks)
len(gdf)

0

`geodataframe_to_landmarks()`¶

def geodataframe_to_landmarks(gdf)

Convert a landmarks GeoDataFrame back to widget dicts.

Parameters¶

gdf — GeoDataFrame produced by landmarks_to_geodataframe, or None / zero rows.

Returns¶

list[dict] — Widget landmark dicts suitable for w.landmarks = .... Empty input yields [].

Examples¶

import milume
w = milume.peek(adata)
w.landmarks = milume.geodataframe_to_landmarks(

... milume.landmarks_to_geodataframe(w.landmarks) ... )

Methods¶

Notebook helpers on the widget handle returned by milume.peek.

`set_points()`¶

def set_points(x: Any, y: Any, *, color: Any = None, color_map: dict[str, str] | None = None, legend_title: str | None = None, continuous_range: tuple[str, str] | None = None) -> None

Replace scatter points/colors.

`set_expression()`¶

def set_expression(expr: Any) -> None

Replace the eager gene catalog/matrix from a table (view-only).

Packs all columns immediately for the browser gene picker.

`set_render_mode()`¶

def set_render_mode(mode: str) -> None

Switch canvas between point scatter and spatial raster bins.

`set_raster_basis()`¶

def set_raster_basis(*, genes: str | None = None, embedding: str | None = None, composition: str | None = None) -> None

Select bin aggregation basis (genes / embedding / composition).

Pathway / obs score columns are deferred (plan slice A); use raster_obs_key later via the same mean-into-bin path.

Bin feature matrices are built in the browser; this only updates traits.

`clear_raster_query()`¶

def clear_raster_query() -> None

Clear the pinned similarity query bin.

`set_color()`¶

def set_color(color: Any, *, color_map: dict[str, str] | None = None, legend_title: str | None = None, continuous_range: tuple[str, str] | None = None) -> None

Update point colors without changing x/y.

`category_colors()`¶

def category_colors(column: str | None = None) -> dict[str, str]

Label -> hex colour of a categorical column, as the map draws it.

Defaults to the active category. Use it to colour other views (plots, the cube) the same way as the points.

`clear_selections()`¶

def clear_selections() -> None

Remove every selection from the widget.

`clear_landmarks()`¶

def clear_landmarks() -> None

Remove every landmark from the widget.

`clear()`¶

def clear() -> None

Remove all selections and landmarks.

`select_type()`¶

def select_type(index: int) -> None

Focus one category group in the active set (replaces a multi-select union).

The browser may set selected_type_indices to several groups; this helper is the notebook path for single-group focus without fighting front-end sync.

`get_focus_obs_names()`¶

def get_focus_obs_names(adata: Any, *, spatial_key: str = 'spatial') -> 'np.ndarray'

obs_names for the current type or selection focus (multi-type union).

`get_obs_names()`¶

def get_obs_names(adata: Any = None, selection_id: str | None = 'all', *, spatial_key: str = 'spatial') -> 'np.ndarray'

obs_names of cells inside selection_id (durable join key).

Uses selection_mask (geometry or stored point_indices). Neighborhood expand is client-side; promote freezes membership into point_indices before syncing.

With no adata the widget's own coordinates and names are used, so the result cannot depend on which spatial_key you pass.

`assign_obs_mask()`¶

def assign_obs_mask(adata: Any, key: str, selection_id: str | None = 'all', *, spatial_key: str = 'spatial') -> None

Write a boolean column on adata.obs for the current selection.

LandmarksWidget API¶

milume.peek¶

Constructor parameters¶

Parameters¶

Notes¶

Synced traitlets¶

Selection & landmarks¶

Inspect (SpatialData)¶

View & coloring¶

Advanced synced fields¶

Raster & render mode¶

GeoDataFrame interchange¶

landmarks_to_geodataframe()¶

Parameters¶

Returns¶

Examples¶

geodataframe_to_landmarks()¶

Parameters¶

Returns¶

Examples¶

Methods¶

set_points()¶

set_expression()¶

set_render_mode()¶

set_raster_basis()¶

clear_raster_query()¶

set_color()¶

category_colors()¶

clear_selections()¶

clear_landmarks()¶

clear()¶

select_type()¶

get_focus_obs_names()¶

get_obs_names()¶

assign_obs_mask()¶

`milume.peek`¶

`landmarks_to_geodataframe()`¶

`geodataframe_to_landmarks()`¶

`set_points()`¶

`set_expression()`¶

`set_render_mode()`¶

`set_raster_basis()`¶

`clear_raster_query()`¶

`set_color()`¶

`category_colors()`¶

`clear_selections()`¶

`clear_landmarks()`¶

`clear()`¶

`select_type()`¶

`get_focus_obs_names()`¶

`get_obs_names()`¶

`assign_obs_mask()`¶