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 (seecsbdeep.models.IsotropicCARE
).- Parameters
config (
csbdeep.models.Config
or None) – Valid configuration of CARE network (seeConfig.is_valid()
). Will be saved to disk as JSON (config.json
). If set toNone
, 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.
- keras_model
Keras neural network model.
- Type
- name
Model name.
- Type
- logdir
Path to model folder (which stores configuration, weights, etc.)
- Type
- 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 imageaxes (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
- 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
- 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-pixelmean
of Laplace distributions for probabilistic model.scale (
numpy.ndarray
or None) – Per-pixelscale
of Laplace distributions for probabilistic model (None
otherwise.)axes (str) – Axes of
mean
andscale
- Returns
Adjusted restored image(s).
- Return type
- abstract before(x, axes)[source]¶
Normalization of the raw input image (method stub).
- Parameters
x (
numpy.ndarray
) – Raw input image.axes (str) – Axes of input image x
- Returns
Normalized input image with suitable values for neural network input.
- Return type
- 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 toFalse
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
- 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
x (
numpy.ndarray
) – Restored image.axes (str) – Axes of restored image x
- Returns
Resized restored image.
- Return type
- 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
- 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
mode (str) – Parameter
mode
ofnumpy.pad()
that controls how the image is padded.kwargs (dict) – Keyword arguments for
numpy.pad()
.