ModelGrouping

Trial-to-model mapping for CrossSegmentationExplorer-style comparison.

Maps optimization trials to “models” for side-by-side comparison, similar to how CrossSegmentationExplorer groups AI segmentations.

See ADR-018 for design rationale.

Classes

class ComparisonModel

A model for comparison, containing one or more trials.

In CrossSegmentationExplorer, a “model” is a group of segmentations from the same AI model. For optimization, we map this to groupings like “all watershed trials” or “best trial per algorithm”.

Attributes:

name: Display name for this model (e.g., “watershed”, “Gold Standard”). trials: List of trials belonging to this model. color: Optional display color (R, G, B) for visualization. metadata: Additional metadata about this model.

Methods:

best_trial()

Get the best performing trial in this model.

best_score()

Get the best Dice score in this model.

trial_count()

Get the number of trials in this model.

class TrialModelMapper

Map optimization trials to comparison models.

Provides various grouping strategies for organizing trials into CrossSegmentationExplorer-compatible “models”.

Usage:

mapper = TrialModelMapper()

# Group by algorithm models = mapper.group_by_algorithm(trials) # Returns: {“watershed”: ComparisonModel, “geodesic”: ComparisonModel, …}

# Get top N per algorithm models = mapper.get_top_n_per_algorithm(trials, n=1) # Returns: {“watershed”: ComparisonModel(trials=[best_watershed]), …}

# Group by Dice score range ranges = [(0.95, 1.0, “excellent”), (0.90, 0.95, “good”), (0.0, 0.90, “poor”)] models = mapper.group_by_dice_range(trials, ranges)

Methods:

__init__()

Initialize trial-to-model mapper.

group_by_algorithm()

Group trials by algorithm parameter.

get_top_n_per_algorithm()

Get top N trials by Dice score for each algorithm.

group_by_dice_range()

Group trials by Dice score ranges.

group_by_trial_numbers()

Select specific trials by number for comparison.

create_gold_standard_model()

Create a placeholder model for gold standard segmentation.

get_best_overall()

Get a model containing only the single best trial.

filter_by_algorithm()

Filter trials to include only specified algorithms.

filter_by_min_dice()

Filter trials to include only those above minimum Dice score.

Functions

best_trial()

Get the best performing trial in this model.

best_score()

Get the best Dice score in this model.

trial_count()

Get the number of trials in this model.

group_by_algorithm()

Group trials by algorithm parameter.

Args:

trials: List of TrialData objects to group. include_empty: If True, include algorithms with no trials.

Returns:

Dictionary mapping algorithm name to ComparisonModel.

get_top_n_per_algorithm()

Get top N trials by Dice score for each algorithm.

Args:

trials: List of TrialData objects. n: Number of top trials to include per algorithm.

Returns:

Dictionary mapping algorithm name to ComparisonModel with top N trials.

group_by_dice_range()

Group trials by Dice score ranges.

Args:

trials: List of TrialData objects. ranges: List of (min, max, name) tuples defining score ranges.

Example: [(0.95, 1.0, “excellent”), (0.90, 0.95, “good”)]

Returns:

Dictionary mapping range name to ComparisonModel.

group_by_trial_numbers()

Select specific trials by number for comparison.

Args:

trials: List of TrialData objects. trial_numbers: List of trial numbers to include.

Returns:

Dictionary mapping “trial_N” to ComparisonModel.

create_gold_standard_model()

Create a placeholder model for gold standard segmentation.

The gold standard is treated as a special “model” in comparison views.

Args:

gold_name: Display name for the gold standard.

Returns:

ComparisonModel for gold standard (trials list will be empty, segmentation loaded separately).

get_best_overall()

Get a model containing only the single best trial.

Args:

trials: List of TrialData objects.

Returns:

ComparisonModel with the single best trial.

filter_by_algorithm()

Filter trials to include only specified algorithms.

Args:

trials: List of TrialData objects. algorithms: List of algorithm names to include.

Returns:

Filtered list of trials.

filter_by_min_dice()

Filter trials to include only those above minimum Dice score.

Args:

trials: List of TrialData objects. min_dice: Minimum Dice score threshold.

Returns:

Filtered list of trials.

quick_compare_algorithms()

Quick comparison: best trial per algorithm.

Args:

trials: List of TrialData objects.

Returns:

Dictionary of algorithm name to ComparisonModel with best trial.

quick_compare_top_trials()

Quick comparison: top N trials overall.

Args:

trials: List of TrialData objects. n: Number of top trials to include.

Returns:

Dictionary of trial identifiers to ComparisonModel.