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

Configuration of CARE network, as provided during instantiation.

Type

csbdeep.models.Config

keras_model

Keras neural network model.

Type

Keras model

name

Model name.

Type

str

logdir

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

Type

pathlib.Path

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.

abstract 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

abstract 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

abstract property do_after

Flag to indicate whether after() should be called.

Type

bool

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).

property 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.

abstract after(x, axes)[source]

Resizing of the restored image (method stub).

Parameters
Returns

Resized restored image.

Return type

numpy.ndarray

abstract 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.