> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Visualizing results
> Load Zarr/HDF5/NPZ outputs and overlay gene expression or tissue masks.
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](/documentation/resources/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.
```python theme={null}
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](https://github.com/bioptimus/m-jumpstart). Heatmap overlays and single-gene overlays are all covered by the [spatial gene panel](#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.
```python theme={null}
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")
```
### Image-only vs. bulk-RNA-guided
Compare the same gene predicted with and without bulk RNA context.
```python theme={null}
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)",
)
```
### Highest- and lowest-expressing tiles
Pull the tiles driving a gene's prediction for quick visual QC.
```python theme={null}
utils.plot_top_gene_tiles(preds, coords, gene_idx=gene_idx,
wsi_path=wsi_path, gene_name="EPCAM",
n_top=6, n_bottom=6)
```
