MRIsegm

MRIsegm provides a series of modules. Each module contains a series of functions for different purposes. The modules are the following, each of them provides a different kind of functions.

MRIsegm.datagenerators

This module contains the implementation of DataGenerators.

class MRIsegm.datagenerators.DataGenerator(batch_size, source_path, label_path, aug=False, seed=123, validation_split=0.0, subset='training')

Bases: object

crop(img, lbl)

crop input and labels images

Parameters

• img (image) – input image

• lbl (image) – label image

Returns

cropped input and label image

Return type

tuple

denoise(img)

Denoise the image using non-local means algorithm

Parameters

img (image) – image to be denoised

Returns

smoothed denoised image

Return type

image

gamma_correction(img, gamma=1.0)

Perform gamma correction. The true value of gamma used in the formula is 1/gamma.

Parameters

• img (image) – image to be filtered

• gamma (float, optional) – gamma value, by default 1.0

Returns

gamma corrected image

Return type

image

property num_data

check the number of files for the relative subset

Returns

number of files (images)

Return type

int

random_hflip(img, lbl)

random horizontal flip input and label images

Parameters

• img (image) – input image

• lbl (image) – label image

Returns

randomly horizontal flipped input and label image

Return type

tuple

random_vflip(img, lbl)

random vertical flip input and label images

Parameters

• img (image) – input image

• lbl (image) – label image

Returns

randomly vertical flipped input and label image

Return type

tuple

randomize(source, label)

Shuffle data

Parameters

• source (array) – files paths

• label (array) – labels paths

Returns

randomized source and label paths

Return type

tuple

rescale(img)

Normalize and rescale image to binary floating 32-bit

Parameters

img (image) – image to be normalized and rescaled

Returns

normalaized and rescaled image

Return type

image

resize(img, lbl)

resize input and labels images

Parameters

• img (image) – input image

• lbl (image) – label image

Returns

resized input and label image

Return type

tuple

MRIsegm.datagenerators.create_segmentation_generator(img_path, mask_path, BATCH_SIZE, IMG_SIZE, SEED, data_gen_args_img, data_gen_args_mask)

Create DataGenerator yielding tuples of (x, y) with shape (batch_size, height, width, channels) where x is the input image and y is the ground-truth. The data generation is performed using data_gen_args_img and data_gen_args_mask.

Parameters

• img_path (str) – path for the images directory.

• mask_path (str) – path for the ground-truth directory.

• BATCH_SIZE (int) – size of the batches of data.

• IMG_SIZE (tuple) – (image height, image width).

• SEED (int) – seed for randomness control.

• data_gen_args_img (dict) – dict of keras ImageDataGenerator args for the generation of custom images.

• data_gen_args_mask (dict) – dict of keras ImageDataGenerator args for the generation of custom masks.

Returns

tuples of (x, y) with shape (batch_size, height, width, channels) where x is the input image and y is the ground-truth.

Return type

zip object

MRIsegm.graphics

This module contains methods to display the predictions.

MRIsegm.graphics.display(display_list, colormap=False, cmap='gist_heat', norm=True)

Display a list of images: ‘Input image’, ‘Ground-truth’, ‘Predicted’. It is possible to show the predicted image using a matplotlib cmap setting colormap as True.

Parameters

• display_list (list) – list of input images: ground-truth and predicted image.

• colormap (bool, optional) – if True show the predicted image using a sequential colormap (i.e. matplotlib ‘gist_heat’), by default False.

• cmap (str) – matplotlib cmap, by default ‘gist_heat’.

• norm (bool, optional) – if normalized the predicted image values are in the range [0.-1.], by deafult True.

MRIsegm.graphics.display_overlap(display_list, keys, colormap=True, cmap='gist_heat', figsize=(25, 15))

Display the ground-truth image and the predicted images from a list using a matplotlib colormap (setting colormap as True), over the original images.

Parameters

• display_list (list) – list of input images: ground-truth and predicted mask.

• keys (list) – list of models’ name used for generating the prediction.

• colormap (bool, optional) – if True the predicted mask is shown using a sequential colormap (i.e. matplotlib ‘gist_heat’), by default True.

• cmap (str, optional) – matplotlib cmap, by default ‘gist_heat’.

• figsize (tuple, optional) – figure size, by default (25, 15).

MRIsegm.graphics.display_predictions(display_list, keys, colormap=True, cmap='gist_heat', figsize=(25, 15))

Display the ground-truth image and the predicted images from a list using a matplotlib colormap (setting colormap as True).

Parameters

• display_list (list) – list of input images: ground-truth and predicted mask.

• keys (list) – list of models’ name used for generating the prediction.

• colormap (bool, optional) – if True the prediction is shown using a sequential colormap (i.e. matplotlib ‘gist_heat’), by default True.

• cmap (str, optional) – matplotlib cmap, by default ‘gist_heat’.

• figsize (tuple, optional) – figure size, by default (25, 15).

MRIsegm.graphics.plot_history(model_name, history, metrics, loss, save=True, custom_metrics=True, custom_loss=False, **kwargs)

Show the model history such as metrics and loss for both training and validation using ‘seaborn’ style.

Parameters

• model_name (str) – name of the model. It is the suptitle of the plot.

• history (Keras History object) – result of model.fit(). It is a record of training loss values and metrics values at successive epochs, as well as validation loss values and validation metrics values.

• metrics (list) – List of metrics to be evaluated by the model during training and testing. Each of this must be a string (name of a built-in function) or custom function (see ‘MRIsegm.metrics’).

• loss (string or a function) – string of name of a built-in function (i.e. ‘binary_crossentropy’ from tf.keras.metrics) or a custom function (see ‘MRIsegm.losses’).

• save (bool, optional) – if saving the plot to the given path which must be given as path=’path/to/plot’, by default True.

• custom_metrics (bool, optional) – if ‘True’ consider metrics as a custom function (see ‘MRIsegm.metrics’), by default True.

• custom_loss (bool, optional) – if ‘True’ consider loss as a custom function (see ‘MRIsegm.losses’), by default False.

MRIsegm.graphics.show_dataset(datagen, num=1)

Show a given number ‘num’ of tuples of images created using datagenerator (i.e. create_segmentation_generator). The first one is the input image, the second ine is the relative ground-truth.

Parameters

• datagen (iterator) – DirectoryIterator yielding tuples of (x, y) images with shape (batch_size, height, width, channels) where x is the input image and y is the relative ground-truth image.

• num (int, optional) – number of (x, y) tuples to be shown, by default 1.

MRIsegm.graphics.show_multiple_overlap(datagen, keys, values, num=1, colormap=True, cmap='gray', figsize=(25, 15))

Show a given number ‘num’ of predicted images by the given models from datagenerator, over the original images. The first one is the ground-truth. Each predicted image is shown using a matplotlib sequential colormap(setting colormap as ‘True’).

Parameters

• datagen (iterator) – DirectoryIterator yielding tuples of (x, y) with shape (batch_size, height, width, channels) where x is the input image and y is the ground-truth.

• keys (list) – list of models’ name used for generating the prediction.

• values (list) – list of loaded models used for generating the predictions.

• num (int, optional) – number of series to be shown, by default 1.

• colormap (bool, optional) – if True the prediction is shown using a sequential colormap, by default True.

• cmap (str, optional) – matplotlib cmap, by default ‘gray’.

• figsize (tuple, optional) – figure size, by default (25, 15).

MRIsegm.graphics.show_multiple_predictions(datagen, keys, values, num=1, colormap=True, cmap='gist_heat', figsize=(25, 15))

Show a given number ‘num’ of predicted images by the given models from datagenerator. The first one is the ground-truth.Each predicted image is shown using a matplotlib sequential colormap.

Parameters

• datagen (iterator) – DirectoryIterator yielding tuples of (x, y) with shape (batch_size, height, width, channels) where x is the input image and y is the ground-truth.

• keys (list) – list of models’ name used for generating the predictions.

• values (list) – list of loaded models used for generating the predictions.

• num (int, optional) – number of series to be shown, by default 1.

• colormap (bool, optional) – if True the prediction is shown using a sequential colormap (i.e. matplotlib ‘gist_heat’), by default True.

• cmap (str, optional) – matplotlib cmap, by default ‘gist_heat’.

• figsize (tuple, optional) – figure size, by default (25, 15).

MRIsegm.graphics.show_prediction(datagen, model, num=1, colormap=True, cmap='gist_heat', norm=True)

Show a given number ‘num’ of a series of image from datagenerator. The first of the series is the input image, the second one is ground-truth and the last one is the predicted image by the given model. The predicted image is shown using a sequential colormap.

Parameters

• datagen (iterator) – DirectoryIterator yielding tuples of (x, y) with shape (batch_size, height, width, channels) where x is the input image and y is the ground-truth.

• model (Keras Model class) – model used to make the prediction.

• num (int, optional) – number of series to be shown, by default 1.

• colormap (bool, optional) – if True the prediction is shown using a sequential colormap (i.e. matplotlib ‘gist_heat’), by default True.

• cmap (str) – matplotlib cmap, by default ‘gist_heat’.

• norm (bool, optional) – if normalized the predicted values are in the range [0.-1], by deafult True.

MRIsegm.losses

This module contains useful losses for training the model.

MRIsegm.losses.DiceBCEloss(y_true, y_pred)

This loss combines Dice loss with the standard binary cross-entropy (BCE) loss that is generally the default for segmentation models. Combining the two methods allows for some diversity in the loss, while benefitting from the stability of BCE.

Parameters

• y_true (Tensor) – input tensor with shape [batch_size, d0, .. dN].

• y_pred (Tensor) – predicted tensor with same shape of y_true.

Returns

Dice binary cross-entropy loss. If reduction is NONE, this has shape [batch_size, d0, .. dN-1]; otherwise, it is scalar.

Return type

Weighted loss float Tensor

References

• Kaggle https://www.kaggle.com/bigironsphere/loss-function-library-keras-pytorch

MRIsegm.losses.dice_loss(y_true, y_pred)

Also know as dice distance, measures dissimilarity between sample sets, it is complementary to the dice coefficient and it is obtained by subtracting the dice coefficient from 1.

Parameters

• y_true (Tensor) – input tensor with shape [batch_size, d0, .. dN].

• y_pred (Tensor) – predicted tensor with same shape of y_true.

Returns

scalar dice loss tensor with shape=().

Return type

Weighted loss float Tensor

References

• Wiki https://en.wikipedia.org/wiki/Sørensen–Dice_coefficient

MRIsegm.losses.soft_dice_loss(y_true, y_pred)

Soft dice distance, measures dissimilarity between sample sets, it is complementary to the dice coefficient and it is obtained by subtracting the dice coefficient from 1. It is similar to dice loss but abs(X) + abs(Y) is obtained as y_true**2 + y_pred**2

Parameters

• y_true (Tensor) – input tensor with shape [batch_size, d0, .. dN].

• y_pred (Tensor) – predicted tensor with same shape of y_true.

Returns

scalar dice loss tensor with shape=().

Return type

Weighted loss float Tensor

References

• Wiki https://en.wikipedia.org/wiki/Sørensen–Dice_coefficient

MRIsegm.metrics

This module contains useful metrics for training the model.

MRIsegm.metrics.dice_coef(y_true, y_pred, smooth=1)

Dice coefficient, also know as Sørensen-Dice index, is used to gauge the similarity of two samples. Given 2 sets it is defined as twice the number of elements common to both sets divided by the sum of the number of elements in each set.

Parameters

• y_true (Tensor) – input tensor with shape: [batch_size, height, width, channels].

• y_pred (Tensor) – predicted tensor with shape: [batch_size, height, width, channels].

• smooth (int, float, optional) – value that will be added to the numerator and denominator to avoid 0 division, by default 1.

Returns

dice – dice coefficient. The index is a number between 0 and 1 , if 1 sets totally match.

Return type

float

References

• Wiki https://en.wikipedia.org/wiki/Sørensen–Dice_coefficient

MRIsegm.models

This module contains the implementation of a U-net model.

MRIsegm.models.unet(IMAGE_HEIGHT, IMAGE_WIDTH, n_levels=4, initial_features=64, n_conv=2, kernel_size=3, pooling_size=2, in_channels=1, out_channels=1, activation='sigmoid')

U-Net is a convolutional neural network that was developed for biomedical image segmentation.The network consists of a contracting path and an expansive path, which gives it the u-shaped architecture. The contracting path is a typical convolutional network that consists of repeated application of convolutions, each followed by a rectified linear unit (ReLU) and a max pooling operation. During the contraction, the spatial information is reduced while feature information is increased. The expansive pathway combines the feature and spatial information through a sequence of up-convolutions and concatenations with high-resolution features from the contracting path.

Parameters

• IMAGE_HEIGHT (int) – height of the images.

• IMAGE_WIDTH (int) – width of the images.

• n_levels (int, optional) – number of contracting levels, by default 4.

• initial_features (int, optional) – number of initial convolutional layers, by default 64.

• n_conv (int, optional) – number of performed convolutions, by default 2.

• kernel_size (int, optional) – size of the kernel, by default 3.

• pooling_size (int, optional) – size of pooling, by default 2.

• in_channels (int, optional) – number of input channels, by default 1.

• out_channels (int, optional) – number of output channels, by default 1.

• activation (str) – keras activation function name.

Returns

U-net model.

Return type

keras Model class object

References

• Wiki: https://en.wikipedia.org/wiki/U-Net

• U-Net architecture : ‘../extras/U-Net arch.jpeg’

• U-Net paper: https://arxiv.org/pdf/1505.04597.pdf

MRIsegm.processing

This module contains methods to perform operations such as denoising, resizing, gamma correction.

MRIsegm.processing.compare_denoised_histo(img, alpha, figsize=(15, 15))

Compare the histogram of the original and denoised image showing both the image and the relative histogram.

Parameters

• img (image, array_like) – image to be denoised.

• alpha (int, float) – smoothing parameters. A higher value of alpha results in a smoother image, at the expense of blurring features.

• figsize (tuple, optional) – figsize arg of matplotlib module, by default (15, 15).

MRIsegm.processing.contour_slices(slices, predicted_slices)

Draw the contours of the predicted mask over the original image for each slice of the stack.

Parameters

• slices (numpy array) – Numpy array of shape = (layers, height, width, 1).

• predicted_slices (numpy array) – array of shape = (layers, height, width, 1).

Returns

return an array of shape = (*slices.shape, 3).

Return type

array

MRIsegm.processing.crop_image(img)

Crop full image to center from 512x512 to 256 x 256

Parameters

img (array like) – image to be cropped

Returns

cropped image

Return type

array like image

MRIsegm.processing.crop_masks(slices)

Crop slices of masks

Parameters

slices (array of shape: (depth, hight, width)) – stack of masks to be cropped

Returns

array of shape – stack of cropped masks

Return type

(depth, hight, width)

MRIsegm.processing.denoise(img, alpha=10)

Denoise the image using non-local means algorithm

Parameters

• img (image, array like) – image to be denoised

• alpha (float, optional) – smoothing parameter, by default 10

Returns

smoothed denoised image

Return type

image, array like

MRIsegm.processing.denoise_nlm(img, alpha, show=False, **kwargs)

Denoise image using non-local mean filter.

Parameters

• img (image, array_like) – image to be denoised.

• alpha (int, float) – smoothing parameters. A higher value of alpha results in a smoother image, at the expense of blurring features.

• show (bool, optional) – if True show both the original image and the denoised one otherwise returns ‘denoised_img’, by default False.

Returns

denoised_img – return denoised input image.

Return type

image, array_like

MRIsegm.processing.denoise_slices(slices, alpha=1.15)

Denoise each layer of a the entire slices stack.

Parameters

• slices (array) – array of shape depth, height, width

• alpha (int, float) – smoothing parameters. A higher value of alpha results in a smoother image, at the expense of blurring features, by default 1.15 .

Returns

denoised_slices – array of shape depth, height, width.

Return type

array

MRIsegm.processing.gamma_correction(img, gamma=1.0)

Perform gamma correction. The true value of gamma used in the formula is 1/gamma.

Parameters

• img (image, array like) – image to be filtered

• gamma (float, optional) – gamma value, by default 1.0

Returns

gamma corrected image

Return type

image, array like

MRIsegm.processing.otsu_thresholding(img, **kwargs)

Perform Otsu thresholding on input image.

Parameters

img (image, array_like) – input image to be thresholded.

Returns

th – thresholded image using cv2.THRESH_BINARY_INV+cv2.THRESH_OTSU.

Return type

thresholded image

MRIsegm.processing.pre_processing_data(slices, alpha=10)

Single-shot preprocessind data function. Performing rescaling, denoising, gamma correction.

Parameters

• slices (array of shape: (depth, hight, width)) – stack of images to be preprocessed

• alpha (float, optional) – smoothing parameter, by default 10

Returns

array of shape – pre-processed slices

Return type

(depth, hight, width)

MRIsegm.processing.predict_images(slices, model, pre_processing=False, t=0.05)

Predict full stack of slices, slice by slice

Parameters

• slices (array of shape: (depth, hight, width)) – stack of images

• model (Tensorflow-Keras model instance) – loaded .h5 keras model by tf.keras.model.load_model()

• pre_processing (bool, optional) – if true pre-process the images, by default False

• t (float, optional) – threshold parameter. Values below this threshold value are set to 0, by default 0.1

Returns

array of shape – stack of predicted images, corresponding to the prediction for the original slices.

Return type

(depth, hight, width, 1)

MRIsegm.processing.predict_slices(slices, model, IMAGE_HEIGHT, IMAGE_WIDTH)

Create stack of predicted slice mask using the given model.

Parameters

• slices (numpy array) – Numpy array of shape = (layers, height, width, 1).

• model (Keras model instance) – loaded .h5 keras model by tf.keras.model.load_model() .

• IMAGE_HEIGHT (int) – image height.

• IMAGE_WIDTH (int) – image width.

Returns

array of shape = (layers, height, width, 1).

Return type

numpy array

MRIsegm.processing.rescale(img)

Normalize and rescale image to binary floating 32-bit

Parameters

img (image, array like) – image to be normalized and rescaled

Returns

[normalaized and rescaled image

Return type

image, array like

MRIsegm.processing.resize_slices(slices, IMAGE_HEIGHT, IMAGE_WIDTH, dtype=<class 'numpy.float32'>)

Resize slices to shape = (layers, height, width) to shape = (layers, height, width, 1).

Parameters

• slices (numpy array) – Numpy array of shape = (layers, height, width).

• IMAGE_HEIGHT (int) – image height.

• IMAGE_WIDTH (int) – image width.

• dtype (numpy dtype) – dtype of the resized slices, by default np.float32.

Returns

resized_slice – resized array of shape (layers, height, width, 1) where 1 denotes the number of channels.

Return type

numpy array

MRIsegm.processing.show_image_histogram(img, show_original=True)

Plot the histogram of the input image.

Parameters

• img (image, array_like) – image to calculate the histogram from.

• show_original (bool, optional) – if True show both the image and the histogram otherwise only the histogram, by default True.

MRIsegm.processing.show_slice_histogram(slices, layer, show_original=True)

Show the histogram of the given slices of the slices stack.

Parameters

• slices (array) – array of shape depth, height, width.

• layer (int) – value between (0, slices.shape[0]).

• show_original (bool, optional) – if True show both the image and the histogram otherwise only the histogram, by default True.

MRIsegm.processing.write_contour(slices, predicted_slices, layer)

Draw the contours of the predicted mask over the original image.

Parameters

• slices (numpy array) – Numpy array of shape (layers, height, width, 1).

• predicted_slices (numpy array) – array of shape = (layers, height, width, 1).

• layer (int) – value between (0, slices.shape[0]).

Returns

return a RGB image array.

Return type

array

MRIsegm.utils

This module contains methods to load and visualize the DICOM series.

MRIsegm.utils.display_image(img, figsize=(12, 7), **kwargs)

Display greyscale image

Parameters

• img (image, array_like) – image to be displayed

• figsize (tuple, optional) – figsize arg of matplotlib module, by default (12, 7)

MRIsegm.utils.display_images(display_list, figsize=(12, 8), **kwargs)

Display a list of greyscale images

Parameters

• display_list (list) – list of images to be displayed

• figsize (tuple, optional) – figsize arg of matplotlib module, by default (12, 8)

MRIsegm.utils.explore_roi(slices, layer, rois)

Show the regions of interest contours from a given slice

Parameters

• slices (array) – array of shape depth, height, width

• layer (int) – value between (0, slices.shape[0])

• rois (list) – roi list

MRIsegm.utils.explore_slices(slices, layer, **kwargs)

Show figure of the given slice

Parameters

• slices (array) – array of shape depth, height, width

• layer (int) – value between (0, slice.shape[0])

MRIsegm.utils.get_rois(roi_path)

Get ImageJ rois from .roi files stored in roi_path

Parameters

roi_path (str) – path of dir containing .roi files

Returns

roi – list of roi dicts orderd by position number and without “type”:composite

Return type

list

MRIsegm.utils.get_slices(dir_path, uint8=True)

Get full stack of slices from single dcm files ordered by “InstanceNumber” as a rescaled array of shape: depth, height, width

Parameters

• dir_path (str) – directory of dcm slices

• uint8 (bool) – rescale the image to uint8, by default True

Returns

slices – array of shape: depth, height, width , ordered by “InstanceNumber”

Return type

array

MRIsegm.utils.get_slices_info(slices)

Print depth, height, width of the input slices

Parameters

slices (array-like) –

MRIsegm.utils.make_mask(slices, layer, rois)

Generate mask of a given slice

Parameters

• slices (array) – array of shape depth, height, width

• layer (int) – value between (0, slices.shape[0])

• rois (list) – roi list

Returns

label – return mask of a given slice. Pixels outside regions of interest are set to 0 (black), pixel inside regions of interest are set to 255 (white)

Return type

array

Raises

ValueError – if there are no regions of interest: “no labels found!”

MRIsegm.utils.mask_slices(slices, rois)

Make an array of shape depth, height, width, containing for each layer the proper mask. If no mask if found then masked_slices[layer, :, :] = 0

Parameters

• slices (array) – array of shape depth, height, width

• rois (list) – roi list

Returns

masked_slices – array of shape: depth, height, width containing for each layer the proper mask

Return type

array

MRIsegm.utils.plot_random_layer(slices)

Show figure of the random slice between (0, slices.shape[0])

Parameters

slices (array) – array of shape depth, height, width

MRIsegm.utils.read_slices(filename)

Read dicom file as pixel array

Parameters

filename (str) – name of file.dcm

Returns

pix_arr – dcm file as array

Return type

array

Raises

ValueError – filename must be .dcm format

MRIsegm.utils.rescale(im, max_value, min_value)

Rescale image in range (0,255)

Parameters

• im (array like) – image to be rescaled

• max_value (value) – max image value

• min_value (value) – min image value

Returns

rescaled image – rescaled input image as type uint 8

Return type

array like