Linear Probing
Linear probing measures how useful an encoder's features are for classification. Asparagus freezes the encoder, keeps it in evaluation mode, and trains linear classification heads on globally averaged features from its final layer. Unlike fine-tuning, this leaves the encoder weights unchanged.
asp_linear_probe uses configs/default_linear_probe.yaml. It trains one head per candidate learning rate in a single run, selects the head with the highest validation macro AUROC, and automatically evaluates that head on the test set.
Prerequisites
- Install Asparagus and configure the environment variables, including
ASPARAGUS_CONFIGS,ASPARAGUS_DATA, andASPARAGUS_MODELS. - Prepare a classification dataset and split files. Each image must have a single integer class label; task metadata must include
n_classesandn_modalities. - Choose a classification model config compatible with your pretrained encoder. The example below uses
resenc_unet_b_clsregfor a matching residual UNet encoder. Custom models must acceptlate_fusion=Trueand expose_encode()features suitable for spatial average pooling. - Provide both a train/validation split and a held-out test split. The command runs testing automatically, so set
data.test_splitexplicitly to an existing split file name, without.json.
Run a Probe
Load a pretrained checkpoint by its run ID:
asp_linear_probe \
task=Task004_Name \
+model=resenc_unet_b_clsreg \
checkpoint_run_id=435850 \
load_checkpoint_name=last.ckpt \
data.train_split=split_75_15_10 \
data.test_split=TEST_75_15_10
Replace the task, checkpoint run ID, model config, and split names with your own. Match model.dimensions and training.target_size to the data and encoder; defaults are 3D for this model and [160,160,160] for the probe's target size.
To load a checkpoint directly, replace checkpoint_run_id and load_checkpoint_name with a path:
asp_linear_probe \
task=Task004_Name \
+model=resenc_unet_b_clsreg \
checkpoint_path=/path/to/last.ckpt \
data.train_split=split_75_15_10 \
data.test_split=TEST_75_15_10
You can also set hf_model_id=owner/model for an Asparagus-compatible Hugging Face checkpoint, with hf_weight_format configured if a different weight mapper is needed. Use only one checkpoint source: checkpoint_run_id, checkpoint_path, or hf_model_id. If none is supplied, the probe uses a randomly initialized, frozen encoder as a baseline.
Weights are loaded into the encoder without loading the pretrained decoder. Check the weight-loading output to confirm that the intended encoder weights were loaded.
Configure Training
Use Hydra overrides to adjust the learning-rate candidates and training settings:
asp_linear_probe \
task=Task004_Name \
+model=resenc_unet_b_clsreg \
checkpoint_run_id=435850 \
data.train_split=split_75_15_10 \
data.test_split=TEST_75_15_10 \
training.probing.learning_rates='[1e-4,1e-3,1e-2]' \
training.epochs=20 \
training.check_val_every_n_epoch=1 \
training.batch_size=8 \
training.target_size='[160,160,160]' \
training.seed=42 \
+hardware=1gpu12cpu
| Parameter | Purpose | Default |
|---|---|---|
training.probing.learning_rates |
Candidate initial learning rates; one head per value | [5e-5,1e-4,5e-4,1e-3,5e-3,1e-2,5e-2,1e-1] |
training.epochs |
Training epochs | 15 |
training.check_val_every_n_epoch |
Validation interval in epochs | 2 |
training.batch_size |
Training and validation batch size | 4 |
training.accumulate_grad_batches |
Batches accumulated per optimizer step | 2 |
training.target_size |
Spatial crop size | [160,160,160] |
training.pretrained_target_size |
Original spatial size when positional embeddings need resizing | unset |
training.seed |
Random seed | randomly generated |
data.fold |
Fold index in the train/validation split | 0 |
+hardware |
Hardware config to append | 1gpu40cpu |
logger.wandb_logging |
Enable Weights & Biases logging | True |
Use a non-empty list of distinct learning-rate candidates. Heads use SGD with momentum 0.9, no weight decay, and cosine learning-rate decay. The probe uses training.probing.learning_rates rather than model.finetune_lr or model.train_lr.
Validation runs before training and at the configured interval. Each validation pass selects the highest-AUROC head at that point; testing uses the selected head's current weights after training. Set training.check_val_every_n_epoch=1 to ensure selection also runs at the end of the final epoch.
Weights & Biases logging is enabled by default under the LinearProbe project. Configure your account as for other training workflows, or pass logger.wandb_logging=false to disable it.
To inspect the composed configuration without training, append --cfg job to your command. For reusable YAML configs and --config-name, see the Config Reference.
Results
The run prints its run ID and full run directory under $ASPARAGUS_MODELS. Predictions are written to:
<run_dir>/predictions/<test_task>__<data.test_split>__linear_probe.json
test_task defaults to task. The JSON contains the predicted class and label for each test sample, aggregate AUROC_macro, AUPRC_macro, and F1_macro metrics, and the selected best_head and best_head_lr. Per-head training and validation metrics and val/best_head_auroc are logged during the run.
Linear probing disables model checkpoint saving. The results describe an encoder evaluation; the trained heads are not saved for later use with asp_test_cls.