Pipeline

A pipeline run starts by reading the dataset and split manifests, then follows the stages implied by dataset_type:

• tile: read tile images and labels, extract tile features, train a lightweight task head, and evaluate on the test split.

• slide: read whole-slide images and labels, tile each slide, extract features with a tile-level or slide-level encoder, and train the appropriate downstream model. Tile-level encoders require an aggregator plus prediction head. Slide-level encoders only require a prediction head.

• patient: aggregate slide-level outputs across multiple slides per patient (experimental).

• segmentation / detection: dense paths. A frozen encoder produces a dense token grid and a trained decoder maps it to a per-pixel mask (segmentation) or a per-class peak heatmap (detection). Detection supervision is a per-sample points_path and the head scores class-aware F1 at a matching distance δ (mean_f1); see Detection.

The main configuration object is soma.config.PipelineConfig:

class soma.config.PipelineConfig(dataset_csv, splits_csv, output_root, dataset_type, feature_mode='cached', preprocessing=<factory>, execution=<factory>, cache=<factory>, encoder=None, composite=None, aggregator=None, decoder=None, pixel_classifier=None, task=None, evaluation=<factory>, training=<factory>, heatmaps=<factory>, augmentation=<factory>, tags=<factory>, resume=False, run_id=None)

Bases: object

Complete specification for a pipeline run.

Parameters:

• dataset_csv (str | Path) – Path to the dataset manifest.

• splits_csv (str | Path) – Path to the split manifest.

• output_root (str | Path) – Directory for the run outputs.

• dataset_type (str) – Input mode for the pipeline. "slide" means whole slide bags with optional MIL aggregation, "tile" means patch-level classification, and "patient" means patient-level aggregation. aggregator must be None unless dataset_type is "slide".

• preprocessing (PreprocessingConfig) – Whole-slide preprocessing and tiling settings.

• execution (ExecutionConfig) – Runtime execution settings for preprocessing and feature extraction.

• cache (CacheConfig) – Shared cache policy.

• encoder (EncoderConfig | None) – Foundation-model encoder configuration, or None for workflows that do not need one.

• aggregator (AggregatorConfig | None) – MIL aggregator configuration for slide-level bag learning, or None for tile/patient pipelines.

• task (TaskConfig) – Task-head configuration. Required.

• evaluation (EvalConfig) – Metric and subgroup evaluation configuration.

• training (TrainingConfig) – Training hyperparameters.

• heatmaps (HeatmapConfig) – Attention heatmap rendering settings.

• tags (list[str]) – Free-form labels attached to the experiment metadata.

• resume (bool) – When True, reuse the latest existing run dir for this experiment instead of minting a fresh one, and skip folds that already wrote metrics.json (issue #244). Ignored when run_id is set.

• run_id (str | None) – Pin the run to this exact run id (resume into it if it exists, else create it under that name). Takes precedence over resume. Both are invocation-time directives: they are not part of the experiment identity and are not written back into the saved config.yaml.

Examples

The minimal slide-level run lives in Getting started. The variants below show how the other dataset_type values differ from it.

Tile-level pipeline

Tile-level runs use the same pipeline entry point, but keep aggregator set to None because the model operates on per-tile features directly:

from soma import EncoderConfig, EvalConfig, Pipeline, PipelineConfig, TaskConfig, TrainingConfig

config = PipelineConfig(
    dataset_csv="dataset.csv",
    splits_csv="splits.csv",
    output_root="output",
    dataset_type="tile",
    encoder=EncoderConfig(name="uni2"),
    aggregator=None,
    task=TaskConfig(name="binary_classification"),
    evaluation=EvalConfig(metrics=["accuracy"]),
    training=TrainingConfig(epochs=50, learning_rate=1e-4),
)

result = Pipeline(config).run()

Run outputs

The run directory layout is described in Run outputs.