Builder

The Builder is the core class of biom3d. It is used to train a model or to test a model in a couple of lines of code.

class biom3d.builder.Builder(config=None, path=None, training=True)

The Builder is the core of biom3d.

The Builder reads a configuration file and builds the components required for training and prediction.

Please note that in this current version the training and inference can only be done with CUDA.

Multi-GPUs training is also supported with DataParallel only (Distributed Data Parallel is not).

Training is currently done with the SGD optimizer. If you would like to change the optimizer, you can edit self.build_training method.

If both config and path are defined then Builder considers that fine-tuning is intended.

If path is a list of path, then multi-model prediction will be used, training should be off/False.

Parameters

• config (str, dict or biom3d.utils.Dict) – Path to a Python configuration file (in either .py or .yaml format) or dictionary of a configuration file. Please refer to biom3d.config_default.py to see the default configuration file format.

• path (str, list of str) – Path to a builder folder which contains the model folder, the model configuration and the training logs. If path is a list of strings, then it is considered that it is intended to run multi-model predictions. Training is not compatible with this mode.

• training (bool, default=True) – Whether to load the model in training or testing mode.

Examples

To run a training from a configuration file do:

>>> from importlib import import_module
>>> cfg = import_module("biom3d.configs.unet_default").CONFIG
>>> builder = Builder(config=cfg)
>>> builder.run_training() # start the training

To run a prediction from a log folder, do:

>>> path = "path/to/log/folder"
>>> builder = Builder(path=path, training=False)
>>> builder.run_prediction_folder(dir_in="input/folder", dir_out="output/folder")

build_callbacks()

Build the callbacks for the training process. Callback are used to monitor the training process and to update the schedulers.

As the callbacks are often dependant on the Builder arguments, they are defined directly here.

build_dataset()

Build the dataset.

build_model(training=True)

Build the model, the losses and the metrics.

build_train()

Successively build the dataset, the model and the callbacks.

load_test(path, load_best=True)

Load a builder from a folder. The folder should have been created by the self.build_train method. Can be used to test the model on unseen data.

Parameters

• path (str) – Path of the log folder.

• load_best (bool, default=True) – Whether to load the best model or the final model.

load_train(path, load_best=False)

Load a builder from a folder. The folder should have been created by the self.build_train method. Can be use to restart a training.

Parameters

• path (str) – Path of the log folder.

• load_best (bool, default=False) – Whether to load the best model or the final model.

run_prediction_folder(dir_in, dir_out, return_logit=False)

Compute predictions for a folder of images.

Parameters

• dir_in (str) – Path to the input folder of images.

• dir_out (str) – Path to the output folder where the predictions will be stored.

• return_logit (bool, default=False) – Whether to save the logit, i.e. the model output before the final activation.

run_prediction_single(img_path=None, img=None, img_meta=None, return_logit=True)

Compute a prediction for one image using the predictor defined in the configuration file. Two input options are available: either give the image path or the image and its associated metadata.

Parameters

• img_path (str) – Path to the image.

• img (numpy.ndarray) – The entire image, required if the img_path is not provided.

• img_meta (dict) – Metadata of the image, required it the img_path is not provided.

• return_logit (bool, default=True) – Whether to return the logit, i.e. the model output before the final activation.

Returns

Output images.

Return type

numpy.ndarray

run_training()

Run the training and validation routines.

class biom3d.builder.LARS(params, lr=0, weight_decay=0, momentum=0.9, eta=0.001, weight_decay_filter=None, lars_adaptation_filter=None)

Almost copy-paste from https://github.com/facebookresearch/barlowtwins/blob/main/main.py

step()

Performs a single optimization step (parameter update).

Parameters

closure (Callable) – A closure that reevaluates the model and returns the loss. Optional for most optimizers.

Note

Unless otherwise specified, this function should not modify the .grad field of the parameters.

biom3d.builder.read_config(config_fct, register_cat, **kwargs)

Read the config function in the register category and run the corresponding function with the keyword arguments which are merged from 1. the register kwargs, 2. the config file kwargs and 3. this function kwargs.

Parameters

• config_fct (str) – Name of the function listed in the register.

• register_cat (Dict) – Dictionary defining one category in the register.

• **kwargs (dict, optional) – Additional keyword arguments of the function defined by the config_fct

Returns

Return type

The eventual outputs of the function.