SDK overview - Bioptimus Documentation

The bioptimus Python SDK runs whole-slide inference against either an on-premise server or a SageMaker endpoint. It handles WSI reading, tiling, tissue masking, bulk-RNA alignment, and concurrent dispatch.

Installation

Python wheel (current)
pip (index)

pip install ./bioptimus-<version>-py3-none-any.whl

pip install bioptimus==<version>

Two ways to use it

Inference facade (recommended)

One object configures the whole pipeline. Caches tissue masks, organizes outputs into a workspace, and is reproducible. Best for most users and for cohorts.

Core API (advanced)

Backbone + SlideInference give explicit, per-slide control over the model client, mask provider, and writer.

Connecting to a model

The Backbone factory is the low-level client used by both layers.

On-premise
AWS SageMaker

from bioptimus.models.backbones import Backbone, Models

print(Backbone.available_backbones())   # H1: ['h1', 'tissue-seg']
model = Backbone(Models.H1, backend="remote", base_url="http://localhost:8080")

from bioptimus.models.backbones import Backbone, Models

model = Backbone(
    Models.M_OPTIMUS, backend="aws",
    endpoint_name="m-optimus", region_name="us-east-1",
)

For M-Optimus, gene sets are fetched from the server automatically (model.input_gene_names, model.output_gene_names).

Guides

Inference facade

One-object pipeline, workspaces, reproducible config.

Cohorts

Multi-slide cohorts and late-binding bulk RNA.

Spatial transcriptomics

M-Optimus gene-expression prediction end to end.

H1 embeddings & PCA

Extract embeddings and visualize morphology.

WSI reader

Read slides: levels, MPP, regions, thumbnails.

Visualizing results

Load Zarr/HDF5/NPZ and overlay genes and masks.

Output formats

Format	Extension	Notes
`OutputFormat.ZARR`	`.zarr`	Default. Directory store, memory-efficient
`OutputFormat.HDF5`	`.h5`	Single file, memory-efficient
`OutputFormat.NPZ`	`.npz`	Accumulates in memory, compressed on close

Outputs contain outputs, coords, tissue_ratios, thumbnail, tissue_mask, and (for M-Optimus) input_gene_names / output_gene_names, plus metadata attributes (slide_name, tile_size, stride, mpp, slide_dimensions, slide_dimensions_at_mpp, num_tiles). See Visualizing results.

​Installation

​Two ways to use it