Training (programmatic API)#

physioex.train is a hand-written PyTorch training/evaluation loop (not PyTorch Lightning). The programmatic entry point is physioex.train.trainer.Trainer, a stateless helper exposing only static/class methods; models are plain torch.nn.Modules.

For most workflows the end-user entry points are the command-line tools (train, finetune, test_model) documented on the CLI page. This page covers the underlying Python API. For the full class diagram see the train-layer architecture page.

Trainer at a glance#

Trainer methods accept any dataset exposing .split(fold) and .sequence_length — i.e. a BasePhysioDataset or a MultiDataset — and wire dict_collate_fn automatically. Key methods:

  • build_dataloaders(dataset, train_batch_size=32, eval_batch_size=1, ..., fold=0) — returns (train_loader, val_loader).

  • train(model, dataset, checkpoint_path=None, max_epochs=10, lr=1e-3, weight_decay=1e-5, ...) — runs the epoch loop (AMP, gradient accumulation, optional early stopping, pluggable logger) and returns the trained model.

  • evaluate(model, dataset, metrics=..., ...) — standard evaluation, returns a metrics dict.

  • voting_evaluate(model, dataset, L=21, ...) — sliding-window per-subject voting evaluation over full-night sequences.

  • save_checkpoint(model, path, epoch=None, optimizer=None) / load_checkpoint(model, path, optimizer=None) — dual-format (.pt / Lightning .ckpt) checkpoint I/O.

The module-level physioex.train.trainer.seed_everything(seed=42) seeds Python, NumPy and PyTorch RNGs.

Example#

The Trainer methods are static/class methods, so you call them directly on the class — no instance is created:

import torch
from physioex.data.datasets import get_dataset
from physioex.train.trainer import Trainer, seed_everything
from physioex.models.tinysleepnet import TinySleepNet

seed_everything(42)

# 1. Build a dataset (raw-EDF, lazy) — see the Data and Preprocessing pages.
dataset = get_dataset("hmc")(
    channels=["EEG"], pipelines="time_domain", sequence_length=21,
)

# 2. Build a model (a plain nn.Module). in_chan matches the channel count.
model = TinySleepNet(n_classes=5, in_chan=1)

# 3. Train. Trainer builds the dataloaders internally from the dataset.
model = Trainer.train(
    model=model,
    dataset=dataset,
    checkpoint_path="runs/tsn",
    max_epochs=20,
    lr=1e-3,
    fold=0,
)

# 4. Evaluate with sliding-window voting.
metrics = Trainer.voting_evaluate(model=model, dataset=dataset, L=21, fold=0)
print(metrics)

Note

The exact constructor arguments differ per model (n_classes, in_chan, and model-specific hyper-parameters). Consult each architecture’s signature in the API Reference or the models architecture page before instantiating.

Fine-tuning is the same train call starting from a loaded checkpoint (a lower learning rate is typical). Multi-GPU DDP training is available via physioex.train.multidevicetrainer.MultiDeviceTrainer, which subclasses Trainer on the same data path.

API#

class physioex.train.trainer.Trainer[source]

Bases: object

classmethod voting_evaluate(model, dataset, L=21, metrics=None, batch_size=1, num_workers=None, pin_memory=False, prefetch_factor=2, persistent_workers=False, fold=0, gpu_id=None, ignore_index=-1, seed=42, per_subject=False, ci_method='bootstrap', n_bootstrap=1000)[source]

Evaluate using sliding-window voting over full-night sequences.

For each subject, the night is scanned with L-length windows at L different starting offsets (0 to L-1). Predictions from overlapping windows are averaged. This matches the evaluation protocol of the current library’s voting_strategy().

Parameters:

  • model (Module) – model with forward(x) accepting shape (batch, L, …) and returning (batch, L, n_classes)

  • dataset (PhysioExDataset | DataLoader) – a PhysioExDataset (will be wrapped in eval loader) OR a DataLoader

  • L (int) – sequence length the model was trained on (default 21)

  • metrics (dict) – dict of metric_name -> callable(preds, targets, ignore_index=…). Defaults to accuracy/f1/precision/recall/cohen_kappa/confusion_matrix/support.

  • ignore_index (int) – label value for padded epochs (default -1)

  • batch_size (int)

  • num_workers (int)

  • pin_memory (bool)

  • prefetch_factor (int)

  • persistent_workers (bool)

  • fold (int)

  • gpu_id (int)

  • seed (int)

  • per_subject (bool)

  • ci_method (str)

  • n_bootstrap (int)

Returns:

dict of metric_name -> value

Return type:

dict

physioex.train.trainer.seed_everything(seed=42)[source]

Seed all relevant RNGs for reproducibility.

Parameters:

seed (int)

See the full auto-generated API Reference for metrics, statistics and logging helpers.

On this page

This Page