Bioptimus SDK

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. The Bioptimus SDK talks to whichever model is deployed at the endpoint you connect to. Backbone.available_backbones() lists the models the Bioptimus SDK knows how to build (h1, m-optimus, tissue-seg) — to see what a server actually has loaded, check its /ping response.

Installation

PyPI
Python Wheel

pip install bioptimus-sdk

pip install bioptimus_sdk-<version>-py3-none-any.whl

Two ways to use it

Inference pipeline (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
from bioptimus.models.types import Models

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

from bioptimus.models.backbones import Backbone
from bioptimus.models.types import Models

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

from bioptimus.models.backbones import Backbone
from bioptimus.models.types import Models

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

from bioptimus.models.backbones import Backbone
from bioptimus.models.types import 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).

Server not responding? Check /ping first

Before constructing a Backbone (or an Inference pipeline), confirm the on-premise server is reachable:

import requests

requests.get("http://localhost:8080/ping", timeout=5).json()
# {"status": "ok", "models": ["h1", "tissue-seg"]}

If this raises ConnectionError / connection refused or times out, nothing is serving at that URL:

Not started — launch the container, mapping port 8080, then wait for models to load. See On-premise deployment:
docker run -d --name bioptimus-server --gpus all -p 8080:8080 <image> serve
503 {"status": "loading"} — models are still initialising; wait and retry.
Wrong URL/port — base_url (and the pipeline’s api_url) must be the server’s host and port, with no trailing /ping.

For SageMaker there is no /ping: confirm the endpoint is InService and that endpoint_name / region_name are correct.

Guides

Inference pipeline

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.

Tile embeddings & PCA

Extract embeddings and visualize morphology.

WSI processing

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

Every output file contains the same contents:

Datasets: outputs, coords, tissue_ratios, thumbnail, tissue_mask — plus input_gene_names and output_gene_names for M-Optimus.
Metadata attributes: slide_name, tile_size, stride, mpp, slide_dimensions, slide_dimensions_at_mpp, num_tiles.

See Visualizing results to load and plot them.

Overview

Get Started

Preprocessing

Workflows

Reference

Installation

Two ways to use it

Inference pipeline (recommended)

Core API (advanced)

Connecting to a model

Guides

Inference pipeline

Cohorts

Spatial transcriptomics

Tile embeddings & PCA

WSI processing

Visualizing results

Output formats

​Installation

​Two ways to use it

Inference pipeline (recommended)

Core API (advanced)

​Connecting to a model

​Guides

Inference pipeline

Cohorts

Spatial transcriptomics

Tile embeddings & PCA

WSI processing

Visualizing results

​Output formats

Installation

Two ways to use it

Connecting to a model

Guides

Output formats