micro_dl.inference module

Submodules

micro_dl.inference.evaluation_metrics module

Metrics for model evaluation

class micro_dl.inference.evaluation_metrics.MetricsEstimator(metrics_list, masked_metrics=False)

Bases: object

Estimate metrics for evaluating a trained model

static assert_input(target, prediction, pred_name, mask=None)
compute_metrics_row(target, prediction, pred_name, mask)

Compute one row in metrics dataframe.

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_name (str) – filename used for saving model prediction

  • mask (np.array) – binary mask with foreground / background

Returns:

dict metrics_row: a row for a metrics dataframe

estimate_xy_metrics(target, prediction, pred_name, mask=None)

Estimate metrics for the current input, target pair along each xy slice (in plane)

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_name (str/list) – filename(s) used for saving model prediction

  • mask (np.array) – binary mask with foreground / background

estimate_xyz_metrics(target, prediction, pred_name, mask=None)

Estimate 3D metrics for the current input, target pair

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_name (str) – filename used for saving model prediction

  • mask (np.array) – binary mask with foreground / background

estimate_xz_metrics(target, prediction, pred_name, mask=None)

Estimate metrics for the current input, target pair along each xz slice

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_name (str) – filename used for saving model prediction

  • mask (np.array) – binary mask with foreground / background

estimate_yz_metrics(target, prediction, pred_name, mask=None)

Estimate metrics for the current input, target pair along each yz slice

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_name (str) – filename used for saving model prediction

  • mask (np.array) – binary mask with foreground / background

get_metrics_xy()

Return xy metrics

get_metrics_xyz()

Return 3D metrics

get_metrics_xz()

Return xz metrics

get_metrics_yz()

Return yz metrics

static mask_to_bool(mask)

If mask exists and is not boolean, convert. Assume mask values == 0 is background

Parameters:

mask (np.array) – Mask

Return np.array mask:

Mask with boolean dtype

micro_dl.inference.evaluation_metrics.accuracy_metric(target, prediction)

Accuracy of binary target and prediction. Not using mask decorator for binary data evaluation.

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

Return float Accuracy:

Accuracy for binarized data

micro_dl.inference.evaluation_metrics.binarize_array(im)

Binarize image

Parameters:

im (np.array) – Prediction or target array

Return np.array im_bin:

Flattened and binarized array

micro_dl.inference.evaluation_metrics.corr_metric(target, prediction)

Pearson correlation of target and prediction

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

:return float Pearson correlation

micro_dl.inference.evaluation_metrics.dice_metric(target, prediction)

Dice similarity coefficient (F1 score) of binary target and prediction. Reports global metric. Not using mask decorator for binary data evaluation.

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

Return float dice:

Dice for binarized data

micro_dl.inference.evaluation_metrics.mae_metric(target, prediction)

MAE of target and prediction

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

:return float mean absolute error

micro_dl.inference.evaluation_metrics.mask_decorator(metric_function)

Decorator for masking the metrics

Parameters:

metric_function (function) – a python function that takes target and prediction arrays as input

Return function wrapper_metric_function:

input function that returns metrics and masked_metrics if mask was passed as param to input function

micro_dl.inference.evaluation_metrics.mse_metric(target, prediction)

MSE of target and prediction

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

:return float mean squared error

micro_dl.inference.evaluation_metrics.r2_metric(target, prediction)

Coefficient of determination of target and prediction

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

:return float coefficient of determination

micro_dl.inference.evaluation_metrics.ssim_metric(target, prediction, mask=None, win_size=21)

Structural similarity indiex (SSIM) of target and prediction. Window size is not passed into function so make sure tiles are never smaller than default win_size.

Parameters:

  • target (np.array) – ground truth array

  • prediction (np.array) – model prediction

  • mask (np.array/None) – Mask

  • win_size (int) – window size for computing local SSIM

:return float/list ssim and ssim_masked

micro_dl.inference.image_inference module

Model inference at the image/volume level

class micro_dl.inference.image_inference.ImagePredictor(train_config, inference_config, preprocess_config=None, gpu_id=-1, gpu_mem_frac=None)

Bases: object

Inference on larger images. Methods in this class provide functionality for performing inference on large (x,y > 256,256) images through direct inference in 2 and 3 dimensions, or by tiling in 2 or 3 dimensions along xy and z axes.

Inference is performed by first initalizing an InferenceDataset object which loads samples and performs normalization according to the tile-specific normalization values acquired during preprocessing.

Actual inference is performed by a trained tensorflow ‘.hdf5’ model specified in config files, which is loaded and instantiated.

After inference is performed on samples acquired from InferenceDataset object, dynamic range is return by denormalizing the outputs if the model task is reg- ression.

Metrics are calculated by use of a MetricEstimator object, which calculates, and indexes metrics for successive images.

estimate_metrics(target, prediction, pred_fnames, mask)

Estimate evaluation metrics The row of metrics gets added to metrics_est.df_metrics, and stored in class instance of MetricsEstimator.

Parameters:

  • target (np.array) – ground truth

  • prediction (np.array) – model prediction

  • pred_fnames (list) – File names (str) for saving model predictions

  • mask (np.array) – foreground/ background mask

get_mask(cur_row, transpose=False)

Get mask, read either from image or mask dir.

Parameters:

  • cur_row (pd.Series/dict) – row containing indices

  • transpose (bool) – Changes image format from xyz to zxy

Return np.array mask:

Mask

predict_2d(chan_slice_meta)

Run prediction on 2D or 2.5D on indices given by metadata row.

Reads in images from the inference dataset object, which performs normalization on the images based on values calculated in preprocessing and stored in frames_mets.csv.

Prediction is done over an entire image or over each tile and stitched together, as specified by data/model structure.

For regression models, post-processes images by reversing the z-score normalization to reintroduce dynamic range removed in normalization.

Parameters:

chan_slice_meta (pd.DataFrame) – Inference meta rows

Return np.array pred_stack:

Prediction

Return np.array target_stack:

Target

Return np.array/list mask_stack:

Mask for metrics (empty list if not using masked metrics)

predict_3d(iteration_rows)

Run prediction in 3D on images with 3D shape.

Reads in images from the inference dataset object, which performs normalization on the images based on values calculated in preprocessing and stored in frames_mets.csv.

Prediction in 3d is done over block-by-block, as specified in object instantiation, and prediction sub-blocks are stitched together.

For regression models, post-processes images by reversing the z-score normalization to reintroduce dynamic range removed in normalization.

Parameters:

iteration_rows (list) – Inference meta rows

Return np.array pred_stack:

Prediction

Return np.array/list mask_stack:

Mask for metrics

run_prediction()

Run prediction for entire set of 2D images or a 3D image stacks

Prediction procedure depends on format of input and desired prediction (2D or 3D). Generates metrics, if specified in parent object initiation, for each prediction channel, channel-wise.

Saves image predictions by individual channel and prediction metrics in separate files. z*** position specified in saved prediction name represents prediction channel.

save_pred_image(im_input, im_target, im_pred, metric, meta_row, pred_chan_name=nan)

Save predicted images with image extension given in init.

Note: images and predictions stored as float values are compressed into uint16 before figure generation. Some loss of information may occur during compression for extremely low-abs-value images and predictions.

Parameters:

  • im_input (np.array) – Input image

  • im_target (np.array) – Target image

  • im_pred (np.array) – 2D / 3D predicted image

  • metric (pd.series) – xy similarity metrics between prediction and target

  • meta_row (pd.DataFrame) – Row of meta dataframe containing sample

  • pred_chan_name (str/NaN) – Predicted channel name

unzscore(im_pred, im_target, meta_row)

Revert z-score normalization applied during preprocessing. Necessary before computing SSIM. Values for normalization may be tile-specific. Values are stored in the metadata produced by preprocessing (in the tile directory).

Used for models tasked with regression to reintroduce dynamic range into the model predictions.

Parameters:

  • im_pred – Prediction image, normalized image for un-zscore

  • im_target – Target image to compute stats from

  • meta_row (pd.DataFrame) – Metadata row for image

Return im_pred:

image at its original scale

micro_dl.inference.model_inference module

Model inference related functions

micro_dl.inference.model_inference.load_model(network_config, model_fname, predict=False)

Load the model from model_dir

Due to the lambda layer only model weights are saved and not the model config. Hence load_model wouldn’t work here! :param yaml network_config: a yaml file with all the required parameters :param str model_fname: fname with full path of the .hdf5 file with saved

weights

Parameters:

predict (bool) – load model for predicting / training. predict skips checks on input shape

Returns:

Keras.Model instance

micro_dl.inference.model_inference.predict_large_image(model, input_image)

Predict on an image larger than the one it was trained on

All networks with U-net like architecture in this repo, use downsampling of 2, which is only conducive for images with shapes in powers of 2. If different, please crop / resize accordingly to avoid shape mismatches.

Parameters:

  • model (keras.Model) – Model instance

  • input_image (np.array) – as named. expected shape: [num_channels, (depth,) height, width] or [(depth,) height, width, num_channels]

Return np.array predicted image:

as named. Batch axis removed (and channel axis if num_channels=1)

micro_dl.inference.stitch_predictions module

Stich model predictions either along Z or as tiles

class micro_dl.inference.stitch_predictions.ImageStitcher(tile_option, overlap_dict, image_format='zyx', data_format='channels_first')

Bases: object

Stitch prediction images for large images

stitch_predictions(im_shape, tile_imgs_list, block_indices_list)

Stitch the predicted tiles /blocks for a 3d image

Parameters:

  • im_shape (list) – shape of stitched pred image

  • tile_imgs_list (list) – list of prediction images

  • block_indices_list (list) – list of tuple/lists with indices for each prediction. Individual list of: len=2 when tile_z (start_slice, end_slice), len=6 for tile_xyz with start and end indices for each dimension

Return np.array stitched_img:

tile_imgs_list stitched into a 3D image

Module contents

Module for inference related classes and functions