Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mwalmsley/zoobot/llms.txt

Use this file to discover all available pages before exploring further.

FinetuneableZoobotAbstract is the parent class shared by all three Zoobot finetuning classes. It defines how to load a pretrained encoder, configure the AdamW optimizer with optional layer decay, and run training and validation steps via PyTorch Lightning. You cannot instantiate this class directly — use FinetuneableZoobotClassifier, FinetuneableZoobotRegressor, or FinetuneableZoobotTree instead. 
from zoobot.pytorch.training.finetune import (
    FinetuneableZoobotClassifier,   # classification tasks
    FinetuneableZoobotRegressor,    # regression tasks
    FinetuneableZoobotTree,         # Galaxy Zoo vote count trees
)

​
Loading a Pretrained Encoder

Any FinetuneableZoobot model can be loaded in one of three ways:

​
Constructor Parameters

These parameters are accepted by all three FinetuneableZoobot child classes (plus their own task-specific args).
​
name
str
HuggingFace Hub model name, e.g. 'hf_hub:mwalmsley/zoobot-encoder-convnext_nano'. Recommended for loading published pretrained models. Mutually exclusive with encoder and zoobot_checkpoint_loc.
​
encoder
torch.nn.Module
A PyTorch model already loaded in memory with a .forward() method. Mutually exclusive with name and zoobot_checkpoint_loc.
​
zoobot_checkpoint_loc
str
Path to a saved ZoobotTree or FinetuneableZoobotTree Lightning checkpoint from which the encoder is extracted. Mutually exclusive with name and encoder.
​
training_mode
str
default:"'full'"
Controls which parameters are trained. 'full' trains all parameters (encoder + head). 'head_only' freezes the encoder and only trains the new head (linear probing / transfer learning).
​
layer_decay
float
default:"0.75"
Learning rate decay applied per encoder layer block going deeper from the head. A value of 0.75 means each successive block has 0.75x the learning rate of the block above it. Set to 1.0 for no decay. Only applies when training_mode='full'.
​
weight_decay
float
default:"0.05"
L2 regularization penalty applied via AdamW. Higher values penalize large weights more strongly to prevent overfitting.
​
learning_rate
float
default:"1e-4"
Base learning rate for the AdamW optimizer. The head always uses this rate; encoder layers use learning_rate * layer_decay ** i.
​
head_dropout_prob
float
default:"0.5"
Probability of dropout applied to encoder output features before the final linear head layer. Acts as regularization.
​
scheduler_kwargs
dict
Arguments for an optional timm learning rate scheduler. Example: {'name': 'cosine', 'warmup_epochs': 5, 'max_epochs': 100}. Defaults to None (no scheduler).
​
timm_kwargs
dict
default:"{}"
Additional keyword arguments passed to timm.create_model() when loading an encoder by name. For example, {'drop_path_rate': 0.1}.
​
greyscale
bool
default:"False"
If True, adds {'in_chans': 1} to timm_kwargs to convert the encoder to single-channel input. Use when loading FITS images or other single-channel data.
​
prog_bar
bool
default:"True"
Whether to display a progress bar during training.
​
visualize_images
bool
default:"False"
Upload example validation images to Weights & Biases. Helpful for debugging data loading but may slow training.
​
seed
int
default:"42"
Random seed passed to lightning.seed_everything().

​
Methods

​
configure_optimizers()

Sets up the AdamW optimizer with layer-wise learning rate decay and an optional timm scheduler. When training_mode='head_only', the encoder is frozen and only self.head parameters are optimized.

​
load_from_name(name, **kwargs) (classmethod)

Download and load a previously finetuned model stored on HuggingFace Hub. The name argument is the HuggingFace repo ID. Internally calls hf_hub_download and then load_from_checkpoint. 
model = FinetuneableZoobotClassifier.load_from_name(
    'mwalmsley/my-finetuned-ring-classifier',
    num_classes=2
)

​
forward(x)

Passes x through the encoder then the head. Returns raw head outputs (logits for classifiers, raw scalars for regressors).

​
Subclassing for Custom Tasks

You can subclass FinetuneableZoobotAbstract to finetune Zoobot on tasks beyond classification, regression, and vote counts. At minimum you must set self.head, self.loss, and implement batch_to_supervised_tuple. 
from zoobot.pytorch.training.finetune import FinetuneableZoobotAbstract
import torch.nn as nn

class FinetuneableZoobotCustom(FinetuneableZoobotAbstract):
    def __init__(self, my_output_dim, **super_kwargs):
        super().__init__(**super_kwargs)
        self.head = nn.Linear(self.encoder_dim, my_output_dim)
        self.loss = nn.MSELoss()

    def batch_to_supervised_tuple(self, batch):
        return batch['image'], batch['my_label']
New to finetuning Zoobot? Start with the Finetuning Guide for a full end-to-end walkthrough, or the Advanced Finetuning guide for a complete worked example of custom subclassing.

Build docs developers (and LLMs) love

Get started for freeTalk to us