Tasks

Task heads map a representation to predictions and define the loss and metric contract. This page is the task-layer index: it lists the task zoo, documents the soma.tasks.base.TaskHead base abstraction, and links to the per-task pages.

See also

The slide-level walkthrough runs classification, regression, and survival end to end on the same extracted features — the clearest way to see how swapping a task head works in practice.

Substrate cleavage

Tasks split by the representation substrate they consume:

• Slide-level tasks consume a bag of tile features, which an aggregator pools into a single slide- or patient-level vector before the head: Classification, Regression, and Survival.

• Dense tasks consume a token grid, which a decoder turns into a per-pixel map before the head: Segmentation and Detection.

The base abstraction is soma.tasks.base.TaskHead.

class soma.tasks.base.TaskHead(*args, **kwargs)

Bases: ABC, Module

Abstract base class for task heads.

Maps an aggregated slide representation to task-specific predictions.

Subclasses must implement forward, compute_loss, postprocess, compute_metrics, and extract_targets, and should set target_dtypes and auto_params appropriately.

The head owns its target contract: target_dtypes declares the keys it consumes (and their tensor dtypes), extract_targets maps a SampleRecord to a dict of raw target values, and compute_loss / compute_metrics receive a dict[str, Tensor] keyed by those names.

Task Zoo

Config name	Loss	Default metrics	When to use
binary_classification	Cross-entropy	auroc, balanced_accuracy, auprc, f1	Two-class labels
multiclass_classification	Cross-entropy	auroc_macro, balanced_accuracy, f1_macro	Two or more classes Use binary_classification when the problem is strictly binary
ordinal_classification	MSE	qwk, balanced_accuracy	Ordered integer grades
regression	MSE	mae, r2	Continuous targets
survival	Discrete-time NLL	c_index	Time-to-event with right censoring
segmentation	CE + soft-Dice	mean_dice, mean_iou	Dense per-pixel classification (dataset_type: segmentation); see Segmentation
detection	Foreground-weighted MSE	mean_f1	Cell / nucleus point detection (dataset_type: detection); see Detection

Task pages

Slide-level tasks (bag → aggregator → head):

• Classification — binary, multiclass, and ordinal heads.

• Regression — continuous targets.

• Survival — time-to-event with the nll and cox losses.

Dense tasks (token grid → decoder → head):

• Segmentation — the dense contract + neural-decoder default path.

• Detection — point detection with the F1@δ metric.

Discovery helper

Use soma.list_task_heads() to inspect the registered task heads from code when you need to populate a selector or validate a config name.