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).

Getting a connection error instead of a response? See Common issues.

Recommended starting configurations

Single slide, single GPU (fastest)
Many slides (cohort)

from bioptimus.models.backbones import Backbone
from bioptimus.inference.inference import SlideInference

model = Backbone(
    "h1", backend="local",
    checkpoint=".../h1_optimus_cls_token_fp16.pt2",  # fp16
    device="cuda:0",
    max_batch_size=128,
)
inferrer = SlideInference(
    wsi_path=wsi_path, model=model,
    mask_provider=tissue_mask_provider, mask_threshold=0.5,
)
inferrer.predict(output_path=out, mode="embed", max_concurrency=256)

Use the Inference facade. Set workers by backend: 1–2 on a single local GPU (higher is pointless — see Performance tuning); a small multiple of the endpoint’s GPU count for remote/aws; one process per GPU for multiple local GPUs.

from bioptimus.inference import Inference
from bioptimus.models.types import Models

infer = Inference(
    model_name=Models.H1, cohort=cohort,
    api_url="http://localhost:8080",
    tissue=True, mask_threshold=0.5,
    output_path="/data/output", experiment="my_experiment", run=1,
    workers=2,
)
infer.tissue()
infer.run(mode="embed")

Still too slow? Raise mask_threshold (fewer tiles), then move to a larger or additional GPU, or dig into the knobs on Performance tuning.

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.

Common issues

Connection issues, and where to look for slow or stalled runs.

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

Troubleshooting

Reference

Installation

Two ways to use it

Inference pipeline (recommended)

Core API (advanced)

Connecting to a model

Recommended starting configurations

Guides

Inference pipeline

Cohorts

Spatial transcriptomics

Tile embeddings & PCA

WSI processing

Visualizing results

Common issues

Output formats

​Installation

​Two ways to use it

Inference pipeline (recommended)

Core API (advanced)

​Connecting to a model

​Recommended starting configurations

​Guides

Inference pipeline

Cohorts

Spatial transcriptomics

Tile embeddings & PCA

WSI processing

Visualizing results

Common issues

​Output formats

Installation

Two ways to use it

Connecting to a model

Recommended starting configurations

Guides

Output formats