ncalab.training

Submodules

Classes

`EarlyStopping`	Early stopping helper class.
`BasicNCATrainer`	Trainer class for any model subclassing BasicNCA.
`TrainingHistory`	Stores data about the training progress. Populated during training
`TrainValRecord`	Helper class, storing a training / validation data split to generate
`SplitDefinition`	Stores a k-fold cross-validation split.
`KFoldCrossValidationTrainer`
`Pool`	Sample pool that retains previous predictions. Also applies damaging patterns to
`BasicNCATrainer`	Trainer class for any model subclassing BasicNCA.
`TrainingHistory`	Stores data about the training progress. Populated during training

Package Contents

class ncalab.training.EarlyStopping(patience: int, min_delta: float = 1e-06)

Early stopping helper class. Helps to stop the training if no change in validation metrics is observed.

Parameters:

patience (int) – Steps to wait until stopping the training.
min_delta (float) – Minimum deviation until counter is reset, defaults to 1e-6.

patience

min_delta = 1e-06

best_accuracy = 0.0

counter = 0

done() → bool

Checks whether the training can be stopped.

Needs to be queried in training loop, once per epoch.

Returns:: Whether to stop the training or not.
Return type:: bool

step(accuracy: float)

Increases internal counter if accuracy doesn’t improve, otherwise resets the counter.

Needs to be called in training loop, once per epoch.

Parameters:: accuracy (float) – Validation accuracy.

class ncalab.training.BasicNCATrainer(nca: ncalab.models.basicNCA.AbstractNCAModel, model_path: pathlib.Path | pathlib.PosixPath | None, gradient_clipping: bool = False, lr: float | None = None, lr_gamma: float = 0.99, adam_betas=(0.9, 0.95), batch_repeat: int = 2, max_epochs: int = 200, optimizer_method: str = 'adam', pool: ncalab.training.pool.Pool | None = None, lr_scheduler: torch.optim.lr_scheduler.LRScheduler | None = None)

Trainer class for any model subclassing BasicNCA.

Parameters:

nca (ncalab.AbstractNCAModel) – NCA model instance to train.
model_path (Path | PosixPath, optional) – Path to saved models. If None, models are not saved, defaults to None.
gradient_clipping (bool, optional) – Whether to clip gradients, defaults to False.
lr (float, optional) – Initial learning rate, defaults to 16e-4.
lr_gamma (float, optional) – Exponential learning rate decay, defaults to 0.9999.
adam_betas (tuple, optional) – Beta values for Adam optimizer, defaults to (0.9, 0.95).
batch_repeat – How often each batch will be duplicated, dfaults to 2.
max_epochs – Maximum number of epochs in training, defaults to 200.
optimizer_method (str, optional) – Optimization method, defaults to ‘adam’.
pool (ncalab.Pool) – Sample pool object.

nca

model_path

gradient_clipping = False

lr_gamma = 0.99

adam_betas = (0.9, 0.95)

batch_repeat = 2

max_epochs = 200

optimizer_method = 'adam'

pool = None

lr_scheduler = None

info() → str

Shows a markdown-formatted info string with training parameters. Useful for showing info on tensorboard to keep track of parameter changes.

Returns [str]:: Markdown-formatted info string.

_train_iteration(x: torch.Tensor, y: torch.Tensor, optimizer: torch.optim.Optimizer, head_optimizer: torch.optim.Optimizer | None, total_batch_iterations: int, summary_writer: torch.utils.tensorboard.SummaryWriter | None = None) → Tuple[ncalab.prediction.Prediction, Dict[str, torch.Tensor]]

Run a single training iteration.

Parameters:

x – Input training images.
y – Input training labels.
steps – Number of NCA inference time steps.
optimizer – Optimizer.
total_batch_iterations (int) – Total training batch iterations
summary_writer (SummaryWriter, optional) – Tensorboard SummaryWriter

Returns:

Predicted image.

Return type:

Tuple[Prediction, Dict[str, torch.Tensor]]

train(dataloader_train: torch.utils.data.DataLoader, dataloader_val: torch.utils.data.DataLoader | None = None, dataloader_test: torch.utils.data.DataLoader | None = None, save_every: int | None = None, summary_writer: torch.utils.tensorboard.SummaryWriter | None = None, plot_function: ncalab.visualization.Visual | None = None, earlystopping: ncalab.training.earlystopping.EarlyStopping | None = None) → ncalab.training.traininghistory.TrainingHistory

Execute basic NCA training loop with a single function call.

Parameters:

[DataLoader] (dataloader_val) – Training DataLoader
[DataLoader] – Validation DataLoader
[int] (save_every) – How often to save model state (in epochs). Useful for very small datasets, like growing lizard.

:param summary_writer [SummaryWriter] Tensorboard SummaryWriter. Defaults to None. :param plot_function: Plot function override. If None, use model’s default. Defaults to None. :param earlystopping (EarlyStopping, optional): EarlyStopping object. Defaults to None.

Returns [TrainingHistory]:: TrainingHistory object.

class ncalab.training.TrainingHistory(path: pathlib.Path | pathlib.PosixPath | None, metrics: Dict[str, float], current_epoch: int, current_model: ncalab.models.AbstractNCAModel, best_accuracy: float = 0, best_epoch: int = 0, best_model: ncalab.models.AbstractNCAModel | None = None, verbose: bool = True)

Stores data about the training progress. Populated during training with ncalab.training.BasicNCATrainer.

Parameters:

path (Optional[Path | PosixPath]) – Save and load path.
metrics (Dict[str, float]) – Dict of validation metrics
current_epoch (int) – Current training epoch.
current_model (AbstractNCAModel) – Currently trained model.
best_accuracy (float, optional) – Best validation accuracy, defaults to 0
best_epoch (int, optional) – Epoch of best validation accuracy, defaults to 0
best_model (Optional[AbstractNCAModel], optional) – Model with best validation accuracy, defaults to None
verbose (bool, optional) – Whether to print updates of validation accuracy, defaults to True

path

metrics

current_epoch

current_model

best_accuracy = 0

best_epoch = 0

best_model = None

verbose = True

created_timestamp

modified_timestamp

loss: List[float] = []

update(epoch: int, model: ncalab.models.AbstractNCAModel, accuracy: float, overwrite: bool = False)

Populates history with current iteration’s values.

Automatically recognizes changes in accuracy.

Parameters:

epoch (int) – Current epoch
model (AbstractNCAModel) – Current model
accuracy (float) – Current accuracy, based on model’s validation metric
overwrite (bool, optional) – Whether to overwrite best accuracy even with no improvement, defaults to False

save(): Saves history and model checkpoint.

to_dict() → Dict

Return dict of recorded values

Returns:: Dict of recorded values
Return type:: Dict

class ncalab.training.TrainValRecord(train: List[str], val: List[str])

Helper class, storing a training / validation data split to generate respective DataLoader objects.

Parameters:

train (List[str]) – List of training image file paths
val (List[str]) – List of validation image file paths

train

val

dataloaders(DatasetType: Type, path: pathlib.Path | pathlib.PosixPath, transform=None, batch_sizes=None): Generate a pair of training and validation DataLoader objects, based on a given DataSet subtype.

class ncalab.training.SplitDefinition

Stores a k-fold cross-validation split.

folds = []

dataloader_test = None

static read(path: pathlib.PosixPath) → SplitDefinition

Reads json files with split definitions, similar to those created by nnUNet.

Format is like

[
    {
        "train": [ "filename0", "filename1",... ]
        "val": [ "filename2", "filename3",... ]
    },
    {
        ...
    }
]

Parameters:: path – Path to JSON file containing split definition.
Returns:: SplitDefinition object
Return type:: SplitDefinition

__len__() → int

__getitem__(idx) → TrainValRecord

class ncalab.training.KFoldCrossValidationTrainer(trainer: ncalab.training.trainer.BasicNCATrainer, split: SplitDefinition)

Parameters:

[BasicNCATrainer] (trainer) – BasicNCATrainer, to train each individual fold.
[SplitDefinition] (split) – Definition of the split used for k-fold cross-training.

trainer

model_prototype

model_name

split

train(DatasetType: Type, datapath: pathlib.Path | pathlib.PosixPath, transform, batch_sizes: None | Dict = None, save_every: int | None = None) → List[ncalab.training.traininghistory.TrainingHistory]

Run training loop with a single function call.

Parameters:

[Type] (DatasetType) – Type of dataset class to use.
[Path] (datapath) – _description_
transform – Data transform, e.g. initialized via Albumentations.
batch_sizes – Dict of batch sizes per set, e.g. {“train”: 8, “val”: 16}. Defaults to None.
[int] (save_every) – _description_. Defaults to None.
plot_function – Plot function override. If None, use model’s default. Defaults to None.

Returns [List[TrainingHistory]]:

List of TrainingHistory objects, one per fold.

class ncalab.training.Pool(n_seed: int = 1, damage: bool = False, p_damage: float = 0.2)

Sample pool that retains previous predictions. Also applies damaging patterns to images to increase the robustness of the trained NCA.

Parameters:

n_seed (int, optional) – How many seed images to retain, defaults to 1
damage (bool, optional) – Whether to apply damaging patterns, defaults to False
p_damage (float, optional) – Probability at which a damaging pattern is applied, defaults to 0.2

n_seed = 1

damage = False

batch: torch.Tensor | None = None

p_damage = 0.2

update(batch: torch.Tensor)

Parameters:: batch – BCWH

sample(seed: torch.Tensor) → torch.Tensor

Parameters:: seed – BCWH
Returns:: BCWH

class ncalab.training.BasicNCATrainer(nca: ncalab.models.basicNCA.AbstractNCAModel, model_path: pathlib.Path | pathlib.PosixPath | None, gradient_clipping: bool = False, lr: float | None = None, lr_gamma: float = 0.99, adam_betas=(0.9, 0.95), batch_repeat: int = 2, max_epochs: int = 200, optimizer_method: str = 'adam', pool: ncalab.training.pool.Pool | None = None, lr_scheduler: torch.optim.lr_scheduler.LRScheduler | None = None)

Trainer class for any model subclassing BasicNCA.

Parameters:

nca (ncalab.AbstractNCAModel) – NCA model instance to train.
model_path (Path | PosixPath, optional) – Path to saved models. If None, models are not saved, defaults to None.
gradient_clipping (bool, optional) – Whether to clip gradients, defaults to False.
lr (float, optional) – Initial learning rate, defaults to 16e-4.
lr_gamma (float, optional) – Exponential learning rate decay, defaults to 0.9999.
adam_betas (tuple, optional) – Beta values for Adam optimizer, defaults to (0.9, 0.95).
batch_repeat – How often each batch will be duplicated, dfaults to 2.
max_epochs – Maximum number of epochs in training, defaults to 200.
optimizer_method (str, optional) – Optimization method, defaults to ‘adam’.
pool (ncalab.Pool) – Sample pool object.

nca

model_path

gradient_clipping = False

lr_gamma = 0.99

adam_betas = (0.9, 0.95)

batch_repeat = 2

max_epochs = 200

optimizer_method = 'adam'

pool = None

lr_scheduler = None

info() → str

Shows a markdown-formatted info string with training parameters. Useful for showing info on tensorboard to keep track of parameter changes.

Returns [str]:: Markdown-formatted info string.

_train_iteration(x: torch.Tensor, y: torch.Tensor, optimizer: torch.optim.Optimizer, head_optimizer: torch.optim.Optimizer | None, total_batch_iterations: int, summary_writer: torch.utils.tensorboard.SummaryWriter | None = None) → Tuple[ncalab.prediction.Prediction, Dict[str, torch.Tensor]]

Run a single training iteration.

Parameters:

x – Input training images.
y – Input training labels.
steps – Number of NCA inference time steps.
optimizer – Optimizer.
total_batch_iterations (int) – Total training batch iterations
summary_writer (SummaryWriter, optional) – Tensorboard SummaryWriter

Returns:

Predicted image.

Return type:

Tuple[Prediction, Dict[str, torch.Tensor]]

train(dataloader_train: torch.utils.data.DataLoader, dataloader_val: torch.utils.data.DataLoader | None = None, dataloader_test: torch.utils.data.DataLoader | None = None, save_every: int | None = None, summary_writer: torch.utils.tensorboard.SummaryWriter | None = None, plot_function: ncalab.visualization.Visual | None = None, earlystopping: ncalab.training.earlystopping.EarlyStopping | None = None) → ncalab.training.traininghistory.TrainingHistory

Execute basic NCA training loop with a single function call.

Parameters:

[DataLoader] (dataloader_val) – Training DataLoader
[DataLoader] – Validation DataLoader
[int] (save_every) – How often to save model state (in epochs). Useful for very small datasets, like growing lizard.

:param summary_writer [SummaryWriter] Tensorboard SummaryWriter. Defaults to None. :param plot_function: Plot function override. If None, use model’s default. Defaults to None. :param earlystopping (EarlyStopping, optional): EarlyStopping object. Defaults to None.

Returns [TrainingHistory]:: TrainingHistory object.

class ncalab.training.TrainingHistory(path: pathlib.Path | pathlib.PosixPath | None, metrics: Dict[str, float], current_epoch: int, current_model: ncalab.models.AbstractNCAModel, best_accuracy: float = 0, best_epoch: int = 0, best_model: ncalab.models.AbstractNCAModel | None = None, verbose: bool = True)

Stores data about the training progress. Populated during training with ncalab.training.BasicNCATrainer.

Parameters:

path (Optional[Path | PosixPath]) – Save and load path.
metrics (Dict[str, float]) – Dict of validation metrics
current_epoch (int) – Current training epoch.
current_model (AbstractNCAModel) – Currently trained model.
best_accuracy (float, optional) – Best validation accuracy, defaults to 0
best_epoch (int, optional) – Epoch of best validation accuracy, defaults to 0
best_model (Optional[AbstractNCAModel], optional) – Model with best validation accuracy, defaults to None
verbose (bool, optional) – Whether to print updates of validation accuracy, defaults to True

path

metrics

current_epoch

current_model

best_accuracy = 0

best_epoch = 0

best_model = None

verbose = True

created_timestamp

modified_timestamp

loss: List[float] = []

update(epoch: int, model: ncalab.models.AbstractNCAModel, accuracy: float, overwrite: bool = False)

Populates history with current iteration’s values.

Automatically recognizes changes in accuracy.

Parameters:

epoch (int) – Current epoch
model (AbstractNCAModel) – Current model
accuracy (float) – Current accuracy, based on model’s validation metric
overwrite (bool, optional) – Whether to overwrite best accuracy even with no improvement, defaults to False

save(): Saves history and model checkpoint.

to_dict() → Dict

Return dict of recorded values

Returns:: Dict of recorded values
Return type:: Dict