Model application

After training a CARE model, we can apply it to raw images that we want to restore.

Note

Alternatively, you can call csbdeep.models.CARE.export_TF() to export the model and use it with our Fiji Plugin.

We first create a CARE model with the same name that we have previously used for training it. By not providing a configuration (config = None), it will automatically be loaded from the model’s folder. Furthermore, the model’s weights (parameters) are automatically loaded. However, you can also manually load specific weights by invoking csbdeep.models.CARE.load_weights(). Finally, the model can be applied to a raw image with predict(), using sensible raw image preparation by default (see Image preparation for details and options).

Examples

>>> from tifffile import imread
>>> from csbdeep.models import CARE
>>> model = CARE(config=None, name='my_model')
>>> x = imread('my_image.tif')
>>> restored = model.predict(x, axes='YX')
>>> from tifffile import imread
>>> from csbdeep.models import IsotropicCARE
>>> model = CARE(config=None, name='my_model')
>>> x = imread('my_image.tif')
>>> restored = model.predict(x, axes='ZYX', factor=4)
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.)

load_weights(name='weights_best.h5')

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.
class csbdeep.models.IsotropicCARE(config, name=None, basedir='.')[source]

CARE network for isotropic image reconstruction.

Extends csbdeep.models.CARE by replacing prediction (predict(), predict_probabilistic()) to do isotropic reconstruction.

predict(img, axes, factor, normalizer=<csbdeep.data.prepare.PercentileNormalizer object>, resizer=<csbdeep.data.prepare.PadAndCropResizer object>, batch_size=8)[source]

Apply neural network to raw image for isotropic reconstruction.

See CARE.predict() for documentation.

Parameters:
  • factor (float) – Upsampling factor for Z axis. It is important that this is chosen in correspondence to the subsampling factor used during training data generation.
  • batch_size (int) – Number of image slices that are processed together by the neural network. Reduce this value if out of memory errors occur.
predict_probabilistic(img, axes, factor, normalizer=<csbdeep.data.prepare.PercentileNormalizer object>, resizer=<csbdeep.data.prepare.PadAndCropResizer object>, batch_size=8)[source]

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

See CARE.predict_probabilistic() for documentation.

Parameters:
  • factor (float) – Upsampling factor for Z axis. It is important that this is chosen in correspondence to the subsampling factor used during training data generation.
  • batch_size (int) – Number of image slices that are processed together by the neural network. Reduce this value if out of memory errors occur.
class csbdeep.models.UpsamplingCARE(config, name=None, basedir='.')[source]

CARE network for combined image restoration and upsampling of one dimension.

Extends csbdeep.models.CARE by replacing prediction (predict(), predict_probabilistic()) to first upsample Z before image restoration.

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

Apply neural network to raw image with low-resolution Z axis.

See CARE.predict() for documentation.

Parameters:factor (float) – Upsampling factor for Z axis. It is important that this is chosen in correspondence to the subsampling factor used during training data generation.
predict_probabilistic(img, axes, factor, normalizer=<csbdeep.data.prepare.PercentileNormalizer object>, resizer=<csbdeep.data.prepare.PadAndCropResizer object>, n_tiles=None)[source]

Apply neural network to raw image with low-resolution Z axis for probabilistic prediction.

See CARE.predict_probabilistic() for documentation.

Parameters:factor (float) – Upsampling factor for Z axis. It is important that this is chosen in correspondence to the subsampling factor used during training data generation.
class csbdeep.models.ProjectionCARE(config, name=None, basedir='.')[source]

CARE network for combined image restoration and projection of one dimension.

Return type for probabilistic prediction:

class csbdeep.internals.probability.ProbabilisticPrediction(loc, scale)[source]

Laplace distribution (independently per pixel).

Image preparation

Before a CARE model can be applied to a raw input image, we first need to specify image normalization and resizing methods. By default, we use csbdeep.predict.PercentileNormalizer with sensible low and high percentile values (compatible to the defaults used for training data generation). Furthermore, although a CARE model can be applied to various image sizes after training, some image dimensions must be divisible by powers of two, depending on the depth of the neural network. To that end, we recommend to use csbdeep.predict.PadAndCropResizer, which, if necessary, will enlarge the image by a few pixels before prediction and remove those additional pixels afterwards, such that the size of the raw input image is retained.

Normalization

All normalization methods must subclass csbdeep.data.Normalizer.

class csbdeep.data.Normalizer[source]

Abstract base class for normalization methods.

after(mean, scale, axes)[source]

Possible adjustment of predicted restored image (method stub).

Parameters:
  • mean (numpy.ndarray) – Predicted restored image or per-pixel mean of Laplace distributions for probabilistic model.
  • scale (numpy.ndarray or None) – Per-pixel scale of Laplace distributions for probabilistic model (None otherwise.)
  • axes (str) – Axes of mean and scale
Returns:

Adjusted restored image(s).

Return type:

numpy.ndarray

before(x, axes)[source]

Normalization of the raw input image (method stub).

Parameters:
Returns:

Normalized input image with suitable values for neural network input.

Return type:

numpy.ndarray

do_after

bool – Flag to indicate whether after() should be called.

class csbdeep.data.NoNormalizer(do_after=False)[source]

No normalization.

Parameters:do_after (bool) – Flag to indicate whether to undo normalization.
Raises:ValueError – If after() is called, but parameter do_after was set to False in the constructor.
class csbdeep.data.PercentileNormalizer(pmin=2, pmax=99.8, do_after=True, dtype=<class 'numpy.float32'>, **kwargs)[source]

Percentile-based image normalization.

Parameters:
  • pmin (float) – Low percentile.
  • pmax (float) – High percentile.
  • do_after (bool) – Flag to indicate whether to undo normalization (original data type will not be restored).
  • dtype (type) – Data type after normalization.
  • kwargs (dict) – Keyword arguments for csbdeep.utils.normalize_mi_ma().
after(mean, scale, axes)[source]

Undo percentile-based normalization to map restored image to similar range as input image.

See csbdeep.predict.Normalizer.after() for parameter descriptions.

Raises:ValueError – If parameter do_after was set to False in the constructor.
before(x, axes)[source]

Percentile-based normalization of raw input image.

See csbdeep.predict.Normalizer.before() for parameter descriptions. Note that percentiles are computed individually for each channel (if present in axes).

do_after

do_after parameter from constructor.

Resizing

All resizing methods must subclass csbdeep.data.Resizer.

class csbdeep.data.Resizer[source]

Abstract base class for resizing methods.

after(x, axes)[source]

Resizing of the restored image (method stub).

Parameters:
Returns:

Resized restored image.

Return type:

numpy.ndarray

before(x, axes, axes_div_by)[source]

Resizing of the raw input image (method stub).

Parameters:
  • x (numpy.ndarray) – Raw input image.
  • axes (str) – Axes of input image x
  • axes_div_by (iterable of int) – Resized image must be evenly divisible by the provided values for each axis.
Returns:

Resized input image.

Return type:

numpy.ndarray

class csbdeep.data.NoResizer[source]

No resizing.

Raises:ValueError – In before(), if image resizing is necessary.
class csbdeep.data.PadAndCropResizer(mode='reflect', **kwargs)[source]

Resize image by padding and cropping.

If necessary, input image is padded before prediction and restored image is cropped back to size of input image after prediction.

Parameters:
after(x, axes)[source]

Crop restored image to retain size of input image.

See csbdeep.predict.Resizer.after() for parameter descriptions.

before(x, axes, axes_div_by)[source]

Pad input image.

See csbdeep.predict.Resizer.before() for parameter descriptions.