medotter
This page documents every public name exported by medotter (imported as
mo): 17 public API names (medotter.__all__ also lists __version__,
documented separately below), plus the lazily-exposed submodules metrics,
bridges, prompts, and selfreport (deliberately excluded from __all__
— see below).
For narrative walkthroughs with worked examples, see the Guides
section; this page is the terse, per-name reference.
medotter.__version__ is "0.1.0".
Names are grouped by area (catalog, data, inference, training, evaluation, benchmark, submission):
- Catalog —
DatasetInfo,describe_dataset,list_datasets - Data —
Sample,VideoSample,load_dataset - Inference —
load_model,list_models,list_architectures - Evaluation —
Predictor,ScoreReport,LabelSchema,score,evaluate - Training —
train - Benchmark —
list_benchmarks,load_benchmark - Submission —
selfreport.evaluate_and_report, and thepython -m medotter submitCLI - Lazy module —
metrics(plusbridges,prompts,selfreport)
Catalog
Torch-free: reads a JSON file bundled with the package. No GPU, network, or ML dependency required.
DatasetInfo
@dataclass(frozen=True)
class DatasetInfo:
name: str
modality: Optional[str] = None
anatomy: Optional[str] = None
task: Optional[str] = None
n_classes: Optional[int] = None
class_names: Optional[List[str]] = None
class_labels: Optional[Dict[int, str]] = None
background_id: Optional[int] = None
ignore_ids: Optional[List[int]] = None
input_channels: Optional[int] = None
has_video: bool = False
hf_repo: Optional[str] = None
source: Optional[str] = None
card: Optional[str] = None
Stability: stable
A frozen dataclass returned by describe_dataset() and list_datasets().
| Field | Type | Meaning |
|---|---|---|
name | str | Exact registry key, e.g. "ACDC". Case-sensitive. |
modality | str | None | Free-text imaging modality, e.g. "CT", "CT, MRI". |
anatomy | str | None | Free-text anatomical region(s), e.g. "abdomen, liver". |
task | str | None | Free-text task description, e.g. "organ, cardiac". |
n_classes | int | None | Number of label classes, including background if named. |
class_names | list[str] | None | Class names in label-index order; index 0 is conventionally background. |
class_labels | dict[int, str] | None | Explicit {label_id: name} map — the authoritative source LabelSchema.from_catalog prefers. |
background_id | int | None | The label id treated as background, when known. |
ignore_ids | list[int] | None | Label ids that should not be scored (e.g. “unannotated” regions). |
input_channels | int | None | Expected image channel count. |
has_video | bool | Whether the dataset is also registered as a video-style loader. |
hf_repo | str | None | Hugging Face dataset repo backing this entry, if any. |
source | str | None | Human-readable source/provenance note. |
card | str | None | Path to the dataset’s knowledge card, if one exists. |
import medotter as mo
info = mo.describe_dataset("ACDC")
info.modality, info.n_classes # ('MRI', 4)
describe_dataset
def describe_dataset(name: str) -> DatasetInfo
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
name | str | — | Exact, case-sensitive registry key (e.g. "ACDC", not "acdc"). |
Returns: the dataset’s DatasetInfo.
Raises: KeyError if name is not in the catalog. The message includes
up to 10 “did you mean” candidates (existing keys containing name as a
substring) when any exist.
import medotter as mo
mo.describe_dataset("ACDC")
# DatasetInfo(name='ACDC', modality='MRI', anatomy='heart, cardiac', ...)
list_datasets
def list_datasets(modality=None, anatomy=None, task=None, has_video=None) -> List[DatasetInfo]
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
modality | str | None | None | Case-insensitive substring match against the free-text modality field. |
anatomy | str | None | None | Case-insensitive substring match against the free-text anatomy field. |
task | str | None | None | Case-insensitive substring match against the free-text task field. |
has_video | bool | None | None | Exact boolean match on has_video. |
Returns: list[DatasetInfo], sorted by name. With no arguments, every
catalog entry.
Raises: nothing — an unmatched filter simply yields an empty list.
import medotter as mo
mo.list_datasets(modality="CT, MRI") # substring match: HANSeg, MSD
mo.list_datasets(anatomy="liver") # substring match across the catalog
Data
Import is torch-free; load_dataset pulls torch and the dataloader
package via a function-local import the first time it is called.
Sample
@dataclass(frozen=True)
class Sample:
image: np.ndarray
mask: Optional[np.ndarray]
spacing: Optional[Tuple[float, ...]]
meta: Dict[str, Any] = field(default_factory=dict)
Stability: stable
One browse/train sample, uniform across all 169 catalog datasets.
| Field | Type | Meaning |
|---|---|---|
image | np.ndarray | (H, W) or (H, W, 3). Native dtype — never re-normalized; normalization is the model’s job. |
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). None if the loader returns no mask. |
spacing | tuple[float, ...] | None | Pixel/voxel spacing if the loader surfaces it, else None — documented, never fabricated. |
meta | dict | At least {"dataset": name}; commonly also modality, case_id, slice_idx, class_names, image_path, mask_path when the loader surfaces them. |
See Loading data for the full contract and how meta
keys drive scoring.
sample = mo.load_dataset("ACDC", split="test")[0]
sample.image.shape, sample.mask.shape
VideoSample
@dataclass(frozen=True)
class VideoSample:
frames: np.ndarray
masks: Optional[np.ndarray]
meta: Dict[str, Any] = field(default_factory=dict)
Stability: stable
One video/sequence clip — the clip-shaped sibling of Sample, returned by
load_dataset(name, type="video") for datasets registered with a video-style
loader (see has_video on DatasetInfo).
| Field | Type | Meaning |
|---|---|---|
frames | np.ndarray | (T, H, W, C). Grayscale loaders yield C=1 (a 2D frame gets a trailing channel axis, never broadcast to RGB). Native dtype — never re-normalized. |
masks | np.ndarray | None | Integer label maps, (T, H, W), in the dataset’s native label space. None when no frame in the clip is annotated; when only some frames are annotated, the unannotated planes are zero-filled and meta["annotated_frames"] lists the frame indices carrying real annotation. |
meta | dict | At least {"dataset": name}; commonly also video_id, num_frames, fps, sequence_id, frame_indices, modality, class_names, annotated_frames when the loader surfaces them. |
clip = mo.load_dataset("Endovis2017", type="video", split="test")[0]
clip.frames.shape, clip.masks.shape # (T, H, W, C), (T, H, W)
load_dataset
def load_dataset(name: str, *, split="train", type="image", source=None, **kwargs)
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
name | str | — | Registry short name (see list_datasets()); case-sensitive. |
split | str | "train" | "train" | "val" | "test"; normalized per-dataset. |
type | str | "image" | "image" yields 2D Sample objects from the image registry; "video" yields VideoSample clips from the video registry. A dataset may be registered in one, the other, or both. |
source | str | None | None | Maps to the loader’s source_type: "local" | "hf" | "download". None lets the loader choose (HF namespace MedOtter/<name>). |
**kwargs | — | — | Per-dataset options (modality=, dataset=, task=, …) forwarded to the loader constructor. |
Returns: an indexable and iterable view of Sample objects
(VideoSample objects when type="video").
Raises: ValueError if type is neither "image" nor "video";
ImportError if the data stack (torch, datasets, the repo’s dataloader
package) is not installed; KeyError if name is not registered for the
requested type (not every dataset has a video track).
import medotter as mo
ds = mo.load_dataset("ACDC", split="test")
len(ds), ds[0].image.shape
Inference
Import is torch-free; load_model pulls torch (and, for SAM2, the model
backbone) only when called.
load_model
def load_model(source, **kwargs)
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
source | str | Path | — | Either a registered name (from list_models()) or a checkpoint path ending in .pth/.pt/.ckpt (or any existing file path). |
**kwargs | — | — | For checkpoints: arch=, num_classes=, input_channel=, input_size=, device=, threshold=, normalize=, input_scale=. For SAM2 names: device=, prompt= ("box" or "point"). |
Returns: a Predictor — an object with .predict(image, spacing=None) -> np.ndarray (an integer label map matching image’s spatial shape).
Raises: ValueError if source is neither a registered name nor a
plausible checkpoint path, or if an explicit arch= is not a known
architecture (see list_architectures()).
import medotter as mo
model = mo.load_model("sam2_hiera_small") # a registered baseline
model = mo.load_model("runs/best.pth", arch="CMUNeXt", num_classes=4) # a checkpoint
list_models
def list_models() -> list[str]
Stability: stable
Params: none.
Returns: sorted registered model names loadable by name alone via
load_model(name) — the SAM2 baselines. This is not the full set
load_model can build; checkpoint models also need arch= (see
list_architectures()).
Raises: nothing; torch-free.
mo.list_models()
# ['sam2_hiera_base_plus', 'sam2_hiera_large', 'sam2_hiera_small', 'sam2_hiera_tiny']
list_architectures
def list_architectures() -> list[str]
Stability: stable
Params: none.
Returns: sorted architecture names valid for load_model(checkpoint, arch=...) — the trainable archs registered in models_train/model_id.json
plus the RWKV allowlist. Unlike list_models(), these are not loadable by
name alone: an arch describes how to build a network, so it needs a
checkpoint’s weights.
Raises: nothing; torch-free (JSON read only).
mo.list_architectures() # includes 'CMUNeXt', 'U_Net', 'RWKV_UNet', ...
Evaluation
Predictor, ScoreReport, and LabelSchema are torch-free. score() uses
only numpy and the torch-free metrics/ package; evaluate() additionally
imports load_dataset (torch on call).
Predictor
@runtime_checkable
class Predictor(Protocol):
def predict(self, image: np.ndarray, spacing=None) -> np.ndarray: ...
Stability: stable
A runtime_checkable typing.Protocol — isinstance(model, mo.Predictor)
works, but nothing needs to subclass it; any object with a matching
.predict method satisfies it, and evaluate() also accepts a bare callable
model(image) with no .predict at all.
predict returns an integer label map matching image’s spatial shape, in
the dataset’s native label space (label 0 is not universally background).
This is the same prompt-free, label-map contract medotter_core uses, at
2D-sample granularity — see medotter_core.inference.Predictor
for the volume-level (3D) counterpart used by Benchmark.evaluate.
class MyPredictor:
def predict(self, image, spacing=None):
return my_model(image)
isinstance(MyPredictor(), mo.Predictor) # True — duck typing via Protocol
ScoreReport
@dataclass(frozen=True)
class ScoreReport:
per_class: Dict[str, Dict[str, Optional[float]]]
macro: Dict[str, Optional[float]]
n_cases: int
metrics: Tuple[str, ...]
support: Dict[str, int] = field(default_factory=dict)
per_case: Optional[Dict[str, Dict[str, Dict[str, float]]]] = None
Stability: stable
Returned by score() and evaluate() (and, in the experimental 3D path, by
Benchmark.evaluate()).
| Field | Type | Meaning |
|---|---|---|
per_class | dict[str, dict[str, float | None]] | {class_name: {metric: mean_value}} — each foreground class’s mean per requested metric. |
macro | dict[str, float | None] | {metric: mean_value} — the mean of per_class values, averaged only over classes present in at least one ground-truth case. |
n_cases | int | Number of samples/cases scored. |
metrics | tuple[str, ...] | The metric names that were computed, e.g. ("dice", "iou"). |
support | dict[str, int] | {class_name: count} — how many cases had that class present in the ground truth. |
per_case | dict[str, dict[str, dict[str, float]]] | None | {case_key: {class_name: {metric: value}}}, keyed by medotter.evaluation.case_key(sample, index); populated only when per_case=True was passed to score/evaluate. |
ScoreReport also defines a custom __repr__ that prints a readable
per-class + macro summary (used by print(report)).
report = mo.evaluate(model, "ACDC")
report.macro["dice"], report.support
print(report) # human-readable per-class + macro summary
LabelSchema
@dataclass(frozen=True)
class LabelSchema:
classes: Dict[int, str]
background_id: Optional[int] = 0
ignore_ids: FrozenSet[int] = field(default_factory=frozenset)
Stability: stable
Describes the integer label space used by a dataset, replacing the
convention that label 0 always means background. classes names every
label (including background/ignore ones, when named); background_id=None
means the dataset has no background class.
Key surface, beyond the constructor:
| Member | Meaning |
|---|---|
.scored_classes | {id: name} — named classes eligible for per-class scoring (excludes background_id and ignore_ids). |
.legal_prediction_ids | Ids a model is allowed to emit: scored_classes plus background_id. |
.legal_ground_truth_ids | legal_prediction_ids plus ignore_ids — ids allowed to appear in ground truth. |
LabelSchema.from_explicit(labels) | Classmethod: build from a list of names (index 0 = background) or a {id: name} dict (infers background/ignore from names). |
LabelSchema.from_catalog(info) | Classmethod: build from a DatasetInfo’s class_labels/class_names. Returns None if the catalog has no class info. |
LabelSchema.infer_from_masks(masks) | Classmethod: infer a schema from observed ground-truth label ids (assumes 0 is background). |
.validate_prediction(pred, *, valid_mask=None, allow_unknown_ids=False) | Validate a prediction’s dtype/finiteness/label ids against the schema; raises ValueError on violation. |
Raises (constructor): ValueError for blank/duplicate class names, or if
background_id is also listed in ignore_ids.
schema = mo.LabelSchema(
classes={0: "tumor", 1: "background"},
background_id=1,
)
report = mo.score(preds, ds, schema=schema)
score
def score(predictions: Dict[str, np.ndarray], dataset, *,
metrics=("dice", "iou"), labels=None, schema=None,
per_case=False, present_only=False) -> ScoreReport
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
predictions | dict[str, np.ndarray] | — | {key: pred_label_array}. key is f"{case_id}#{slice_idx}" when a sample’s meta has both, else case_id, else the sample’s index as a string — the rule medotter.evaluation.case_key(sample, index) implements. |
dataset | — | — | A mo.load_dataset(...) view, or any iterable of Sample. |
metrics | tuple[str, ...] | ("dice", "iou") | Any of "dice", "iou", "hd95". |
labels | list[str] | dict[int, str] | None | None | Backwards-compatible explicit label set; mutually exclusive with schema. |
schema | LabelSchema | None | None | Explicit, strict label contract; mutually exclusive with labels. |
per_case | bool | False | When True, ScoreReport.per_case also carries each case’s individual metric values. |
present_only | bool | False | When True, a class’s per-case mean is averaged only over cases where that class is present in the ground truth. |
Returns: a ScoreReport.
Raises: KeyError if a dataset case key has no entry in predictions;
ValueError for a prediction/sample count mismatch, a duplicate case key, an
unsupported metric name, both labels and schema passed, or a prediction
containing a label id outside the resolved schema.
import medotter as mo
ds = mo.load_dataset("ACDC", split="test")
preds = {"patient001_frame01": my_prediction_array}
report = mo.score(preds, ds, metrics=("dice", "iou"), per_case=True)
evaluate
def evaluate(model, name: str, *, split="test", type="image",
metrics=("dice", "iou"), labels=None, schema=None,
per_case=False, present_only=False, **load_kwargs) -> ScoreReport
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
model | Predictor | callable | — | An object with .predict(image, spacing=None), or a bare callable model(image). |
name | str | — | Dataset registry key, forwarded to load_dataset. |
split | str | "test" | Forwarded to load_dataset. |
type | str | "image" | Forwarded to load_dataset. |
metrics | tuple[str, ...] | ("dice", "iou") | Same as score(). |
labels | list | dict | None | None | Same as score(); mutually exclusive with schema. |
schema | LabelSchema | None | None | Same as score(); mutually exclusive with labels. |
per_case | bool | False | Same as score(). |
present_only | bool | False | Same as score(). |
**load_kwargs | — | — | Forwarded to load_dataset (e.g. source=, per-dataset options). |
Returns: a ScoreReport.
Raises: same ValueError conditions as score() (schema/label
resolution, metric names); ImportError if the data stack load_dataset
needs is not installed.
import medotter as mo
model = mo.load_model("sam2_hiera_small")
report = mo.evaluate(model, "ACDC", split="test", metrics=("dice", "iou"))
print(report)
Training
Import is torch-free; train pulls torch and the training stack only when
called.
train
def train(config, **opts) -> dict
Stability: stable
| Param | Type | Default | Meaning |
|---|---|---|---|
config | str | Path | dict | core.config.Config | — | A YAML path, a plain dict (wrapped in Config), or an existing Config (passed through unchanged). |
**opts | — | — | Forwarded to training.runner.run_training: output_dir=, save= (default True), epochs=, max_batches=, resume= (a checkpoint path — restores optimizer/scheduler state and continues from its saved epoch), hf_weights=, device=, allow_unsafe= (default False; True permits the weights_only=False pickle fallback for resume/hf_weights — an arbitrary-code-execution risk, use only for a trusted source). |
Returns: the trainer’s summary dict, with an added "output_dir" key.
Raises: TypeError if config is not a path, dict, or Config;
ImportError on the call (not on import) if torch/the training stack is
missing; unmodified errors from the training loop otherwise propagate.
import medotter as mo
config = {
"experiment": {"name": "busuclm_cmunext", "seed": 42},
"model": {"name": "CMUNeXt", "input_channel": 3, "num_classes": 1},
"dataset": {"BUS-UCLM": {"split": "train"}},
"auto_split": {"train": 0.8, "val": 0.1, "seed": 42},
"training": {"epochs": 1, "batch_size": 8,
"optimizer": {"type": "AdamW", "lr": 1e-4}},
}
summary = mo.train(config, max_batches=2, output_dir="./runs/smoke")
summary["output_dir"]
Benchmark
list_benchmarks is stable and torch-free (directory listing only).
load_benchmark’s metadata access is torch-free too, but Benchmark.evaluate
is experimental: it needs a prepared data_root most bundles keep out of the
development source tree, and is only partially proven on GPU. Expect that one surface
to evolve — see the full 3D volume benchmarks guide
for the caveats.
list_benchmarks
def list_benchmarks() -> list[str]
Stability: stable
Params: none.
Returns: sorted names of the benchmark bundles under the repo’s
benchmarks/ directory (those with a bench.yaml).
Raises: nothing; torch-free (reads directory names only).
mo.list_benchmarks()
# ['abdominal_multiorgan_ct', 'glioma_wt_tc_et', 'histopath_nucleus_seg', ...]
load_benchmark
def load_benchmark(name_or_dir) -> Benchmark
Stability: stable for discovery and metadata — load_benchmark itself
and the returned Benchmark’s .task_id/.modality/.anatomy/.regions/
.metrics/.mode are torch-free and always available; only
Benchmark.evaluate(...) (the 3D volume eval) is experimental — see below.
| Param | Type | Default | Meaning |
|---|---|---|---|
name_or_dir | str | Path | — | A bundle name under benchmarks/, or a path to a bundle directory containing bench.yaml. |
Returns: a Benchmark — exposes .task_id, .modality, .anatomy,
.regions, .metrics, .mode (torch-free, always available); .train / .test
(need the bundle’s manifest.json); and
.evaluate(predictor, *, data_root, split="test", templates=None) -> ScoreReport for volume-level (3D) scoring — see the
3D volume benchmarks guide for the full accessor
list and Benchmark.evaluate’s parameters. evaluate’s predictor is a
medotter_core.inference.Predictor
(predict(image[C,i,j,k]) -> label volume) — not this page’s 2D
medotter.Predictor.
Raises: ValueError for an unknown bundle name/directory. Benchmark.train
/ .test / .evaluate additionally raise FileNotFoundError when
manifest.json is absent, and Benchmark.evaluate raises
NotImplementedError for any bundle whose .mode is not "3d_volumetric".
import medotter as mo
from medotter_core.inference import ZeroPredictor
bm = mo.load_benchmark("glioma_wt_tc_et")
bm.modality, bm.regions # torch-free metadata
report = bm.evaluate(ZeroPredictor(), data_root="/path/to/DATA_ROOT") # experimental
Submission
Preparing and attaching a self-reported result file — the report a
reviewer compares against the platform’s own re-run when your model is
submitted to the public leaderboard. evaluate_and_report is not a top-level
name: it lives in the lazily-exposed mo.selfreport module (see
Lazy module for the mechanism; selfreport itself
is stdlib-only, so accessing it costs nothing — the heavy imports happen
inside the call). It runs the same evaluation
Benchmark.evaluate runs and also writes the report; the
python -m medotter submit CLI is a separate command that attaches it. See
Submitting a model for the full submission
flow (rate limits, review lifecycle, the web modal).
selfreport.evaluate_and_report
def evaluate_and_report(predictor, name: str, *, data_root, split="test",
out="medotter-report.json", hardware=None) -> dict
Stability: experimental — inherits Benchmark.evaluate’s caveats (see
load_benchmark): needs a prepared data_root, and is
only partially proven on GPU.
| Param | Type | Default | Meaning |
|---|---|---|---|
predictor | medotter_core.inference.Predictor | — | predict(image[C,i,j,k]) -> label volume; the same 3D-volume predictor Benchmark.evaluate takes, not this page’s 2D Predictor. |
name | str | — | A benchmark bundle name, forwarded to load_benchmark. |
data_root | str | Path | — | Root of the prepared raw cohort for name. |
split | str | "test" | "train" or "test". |
out | str | Path | "medotter-report.json" | Where the self-reported result file is written. This exact filename is what the python -m medotter submit CLI auto-picks up (see below). |
hardware | str | None | None | Free-text hardware label recorded in the report’s environment.hardware (e.g. "1x A6000"); omitted from the report when None. |
Returns: the report payload dict — the same document it writes to out,
with the run’s per-case scores already aggregated into leaderboard-shaped
rows. Not a ScoreReport; if you want that shape, call
Benchmark.evaluate directly.
Raises: ValueError for a split other than "train"/"test" (checked
first, before name is even resolved); otherwise same as Benchmark.evaluate
(see load_benchmark): FileNotFoundError when the
bundle’s manifest.json is absent, NotImplementedError for a bundle whose
.mode is not "3d_volumetric".
import medotter as mo
from medotter_core.inference import ZeroPredictor
payload = mo.selfreport.evaluate_and_report(
ZeroPredictor(), "glioma_wt_tc_et",
data_root="/path/to/DATA_ROOT", hardware="1x A6000",
)
# writes ./medotter-report.json, ready for `python -m medotter submit`
CLI: python -m medotter submit
Not a Python name — a command run with python -m. The medotter package
installs no console scripts onto PATH; running it as python -m medotter submit
binds the command to whichever interpreter you invoke — a stale console
script on PATH can never point at a different environment. None of the
python -m medotter commands reads a .env file — environment variables
like HF_TOKEN (needed when python -m medotter evaluate pulls an hf:
checkpoint) must be exported in the environment the command runs in. Documented
here because it’s the usual way selfreport.evaluate_and_report’s
output reaches the public leaderboard; the full flag reference, rate limits,
and review lifecycle are in Submitting a model.
python -m medotter submit owner/model --tasks glioma_wt_tc_et
- Sign-in is GitHub’s OAuth device flow: the CLI prints a
verification_uriand a short code, you approve it in a browser, and the CLI polls GitHub until you do — no token or password to copy around. --revisionmust equal the repository’s current default-branch head commit. Pass it explicitly and the CLI verifies the match before submitting rather than silently pinning a stale or arbitrary commit; omit it and the CLI resolves the default branch’s head for you.- Report auto-pickup: the CLI never generates a report itself — it only
attaches one
mo.selfreport.evaluate_and_report(...)already wrote. Ifmedotter-report.json(that function’s defaultout=) exists in the current directory, the CLI attaches it automatically; pass--reportonly if the file lives somewhere else.
Raises: the CLI doesn’t raise Python exceptions to a caller — a non-2xx
response from the submit endpoint prints the server’s error and exits
non-zero (429 for a rate limit, 400/401/403 for a GitHub-identity
failure; see Submitting a model for the exact
shapes).
Lazy module: mo.metrics
mo.metrics is not in medotter.__all__ — it is reachable via attribute
access (a module-level __getattr__) and shown by __dir__, but deliberately
kept out of __all__ so that from medotter import * and __all__-walking
tools (Sphinx, etc.) don’t eagerly resolve it and pull in the scoring stack.
Accessing mo.metrics imports medotter.metrics, which re-exports exactly
seven pure metric names from medotter_core, byte-identically (no wrapping,
no copies: mo.metrics.hd95 is medotter_core.hd95 is True):
| Name | What it is |
|---|---|
hd95 | 95th-percentile symmetric Hausdorff distance (mm) between two binary masks. |
surface_distances | Lower-level helper behind hd95: paired surface-to-surface distance arrays. |
HD95_MAX_MM | 373.13 — the fixed HD95 penalty (mm) for a one-sided empty structure. |
region_dice | Binary Dice over two already-binarized region masks. |
region_iou | Binary IoU over two already-binarized region masks. |
score_regions | Scores every region as the union of its constituent label ids, for a full label map. |
CANONICAL_REGIONS | {"WT": (1,2,3), "TC": (1,3), "ET": (3,)} — the default regions= for score_regions. |
Each is documented in full on the medotter_core reference page.
Those seven names are the whole surface: the engine orchestration names
(Bundle, run_submission, evaluate_bundle, the to_*_score_rows and
resolve_* helpers, and the rest of medotter_core.__all__) are not
importable through the medotter facade at all — engine-level users import
medotter_core directly. (One name collides without being shared:
mo.evaluate is the dataset-level function from medotter.evaluation, not
the engine’s medotter_core.evaluate — mo.evaluate is not medotter_core.evaluate.)
The first access to mo.metrics pulls in scipy (via medotter_core →
medotter_core.metrics.hd95). Note that mo.score / mo.evaluate also pull
in scipy independently — via their own medotter_core.metrics.region_eval
import chain, on any call regardless of metrics=, not through mo.metrics
(see Evaluation). A script that only uses the
catalog / data / inference / training surfaces — never scoring and never
touching mo.metrics — never pays for scipy.
Stability: stable (the lazy-import mechanism); the seven names are
medotter_core’s, documented on the
medotter_core reference page.
import medotter as mo
mo.metrics.CANONICAL_REGIONS # {'WT': (1, 2, 3), 'TC': (1, 3), 'ET': (3,)}
# same effect, explicit re-export form:
from medotter import metrics
Three sibling modules ride the same lazy lane: mo.bridges (2D-model →
3D-volume bridge predictors, re-exported from medotter_core.bridges, same
scipy cost), mo.prompts (numpy-only prompt helpers, lazy for surface
uniformity), and mo.selfreport (stdlib-only; its evaluate_and_report is
documented under Submission above).