Skip to main content
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, gene_names = data["outputs"], data["coords"], data["gene_names"]
load_zarr_output returns outputs (n_tiles, D), coords (n_tiles, 2), and metadata, plus — when present — gene_names, thumbnail, tissue_mask, and tissue_ratios. HDF5 (.h5) and NPZ (.npz) outputs expose the same keys via h5py and np.load(allow_pickle=True).

​
Plot with the built-in helpers

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

​
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

​
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