Model training

Given suitable training data (see Training data generation), we can define and train a CARE model to restore the source data. To that end, we first need to specify all the options of the model by creating a configuration object via csbdeep.models.Config. Note that we provide sensible default configuration options that should work in many cases. However, you can overwrite them via keyword arguments.

Please see Model overview to choose among the supported restoration models. While training data generation and prediction typically differs among the models, note that the training process is mostly the same for all models. For example, a standard (denoising) CARE model can be instantiated via csbdeep.models.CARE and then trained with the csbdeep.models.CARE.train() method. After training, the learned model can be exported via csbdeep.models.CARE.export_TF() to be used with our Fiji Plugin.

Example

>>> from csbdeep.io import load_training_data
>>> from csbdeep.models import Config, CARE
>>> (X,Y), (X_val,Y_val), axes = load_training_data('my_data.npz', validation_split=0.1)
>>> config = Config(axes)
>>> model = CARE(config, 'my_model')
>>> model.train(X,Y, validation_data=(X_val,Y_val))
>>> model.export_TF()
class csbdeep.models.Config(axes, n_channel_in=1, n_channel_out=1, probabilistic=False, **kwargs)[source]

Default configuration for a CARE model.

This configuration is meant to be used with CARE and related models (e.g., IsotropicCARE).

Parameters:
  • axes (str) – Axes of the neural network (channel axis optional).
  • n_channel_in (int) – Number of channels of given input image.
  • n_channel_out (int) – Number of channels of predicted output image.
  • probabilistic (bool) – Probabilistic prediction of per-pixel Laplace distributions or typical regression of per-pixel scalar values.
  • kwargs (dict) – Overwrite (or add) configuration attributes (see below).

Example

>>> config = Config('YX', probabilistic=True, unet_n_depth=3)
n_dim

int – Dimensionality of input images (2 or 3).

unet_residual

bool – Parameter residual of csbdeep.nets.common_unet(). Default: n_channel_in == n_channel_out

unet_n_depth

int – Parameter n_depth of csbdeep.nets.common_unet(). Default: 2

unet_kern_size

int – Parameter kern_size of csbdeep.nets.common_unet(). Default: 5 if n_dim==2 else 3

unet_n_first

int – Parameter n_first of csbdeep.nets.common_unet(). Default: 32

unet_last_activation

str – Parameter last_activation of csbdeep.nets.common_unet(). Default: linear

train_loss

str – Name of training loss. Default: 'laplace' if probabilistic else 'mae'

train_epochs

int – Number of training epochs. Default: 100

train_steps_per_epoch

int – Number of parameter update steps per epoch. Default: 400

train_learning_rate

float – Learning rate for training. Default: 0.0004

train_batch_size

int – Batch size for training. Default: 16

train_tensorboard

bool – Enable TensorBoard for monitoring training progress. Default: True

train_checkpoint

str – Name of checkpoint file for model weights (only best are saved); set to None to disable. Default: weights_best.h5

train_reduce_lr

dict – Parameter dict of ReduceLROnPlateau callback; set to None to disable. Default: {'factor': 0.5, 'patience': 10, 'min_delta': 0}

is_valid(return_invalid=False)[source]

Check if configuration is valid.

Returns:Flag that indicates whether the current configuration values are valid.
Return type:bool
class csbdeep.models.CARE(config, name=None, basedir='.')[source]

Standard CARE network for image restoration and enhancement.

Uses a convolutional neural network created by csbdeep.internals.nets.common_unet(). Note that isotropic reconstruction and manifold extraction/projection are not supported here (see csbdeep.models.IsotropicCARE ).

Parameters:
  • config (csbdeep.models.Config or None) – Valid configuration of CARE network (see Config.is_valid()). Will be saved to disk as JSON (config.json). If set to None, will be loaded from disk (must exist).
  • name (str or None) – Model name. Uses a timestamp if set to None (default).
  • basedir (str) – Directory that contains (or will contain) a folder with the given model name. Use None to disable saving (or loading) any data to (or from) disk (regardless of other parameters).
Raises:
  • FileNotFoundError – If config=None and config cannot be loaded from disk.
  • ValueError – Illegal arguments, including invalid configuration.

Example

>>> model = CARE(config, 'my_model')
config

csbdeep.models.Config – Configuration of CARE network, as provided during instantiation.

keras_model

Keras model – Keras neural network model.

name

str – Model name.

logdir

pathlib.Path – Path to model folder (which stores configuration, weights, etc.)

export_TF(fname=None)[source]

Export neural network via csbdeep.utils.tf.export_SavedModel().

Parameters:fname (str or None) – Path of the created SavedModel archive (will end with “.zip”). If None, “<model-directory>/TF_SavedModel.zip” will be used.
load_weights(name='weights_best.h5')[source]

Load neural network weights from model folder.

Parameters:name (str) – Name of HDF5 weight file (as saved during or after training).
predict(img, axes, normalizer=<csbdeep.data.prepare.PercentileNormalizer object>, resizer=<csbdeep.data.prepare.PadAndCropResizer object>, n_tiles=None)[source]

Apply neural network to raw image to predict restored image.

Parameters:
  • img (numpy.ndarray) – Raw input image
  • axes (str) – Axes of the input img.
  • normalizer (csbdeep.data.Normalizer or None) – Normalization of input image before prediction and (potentially) transformation back after prediction.
  • resizer (csbdeep.data.Resizer or None) – If necessary, input image is resized to enable neural network prediction and result is (possibly) resized to yield original image size.
  • n_tiles (iterable or None) – Out of memory (OOM) errors can occur if the input image is too large. To avoid this problem, the input image is broken up into (overlapping) tiles that can then be processed independently and re-assembled to yield the restored image. This parameter denotes a tuple of the number of tiles for every image axis. Note that if the number of tiles is too low, it is adaptively increased until OOM errors are avoided, albeit at the expense of runtime. A value of None denotes that no tiling should initially be used.
Returns:

Returns the restored image. If the model is probabilistic, this denotes the mean parameter of the predicted per-pixel Laplace distributions (i.e., the expected restored image). Axes semantics are the same as in the input image. Only if the output is multi-channel and the input image didn’t have a channel axis, then output channels are appended at the end.

Return type:

numpy.ndarray

predict_probabilistic(img, axes, normalizer=<csbdeep.data.prepare.PercentileNormalizer object>, resizer=<csbdeep.data.prepare.PadAndCropResizer object>, n_tiles=None)[source]

Apply neural network to raw image to predict probability distribution for restored image.

See predict() for parameter explanations.

Returns:Returns the probability distribution of the restored image.
Return type:csbdeep.internals.probability.ProbabilisticPrediction
Raises:ValueError – If this is not a probabilistic model.
prepare_for_training(optimizer=None, **kwargs)[source]

Prepare for neural network training.

Calls csbdeep.internals.train.prepare_model() and creates Keras Callbacks to be used for training.

Note that this method will be implicitly called once by train() (with default arguments) if not done so explicitly beforehand.

Parameters:
train(X, Y, validation_data, epochs=None, steps_per_epoch=None)[source]

Train the neural network with the given data.

Parameters:
  • X (numpy.ndarray) – Array of source images.
  • Y (numpy.ndarray) – Array of target images.
  • validation_data (tuple(numpy.ndarray, numpy.ndarray)) – Tuple of arrays for source and target validation images.
  • epochs (int) – Optional argument to use instead of the value from config.
  • steps_per_epoch (int) – Optional argument to use instead of the value from config.
Returns:

See Keras training history.

Return type:

History object

Supporting functions:

csbdeep.io.load_training_data(file, validation_split=0, axes=None, n_images=None, verbose=False)[source]

Load training data from file in .npz format.

The data file is expected to have the keys:

  • X : Array of training input images.
  • Y : Array of corresponding target images.
  • axes : Axes of the training images.
Parameters:
  • file (str) – File name
  • validation_split (float) – Fraction of images to use as validation set during training.
  • axes (str, optional) – Must be provided in case the loaded data does not contain axes information.
  • n_images (int, optional) – Can be used to limit the number of images loaded from data.
  • verbose (bool, optional) – Can be used to display information about the loaded images.
Returns:

Returns two tuples (X_train, Y_train), (X_val, Y_val) of training and validation sets and the axes of the input images. The tuple of validation data will be None if validation_split = 0.

Return type:

tuple( tuple(numpy.ndarray, numpy.ndarray), tuple(numpy.ndarray, numpy.ndarray), str )

csbdeep.internals.nets.common_unet(n_dim=2, n_depth=1, kern_size=3, n_first=16, n_channel_out=1, residual=True, prob_out=False, last_activation='linear')[source]

Construct a common CARE neural net based on U-Net [1] and residual learning [2] to be used for image restoration/enhancement.

Parameters:
  • n_dim (int) – number of image dimensions (2 or 3)
  • n_depth (int) – number of resolution levels of U-Net architecture
  • kern_size (int) – size of convolution filter in all image dimensions
  • n_first (int) – number of convolution filters for first U-Net resolution level (value is doubled after each downsampling operation)
  • n_channel_out (int) – number of channels of the predicted output image
  • residual (bool) – if True, model will internally predict the residual w.r.t. the input (typically better) requires number of input and output image channels to be equal
  • prob_out (bool) – standard regression (False) or probabilistic prediction (True) if True, model will predict two values for each input pixel (mean and positive scale value)
  • last_activation (str) – name of activation function for the final output layer
Returns:

Function to construct the network, which takes as argument the shape of the input image

Return type:

function

Example

>>> model = common_unet(2, 1,3,16, 1, True, False)(input_shape)

References

[1]Olaf Ronneberger, Philipp Fischer, Thomas Brox, U-Net: Convolutional Networks for Biomedical Image Segmentation, MICCAI 2015
[2]Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun. Deep Residual Learning for Image Recognition, CVPR 2016
csbdeep.internals.train.prepare_model(model, optimizer, loss, metrics=('mse', 'mae'), loss_bg_thresh=0, loss_bg_decay=0.06, Y=None)[source]

TODO

csbdeep.utils.tf.export_SavedModel(model, outpath, meta={}, format='zip')[source]

Export Keras model in TensorFlow’s SavedModel format.

See Your Model in Fiji to learn how to use the exported model with our CSBDeep Fiji plugins.

Parameters:
  • model (keras.models.Model) – Keras model to be exported.
  • outpath (str) – Path of the file/folder that the model will exported to.
  • meta (dict, optional) – Metadata to be saved in an additional meta.json file.
  • format (str, optional) – Can be ‘dir’ to export as a directory or ‘zip’ (default) to export as a ZIP file.
Raises:

ValueError – Illegal arguments.

Other models

Training other CARE models (csbdeep.models.IsotropicCARE, csbdeep.models.UpsamplingCARE, csbdeep.models.ProjectionCARE) currently does not differ from that of a standard model. What changes is the way in which the training data is generated (see Training data generation).