milume

A thinking surface for spatial omics.

Layer images, cells, and transcripts in one reactive notebook widget.

You have a spatial dataset and a hunch. milume turns a notebook cell into a tactile, reactive surface where you can look at your tissue, select what catches your eye, and carry that selection straight into code. Cells, landmarks and measurements stay in plain AnnData / obs_names / geometry, so what you see on the surface is what you analyze next.

One call opens it:

import milume

w = milume.peek(adata, color="cell_type")

Draw selections and landmarks, color by category or gene, expand neighborhoods, and read everything back in Python. The name comes from mille (thousand, as in mille-feuille, layers) + lume (light).

Contents

• Install
• Alongside other viewers
• API

Install

pip install milume

With uv:

uv add milume

Contributors: see AGENTS.md for dev setup.

Migrate from spatial-rx

Note: Milume was formerly spatial-rx. The API is unchanged; only the names moved:

pip uninstall spatial-rx
pip install milume

import milume   # was: import spatial_rx

Alongside other viewers

Milume complements other viewers. Use milume to form intuition: layer images, cells, and transcripts in a notebook, select what stands out, and carry the selection straight into your analysis code. Use heavier viewers when you need to inspect in depth. Landmarks and selections round-trip as plain geometry and obs_names, so you can hand the same regions to any viewer.

API

milume.peek(data, **kwargs) opens the surface on your data and returns a widget w you read results from. Full widget guide and generated API reference: docs site.

import milume

w = milume.peek(adata, color="cell_type")   # AnnData with obsm["spatial"]
w = milume.peek(sdata, color="cell_type")   # SpatialData on disk: adds the 3D cube

milume.peek works on AnnData and on-disk SpatialData (including Pyxa-backed mosaics). For Xenium, Atera, CosMx, and other readers, see Other platforms below and the LandmarksWidget guide on the docs site.

Other platforms

Read with spatialdata-io as usual. Xenium and Atera work with defaults (obsm["spatial"] is the cell position in global coordinates). CosMx puts FOV-local pixels in obsm["spatial"]; use global coordinates instead:

import spatialdata_io as sio
import milume

w = milume.peek(sio.cosmx(path), spatial_key="global")

• From a SpatialData, the widget finds the table, the labels element it annotates, a 3D image on the same grid, and their µm frame (override with table=, image=, labels=; contrast_limits= for the image).
• Press I (Inspect): the top toolbar turns into a dashed Inspect pill, hovering shows a live coarse preview of the tissue under the cursor, and a click places a 300 µm window; on release a full-resolution cube of it takes over the plot area, cells drawn as outlines colored like the map, with your landmarks on top. Shift+drag in the cube (or the Move tool) slides the window across the tissue; a plain drag orbits. The bottom bar holds the camera, Adjust (image and label display) and Cross-section (cuts). Esc closes the cube; Esc again, or ×, leaves Inspect. The side panels' peek tabs stay over the cube, so you can focus a category or Selection to color it.
• Save window on the Inspect pill adds the window as an inspect selection, listed in the Selections panel with a thumbnail and named by its main category and size (e.g. Epithelial · 214); hover a row for its cell count and category mix, click it to reopen the window. Read the inspected cells back with w.get_obs_names(adata, "<inspect id>") or w.selections.
• Hold Space to pan in any tool.

Read results back in Python:

Large expression matrices are sent sparse; pass genes= to limit the gene catalog.