Visualizing results

Inference outputs are written as Zarr (default), HDF5, or NPZ — all three carry the same datasets under the same keys.

Figures in this documentation are real model outputs on open-access TCGA slides (e.g. TCGA-75-7027), shown as representative examples — not benchmarks. See Responsible use → Data attribution.

Load an output file

Load a Zarr output with the built-in helper; it returns the arrays and metadata as a dict.

from bioptimus import utils

data = utils.load_zarr_output(result_path)
preds, coords = data["outputs"], data["coords"]
gene_names = data.get("gene_names")   # M-Optimus gene predictions only; None for embeddings

load_zarr_output returns the following datasets (plus a metadata dict). Optional entries are present only when the model and pipeline produce them:

Key	Shape	Description
`outputs`	`(n_tiles, D)`	Per-tile embeddings (`D` = 1536) or gene predictions (`D` = number of output genes).
`coords`	`(n_tiles, 2)`	Pixel `(x, y)` location of each tile on the slide.
`gene_names`	`(D,)`	Output gene identifiers (M-Optimus only).
`thumbnail`	`(H, W, 3)`	Downsampled RGB slide overview.
`tissue_mask`	`(H, W)`	Boolean tissue-vs-background mask.
`tissue_ratios`	`(n_tiles,)`	Fraction of each tile covered by tissue.

Metadata attributes include slide_dimensions, slide_dimensions_at_mpp, tile_size, mpp, and num_tiles. HDF5 (.h5) and NPZ (.npz) outputs expose the same keys via h5py and np.load(allow_pickle=True).

Plot with the built-in helpers

The helpers below visualize M-Optimus gene predictions and require the gene_names returned above. For H-Optimus tile embeddings (no gene_names), see Tile embeddings & PCA.

bioptimus.utils ships the plotting helpers used in the getting-started notebooks. Heatmap overlays and single-gene overlays are all covered by the spatial gene panel helper below — pass a single-entry GENE_PANEL for one gene — so there’s no need to hand-roll matplotlib.

Spatial gene panel

Overlay one or more genes on the slide thumbnail in one call.

GENE_PANEL = {
    "EPCAM":  "ENSG00000119888",   # epithelium / tumor
    "CD3E":   "ENSG00000198851",   # T-cells
    "CD8A":   "ENSG00000153563",   # cytotoxic T-cells
    "MKI67":  "ENSG00000148773",   # proliferation
    "COL1A1": "ENSG00000108821",   # stroma
    "SFTPC":  "ENSG00000168484",   # alveolar (lung)
}
utils.plot_gene_panel_overlay(preds, coords, gene_names, GENE_PANEL,
                              wsi_path=wsi_path, cols=3, cmap="inferno")

Spatial gene-expression panel overlaid on a slide thumbnail — Predicted spatial expression for a six-gene panel on a TCGA-LUAD slide (TCGA-75-7027), M-Optimus with bulk-RNA context.

Image-only vs. bulk-RNA-guided

Compare the same gene predicted with and without bulk RNA context.

gene_idx = gene_names.index("ENSG00000119888")   # EPCAM
utils.plot_gene_overlay_comparison(
    preds_bulk, coords_bulk, preds_image_only, coords_image_only,
    gene_idx=gene_idx, wsi_path=wsi_path, gene_name="EPCAM",
    label_a="With bulk RNA", label_b="Without bulk RNA (image only)",
)

Side-by-side EPCAM overlay: with bulk RNA vs image only — EPCAM predicted from H&E with vs. without bulk RNA (TCGA-LUAD TCGA-75-7027). Bulk RNA sharpens the epithelial signal without retraining.

Highest- and lowest-expressing tiles

Pull the tiles driving a gene’s prediction for quick visual QC.

utils.plot_top_gene_tiles(preds, coords, gene_idx=gene_idx,
                          wsi_path=wsi_path, gene_name="EPCAM",
                          n_top=6, n_bottom=6)

Grid of tiles with highest and lowest predicted EPCAM expression — Tiles with the highest and lowest predicted EPCAM expression (TCGA-LUAD TCGA-75-7027).

Overview

Get Started

Preprocessing

Workflows

Reference

Load an output file

Plot with the built-in helpers

Spatial gene panel

Image-only vs. bulk-RNA-guided

Highest- and lowest-expressing tiles

​Load an output file

​Plot with the built-in helpers

​Spatial gene panel

​Image-only vs. bulk-RNA-guided

​Highest- and lowest-expressing tiles

Load an output file

Plot with the built-in helpers

Spatial gene panel

Image-only vs. bulk-RNA-guided

Highest- and lowest-expressing tiles