Classification

Classification task heads map the aggregated bag representation to class predictions. soma ships binary, multiclass, and ordinal variants. The aggregator is the method home for the bag → slide-level step that feeds these heads — see Aggregators.

Binary

class soma.tasks.classification.BinaryClassificationHead(input_dim, num_classes, metrics=None, label_map=None)

Bases: TaskHead

Linear classification head for binary (two-class) tasks.

Parameters:

  • input_dim (int) – Dimension of the input representation.

  • num_classes (int) – Must be 2.

  • metrics (list[str] | None) – Metrics to compute. Empty list uses the default set for binary_classification: auroc, balanced_accuracy, auprc, f1.

Multiclass

class soma.tasks.classification.MulticlassClassificationHead(input_dim, num_classes, metrics=None, label_map=None)

Bases: TaskHead

Linear classification head for multi-class tasks.

Parameters:

  • input_dim (int) – Dimension of the input representation.

  • num_classes (int) – Number of output classes (>= 2).

  • metrics (list[str] | None) – Metrics to compute. Empty list uses the default set for multiclass_classification: auroc_macro, balanced_accuracy, f1_macro.

Ordinal

class soma.tasks.ordinal_classification.OrdinalClassificationHead(input_dim, num_classes, metrics=None, label_map=None)

Bases: TaskHead

Linear head for ordinal classification using MSE loss.

Treats ordered integer labels as continuous values during training (MSE loss) while producing integer predictions at inference by rounding the continuous output to the nearest class. Both the rounded prediction and the raw continuous score are reported.

Parameters:

  • input_dim (int) – Dimension of the input representation.

  • num_classes (int) – Number of ordinal classes (e.g. 6 for labels 0–5).

  • metrics (list[str] | None) – Metrics to compute. Empty list uses the default set for ordinal_classification: qwk, balanced_accuracy.

Metric compatibility

multiclass_classification accepts qwk as an opt-in metric when the class labels have an ordinal interpretation. The task still uses cross-entropy loss; the metric only changes how results are summarized.

Benchmarks

  • EVA — frozen-tile-probe runs of these heads on the EVA patch-level datasets (bach, breakhis, crc, mhist, patch_camelyon).