API reference¶

Top-level¶

Run all metrics over every case and return an aggregatable result.

Ground-truth spacing is authoritative: if a case does not set spacing explicitly, the spacing read from the ground-truth file is used for the distance metrics.

One evaluation case: a prediction, a ground truth, and its metadata.

All surface metrics at once, with graceful degradation on empty masks.

Conventions (Metrics Reloaded): * both masks empty -> perfect agreement: distances 0, NSD 1.0 * exactly one empty -> worst case: distances +inf, NSD 0.0

Dice similarity coefficient (== F1 on voxels).

Two empty masks agree perfectly and return 1.0 (Metrics Reloaded convention), since "correctly predicting nothing where there is nothing" is a perfect score, not an undefined one.

Intersection over union (Jaccard index).

Greedy one-to-one lesion matching by IoU.

A predicted component and a ground-truth component may match if their IoU is at least iou_threshold. Matches are assigned greedily, highest IoU first, one prediction to one ground-truth lesion. Matched ground-truth lesions are true positives; unmatched predictions are false positives; unmatched ground-truth lesions are false negatives.

Percentile bootstrap CI for an aggregate statistic over per-case values.

Parameters:

Name	Type	Description	Default
`values`	`ArrayLike`	per-case metric values (e.g. one Dice per patient).	required
`statistic`	`Callable[[NDArray[float64]], float]`	aggregate to bootstrap; defaults to the mean.	`mean`
`confidence`	`float`	two-sided confidence level (0.95 -> 2.5%/97.5%).	`0.95`
`n_resamples`	`int`	number of bootstrap resamples.	`2000`
`seed`	`int`	RNG seed; identical inputs always give identical CIs.	`0`
`drop_nonfinite`	`bool`	drop NaN/inf before resampling (e.g. inf distances from empty-mask cases). The point estimate is over the kept values.	`True`

Returns:

Name	Type	Description
`An`	`Estimate`	class:`Estimate` of (value, ci_low, ci_high). With fewer than two
	`Estimate`	usable values the interval collapses to the point estimate.

Loaders¶

Load a binary mask and its voxel spacing.

Parameters:

Name	Type	Description	Default
`source`	`MaskSource`	a NumPy array, or a path to `.npy`, NIfTI (`.nii` / `.nii.gz`), or a DICOM-SEG file.	required
`label`	`int \| None`	if given, keep only voxels equal to this label; otherwise any non-zero voxel is foreground.	`None`
`spacing`	`float \| Spacing \| None`	override the spacing. If `None`, it is read from the file header (NIfTI / DICOM-SEG) or defaults to 1.0 per axis (arrays / `.npy`).	`None`
`segment_number`	`int`	which segment to extract from a DICOM-SEG.	`1`

Returns:

Type	Description
`NDArray[bool_]`	`(mask, spacing)` with `mask` boolean and `spacing` aligned to
`Spacing`	the array axes.

Load one RTSTRUCT ROI as a mask on its referenced image grid.

RTSTRUCT stores contours, not a raster, so it needs the referenced DICOM image series to define the voxel grid. spacing is read from that series unless overridden.