Getting started

Quick Start

This walks through the full arc of the SDK: find a dataset in the catalog, load it, load a model, and evaluate the model against it. Each line pulls in progressively more of the stack - the catalog is free, loading data and models costs torch, and the first score/evaluate call costs scipy (the scoring stack pulls it in regardless of which metrics= you ask for)

import medotter as mo

mo.list_datasets(modality="MRI")             # browse the 130-dataset catalog
ds = mo.load_dataset("ACDC", split="test")   # indexable/iterable Samples
model = mo.load_model("sam2_hiera_small")    # a Predictor with .predict()
report = mo.evaluate(model, "ACDC", split="test", metrics=("dice", "iou"))
print(report)                                 # per-class dice/iou

Walking through it

  1. mo.list_datasets(modality="MRI") returns a list of DatasetInfo entries whose modality field matches "MRI" (a case-insensitive substring match - catalog fields like modality and anatomy are often free-text, e.g. "CT, MRI"). This is a pure catalog lookup: no network access, no heavy imports. Use mo.describe("ACDC") to look up one dataset by its exact registry name.
  2. mo.load_dataset("ACDC", split="test") returns an indexable and iterable view over Sample objects (sample.image, sample.mask, sample.spacing, sample.meta). This is the first line that pulls in torch and the dataloader package - importing medotter itself never does.
  3. mo.load_model("sam2_hiera_small") returns a Predictor - anything with a .predict(image, spacing=None) -> label_map method. "sam2_hiera_small" is one of the registered SAM2 baselines (see mo.list_models()); you can also pass a checkpoint path together with arch= (see mo.list_architectures()) to load a trained model.
  4. mo.evaluate(model, "ACDC", split="test", metrics=("dice", "iou")) is the one-call convenience: it loads the dataset, runs the model over every sample, and scores the predictions - all in one step. It returns a ScoreReport with per-class and macro-averaged metrics.
  5. print(report) shows the per-class dice/iou (and hd95, if you ask for it) alongside the macro average across classes.

evaluate vs. score

mo.evaluate is the one-call path: give it a model and a dataset name, and it handles loading and inference for you. If you already have predictions - computed separately, cached from a previous run, or produced by a model medotter doesn’t know how to load - use the lower-level mo.score(predictions, dataset, metrics=(...)) instead. It takes the same metrics=, labels=/schema=, and aggregation options as evaluate, but scores a {case_key: prediction} dict you supply against an already-loaded dataset, rather than running a model itself.

Next steps