bioptimus.inference.inference

Generic WSI inference orchestrator. Provides Inference, a high-level facade that wires together model construction, tissue segmentation, tile extraction, and per-tile prediction via a remote model endpoint. The internal _SlideInference class handles single-WSI processing.

Inference

class Inference(model_name: Models | str,
                api_url: str | None = None,
                *,
                cohort: Cohort | None = None,
                wsi_dir: str | Path | None = None,
                bulk_rna_dir: str | Path | None = None,
                mask_dir: str | Path | None = None,
                tissue: bool = True,
                mask_threshold: float = 0.5,
                output_path: str | Path = _DEFAULT_OUTPUT_PATH,
                output_format: OutputFormat | str = OutputFormat.ZARR,
                max_concurrency: int = 256,
                workers: int | None = None,
                experiment: str | None = None,
                run: int | None = None,
                variant: str | None = None,
                description: str | None = None,
                backend: str = 'remote',
                wsi_backend: str | None = None,
                coordinates: Sequence[tuple[int, int]] | None = None,
                **kwargs: Any)

High-level multi-WSI inference facade. Wraps model construction, tissue segmentation, tile extraction, and per-tile prediction behind a simple API. A single instance is reusable across many WSIs. The Cohort is the single source of truth — all inputs, outputs, and processing status live there. The manifest is auto-saved after each WSI completes, enabling seamless resume on restart.

Model identifier. Use Models enum values or a plain string matching a YAML config.

Base URL for the HTTP backend. Required when backend is "remote".

A pre-built Cohort manifest. If not provided, one is created on first use (ad-hoc mode).

Directory containing WSI files.

Directory containing bulk RNA files.

Directory containing pre-computed tissue masks.

Whether to auto-compute tissue masks via the tissue-seg model. Defaults to True.

Minimum tissue fraction to keep a tile.

Root directory for the structured workspace.

On-disk format for predictions/embeddings.

Maximum concurrent HTTP requests.

Number of WSIs to process in parallel. When None (the default), it falls back to max(1, gpu_count) from the local CUDA device count. This is meaningful for the local backend; for the remote and aws backends the GPUs live server-side, so a warning is logged and this should be set explicitly.

Experiment / study name for directory nesting.

Run number for repeated experiments.

Sub-variant label (e.g. stain method, threshold).

Free-text note saved in the config.

"remote" (HTTP) or "aws" (SageMaker).

Optional explicit tile positions as (x, y) top-left, slide-origin pixel pairs at the model tile-spec resolution. When supplied, tiles are extracted at exactly these locations (one per coordinate) and tissue masking is bypassed, for every slide this instance processes. Intended for predicting at predefined locations (e.g. PseudoVisium / hex-pooled / Visium spots) and benchmarking against spatial-transcriptomics ground truth. Spot tables report spot centres; convert to top-left first (subtract half the spot size in x and y). Coordinate mode targets a single WSI at a time.

Backend-specific arguments forwarded to Backbone.

Example:

from bioptimus.models import Models
from bioptimus.inference import Inference
from bioptimus.data.cohort import Cohort

cohort = Cohort.from_directories("/data/wsis", "/data/rna")

infer = Inference(
    model_name=Models.H1,
    api_url="http://localhost:8000",
    cohort=cohort,
    experiment="brca-cohort-a",
    run=1,
)
infer.run()  # processes all pending WSIs

from_workspace

@classmethod
@log_failures
def from_workspace(cls, workspace: str | Path, **overrides: Any) -> Inference

Resumes an Inference from a saved workspace. Loads both the config YAML and the cohort manifest, allowing seamless resume of an interrupted run.

Path to the workspace directory.

Keyword overrides applied on top of the config values.

Returns: A fully-initialised Inference with cohort state.

save_config

@log_failures
def save_config(path: str | Path | None = None) -> Path

Persists the current configuration as a YAML file.

Destination file path. Defaults to the workspace.

Returns: Path to the written config file.

cohort

@property
def cohort() -> Cohort

The cohort manifest (single source of truth).

wsi_dir

@property
def wsi_dir() -> Path | None

Directory containing WSI files, or None if not set.

model_name

@property
def model_name() -> str

Name of the model this instance targets.

workspace

@property
def workspace() -> Path

Resolved experiment workspace root directory.

manifest_path

@property
def manifest_path() -> Path

Path to the cohort manifest YAML in the workspace.

find

@log_failures
def find(wsi_dir: str | Path | None = None,
         bulk_rna_dir: str | Path | None = None,
         mask_dir: str | Path | None = None,
         *,
         patient_id_fn: Callable[[str], str] | None = None) -> Cohort

Discovers WSI, bulk RNA, and mask files; builds the cohort. Scans directories for supported files, auto-pairs them, and stores the result as the instance cohort.

Directory to scan for WSI files.

Directory for bulk RNA files.

Directory for pre-computed masks.

Optional callable that maps a filename stem to a patient ID.

Returns: The constructed Cohort. Raises:

ValueError - If no WSI directory is available.

run

def run(mode: InferenceMode | str = InferenceMode.EMBEDDING,
        *,
        force: bool = False) -> list[Path | None]

Processes all pending WSIs in the cohort. Automatically resumes — WSIs whose output already exists on disk are skipped unless force is True.

The InferenceMode to run (EMBEDDING or PREDICTION); a mode string is also accepted.

Reprocess all WSIs regardless of status.

Returns: List of output paths, one per WSI in cohort order. Raises:

BioptimusValueError - If this instance has coordinates set (the full-cohort form is incompatible with the single-WSI contract).

predict

@log_failures
def predict(wsi_path: str | Path | list[str | Path] | None = None,
            *,
            bulk_rna_path: str | Path | None = None,
            force: bool = False) -> Path | None | list[Path | None]

Runs prediction for one or more WSIs. When called without arguments, processes the full cohort. Single paths are auto-registered in the cohort. When this instance was constructed with coordinates=, tiles are extracted at those fixed locations for the single processed WSI.

Single WSI path, list of paths, or None to process the full cohort.

Optional bulk RNA CSV override.

Reprocess even if already done.

Returns: The output path for a single WSI (raising on failure), or a list of output paths for a list input or the full cohort, with None in the slots of slides that failed (logged, recorded in the manifest, and skipped so the batch completes). Raises:

BioptimusValueError - If this instance has coordinates set and a list input or the full-cohort form is requested.

embed

@log_failures
def embed(wsi_path: str | Path | list[str | Path] | None = None,
          *,
          bulk_rna_path: str | Path | None = None,
          force: bool = False) -> Path | None | list[Path | None]

Runs embedding extraction for one or more WSIs. When called without arguments, processes the full cohort. Single paths are auto-registered in the cohort.

Single WSI path, list of paths, or None to process the full cohort.

Optional bulk RNA CSV override.

Reprocess even if already done.

BioptimusValueError - If this instance has coordinates set and a list input or the full-cohort form is requested.

tissue

@log_failures
def tissue(wsi_path: str | Path | list[str | Path] | None = None,
           *,
           force: bool = False) -> np.ndarray | None | list[np.ndarray | None]

Computes (or loads cached) tissue masks. When called without arguments, processes all WSIs in the cohort that don’t yet have masks.

Single path, list, or None for full cohort.

Recompute even if a cached mask exists.

Returns: The mask for a single path (raising on failure), or a list of masks for the full cohort or a list input, with None in the slots of slides whose mask computation failed (logged and skipped).

status

def status() -> str

Returns and prints a processing status summary. Returns: A human-readable summary of cohort processing progress.

failures

@property
def failures() -> list[tuple[str, str, str]]

Returns WSIs with errors as (wsi_id, model, error).

report

def report() -> str

Prints and returns a failure summary. Returns: A formatted string listing all failed WSIs, or a success message.

Overview

Get Started

Preprocessing

Workflows

Troubleshooting

Reference

Inference

from_workspace

save_config

cohort

wsi_dir

model_name

workspace

manifest_path

find

run

predict

embed

tissue

status

failures

report

​Inference

​from_workspace

​save_config

​cohort

​wsi_dir

​model_name

​workspace

​manifest_path

​find

​run

​predict

​embed

​tissue

​status

​failures

​report

Inference

from_workspace

save_config

cohort

wsi_dir

model_name

workspace

manifest_path

find

run

predict

embed

tissue

status

failures

report