Guides
Loading data
Public package status: the Python distributions and
desktop installers are not released yet. These pages document an
evolving interface, not currently usable install artifacts.
View release status.
load_dataset turns any catalog entry into an indexable and iterable view of
Sample objects — a uniform shape across all 130 datasets, regardless of
each dataset’s native file format or loader implementation.
Loading a dataset
def load_dataset(name: str, *, split="train", type="image", source=None, **kwargs)name— the dataset’s exact registry key, e.g."ACDC"(see the catalog guide; case-sensitive).split—"train","val", or"test". Normalized per-dataset, so the exact rows behind each split are the dataset’s own convention.type—"image"is the only supported value today. Some registry entries also have a video-style loader (seehas_videoonDatasetInfo), but its loader returns{"frames", "masks", ...}rather than a singleimage/maskpair — this facade does not adapt that shape yet, sotype="image"on such a dataset still gives you 2D image samples, not frame sequences.source— maps to the underlying loader’ssource_type:"local","hf", or"download". Leave itNoneto let the loader choose (by default, the Hugging Face namespaceMedOtter/<name>).**kwargs— forwarded to the dataset’s loader constructor (e.g.modality=,task=) for datasets that accept per-dataset options.
import medotter as mo
ds = mo.load_dataset("ACDC", split="test")
len(ds) # number of samples in the test split
sample = ds[0] # indexable
for sample in ds: # also iterable
...The Sample contract
Every element is a Sample(image, mask, spacing, meta):
| Field | Type | Contract |
|---|---|---|
image | np.ndarray | (H, W) or (H, W, 3). Native dtype — never re-normalized. Normalization (scaling, mean/std) is the model’s job, not the loader’s. |
mask | np.ndarray | None | Integer label map, same spatial shape as image. In the dataset’s native label space — label 0 is not universally background (see LabelSchema and a dataset’s DatasetInfo.background_id). None if the loader returns no mask. |
spacing | tuple[float, ...] | None | Pixel/voxel spacing, if the underlying loader surfaces it. Never fabricated — None when the dataset doesn’t carry spacing metadata, not a guessed default. |
meta | dict | At least {"dataset": name}; commonly also modality, case_id, slice_idx, class_names, image_path, mask_path — present only when the loader surfaces them. |
meta["case_id"] (plus meta["slice_idx"] when present) is what
mo.score uses to key predictions, so two samples
from the same volume are only safely distinguishable when slice_idx is
present.
Common errors
ImportError— raised iftorch, thedatasetspackage, or the repo’sdataloaderpackage are not installed. The catalog (list_datasets/describe) works without them;load_datasetis the first call that needs the full data stack.KeyError—nameis not a registered dataset. Usemo.list_datasets()to see what’s available.NotImplementedError— raised for anytypeother than"image"; video-frame-sequence loading is not supported by this facade yet.