Sub Packages

unagi.utils

Unagi has one sub package called utils which contains several methods and classes that are used to train the model.

unagi.utils.augmentor_utils

Different augmentation objects are created to use during the training.

class unagi.utils.augmentor_utils.GaussianNoiseAugmentor(probability: float, mean: float, sigma: float)

Bases: Augmentor.Operations.Operation

Gaussian Noise in Augmentor format.

Parameters:

• probability (float) – probability of operation being performed
• mean (float) – mean of the pixels
• sigma (float) – standard deviation of the pixels

perform_operation(images: List[numpy.ndarray]) → List[numpy.ndarray]

Apply operation to a batch of images.

Parameters:image (List[numpy.ndarray]) – list images to perform opetation Returns:list of image arrays after operation is performed Return type:List[numpy.ndarray]

class unagi.utils.augmentor_utils.InvertPartAugmentor(probability)

Bases: Augmentor.Operations.Operation

Invert colors in Augmentor formant.

perform_operation(images: List[numpy.ndarray]) → List[numpy.ndarray]

Apply invert operation to a batch of images.

Parameters:image (List[numpy.ndarray]) – list of images to perform opetation Returns:list of image arrays after operation is performed Return type:List[numpy.ndarray]

class unagi.utils.augmentor_utils.SaltPepperNoiseAugmentor(probability: float, prop: float)

Bases: Augmentor.Operations.Operation

Salt Pepper Noise in Augmentor format.

Parameters:

• probability (float) – probability of operation being performed
• prop (float) – image proportion value to keep

perform_operation(images: List[numpy.ndarray]) → List[numpy.ndarray]

Apply operation to a batch of images.

Parameters:image (List[numpy.ndarray]) – list of images to perform opetation Returns:list of image arrays after operation is performed Return type:List[numpy.ndarray]

unagi.utils.callback_utils

Callbacks for visulations of the training and saving the model are created using callback_utils module.

class unagi.utils.callback_utils.Visualisation(batchsize: int, dir_name: str = 'vis', monitor: str = 'val_loss', save_best_epochs_only: bool = False, mode: str = 'min')

Bases: tensorflow.python.keras.callbacks.Callback

Custom Keras callback for visualizing training through GIFs.

Parameters:

• batchsize (int) – batchsize to generate samples
• dir_name (str, optional) – folder with images to visualize training
• monitor (str, optional) – metric to monitor
• save_best_epochs_only (bool, optional) – save the weights only when the metric improves
• mode (str, optional) – mode for the metric to monitor

on_epoch_end(epoch: int, logs: Dict[str, Any])

Saves prediction of image after epoch into a folder with the same name.

Parameters:

• epoch (int) – current epoch number
• logs (Dict[str, Any]) – dictionary of metrics

on_train_end(logs=None)

Saves metrics for each iteration to a dictionary and saves images as gifs.

unagi.utils.callback_utils.create_callbacks(model: tensorflow.python.keras.engine.training.Model, original_model: tensorflow.python.keras.engine.training.Model, debug: str, num_gpus: int, batchsize: int, vis: str, weights_path: str) → List[str]

Create Keras callbacks for training.

Parameters:

• model (keras_model) – keras model
• original_model (keras_model) – model to use when num_gpus > 1
• debug (str) – path to save weights and tensorboard logs
• num_gpus (int) – number of gpus
• batchsize (int) – batchsize to use during training visualization
• vis (str) – images to read for training visualization
• weights_path (str) – path to save final weights

Returns:

list of callbacks tu use in training.

Return type:

List[str]

See also

Visualisation()

Example

unagi.utils.callbacks_utils.create_callbacks(

model, gpu_model, logs, 1, 32, vis_imgs, weights )

unagi.utils.img_processing_utils

Different image manipulation techniques are used in UNAGI. Dataset module uses different methods to create the images parts and preprocess the images during training.

unagi.utils.img_processing_utils.add_border(img: numpy.ndarray, size_x: int = 128, size_y: int = 128) → Tuple[numpy.ndarray, int, int]

Add border to image based on the inputs

Parameters:

• img (numpy.ndarray) – image array to add border
• size_x (int) – width for image part (deafult is 128).
• size_y (int) – height for image part (deafult is 128).

Returns:

image array with border border value added on width border value added on height

Return type:

Tuple[np.ndarray, int, int]

Example

unagi.utils.img_processing_utils.add_border(img_array, 128, 128)

unagi.utils.img_processing_utils.binarize_img(img: numpy.ndarray, model: tensorflow.python.keras.engine.training.Model, batchsize: int = 2) → numpy.ndarray

Binarize image, using U-net, Otsu, bottom-hat transform etc.

Parameters:

• img (numpy.ndarray) – image array to preprocess
• model (keras_model) – keras model
• batchsize (int, optional) – batchsize to use with the model (default is 2)

Returns:

image array after binarizing

Return type:

numpy.ndarray

See also

process_with_unagi(), postprocess_img()

Example

unagi.utils.img_processing_utils.binarize_img(process_unet_img, model)

unagi.utils.img_processing_utils.combine_imgs(imgs: List[numpy.ndarray], max_y: int, max_x: int) → numpy.ndarray

Combine image parts to one big image.

Parameters:

• img (List[numpy.ndarray]) – list image arraies to combine
• max_y (int) – width for image part (deafult is 128).
• max_x (int) – height for image part (deafult is 128).

Returns:

numpy.ndarray of combined image

Return type:

numpy.ndarray

Note

Walk through list of images and create from them one big image with sizes max_x * max_y. If border_x and border_y are non-zero, they will be removed from created image. The list of images should contain data in the following order: from left to right, from top to bottom.

Example

unagi.utils.img_processing_utils.combine_imgs(img_array_list, 128, 128)

unagi.utils.img_processing_utils.mkdir_s(path: str) → None

Create directory in specified path, if not exists.

Parameters:path (str) – directory name to create Returns: Return type:None

Example

unagi.utils.img_processing_utils.mkdir_s(dir_name)

unagi.utils.img_processing_utils.normalize_gt(img: numpy.ndarray) → numpy.ndarray

Normalize the gt image to have all pixels in range 0 to 1.

Parameters:img (numpy.ndarray) – image array to normalize Returns:normalized image array Return type:numpy.ndarray

Example

unagi.utils.img_processing_utils.normalize_gt(img_array)

unagi.utils.img_processing_utils.normalize_in(img: numpy.ndarray) → numpy.ndarray

Normalize the input image to have all pixels in range 0 to 1.

Parameters:img (numpy.ndarray) – image array to normalize Returns:normalized image array Return type:numpy.ndarray

Example

unagi.utils.img_processing_utils.normalize_in(img_array)

unagi.utils.img_processing_utils.postprocess_img(img: numpy.ndarray) → numpy.ndarray

Apply Otsu threshold to image.

Parameters:img (numpy.ndarray) – image array to postprocess Returns:postprocessed image array Return type:numpy.ndarray

Example

unagi.utils.img_processing_utils.postprocess_img(img_array)

unagi.utils.img_processing_utils.process_with_unagi(img: numpy.ndarray, model: tensorflow.python.keras.engine.training.Model, batchsize: int) → numpy.ndarray

Split image to 128x128 parts and run U-net for every part.

Parameters:

• img (numpy.ndarray) – image array to preprocess
• model (keras_model) – keras model
• batchsize (int) – batchsize to use with the model

Returns:

image array after preprocessing

Return type:

numpy.ndarray

See also

add_border(), normalize_in(), split_img(), combine_imgs()

Example

unagi.utils.img_processing_utils.process_with_unagi(process_unet_img, model)

unagi.utils.img_processing_utils.split_img(img: numpy.ndarray, size_x: int = 128, size_y: int = 128) → List[numpy.ndarray]

Split image to parts (little images).

Parameters:

• img (numpy.ndarray) – image array to split
• size_x (int) – width for image part (deafult is 128).
• size_y (int) – height for image part (deafult is 128).

Returns:

list of numpy.ndarray of image parts

Return type:

List[numpy.ndarray]

Note

Walk through the whole image by the window of size size_x * size_y without overlays and save all parts in list. Images sizes should divide window sizes.

Example

unagi.utils.img_processing_utils.split_img(img_array, 128, 128)

unagi.utils.metric_utils

UNAGI uses different loss functions and metrics to measure the performace of the model training.

unagi.utils.metric_utils.dice_coef(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Count Sorensen-Dice coefficient for output and ground-truth image.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel values

Returns:

dice coefficient calculated on predicted and input class values.

Return type:

float

Example

unagi.utils.metric_utils.dice_coef(y_true, y_pred)

unagi.utils.metric_utils.dice_coef_loss(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Loss of Sorensen-Dice coefficient for output and ground-truth image.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel values

Returns:

dice loss calculated from dice coefficient.

Return type:

float

See also

dice_coef()

Example

unagi.utils.metric_utils.dice_coef_loss(y_true, y_pred)

unagi.utils.metric_utils.focal_loss(alpha: float = 0.25, gamma: float = 2.0) → Callable[[Any, Any], float]

Calculates focal loss on predicted pixels.

Parameters:

• alpha (float) – tensor of true pixel values
• gamma (float) – tensor of predicted pixel valuesass

Returns:

focal loss value calculated predicted pixels.

Return type:

Callable[[Any, Any], float]

References

[1] keras implementation : https://lars76.github.io/neural-networks/object-detection/losses-for-segmentation/

[2] oiginal paper : Focal Loss for Dense Object Detection https://arxiv.org/abs/1708.02002

Example

unagi.utils.metric_utils.focal_loss()

unagi.utils.metric_utils.focal_tversky(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Calculates focal-tversky loss based on tversky index for predicted pixels.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel valuesass

Returns:

focal-tversky loss value calculated on tversky index for predicted pixels.

Return type:

float

References

[1] keras implementation : https://github.com/nabsabraham/focal-tversky-unet

[2] oiginal paper : A Novel Focal Tversky loss function with improved Attention U-Net for lesion segmentation. https://arxiv.org/abs/1810.07842

Example

unagi.utils.metric_utils.focal_tversky(y_true, y_pred)

unagi.utils.metric_utils.jacard_coef(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Count Jaccard coefficient for output and ground-truth image.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel values

Returns:

Jaccard coefficient calculated on predicted and input class values.

Return type:

float

Example

unagi.utils.metric_utils.jacard_coef(y_true, y_pred)

unagi.utils.metric_utils.jacard_coef_loss(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Calculates loss based on Jaccard coefficient for output and ground-truth image.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel values

Returns:

Jaccard loss calculated from Jaccard coefficient.

Return type:

float

See also

jacard_coef()

Example

unagi.utils.metric_utils.jacard_coef_loss(y_true, y_pred)

unagi.utils.metric_utils.tversky(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Calculates tversky index based on predicted pixels.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel valuesass

Returns:

tversky index value calculated on predicted pixels.

Return type:

float

Example

unagi.utils.metric_utils.tversky(y_true, y_pred)

unagi.utils.metric_utils.tversky_loss(y_true: tensorflow.python.framework.ops.Tensor, y_pred: tensorflow.python.framework.ops.Tensor) → float

Calculates tversky loss based on tversky index for predicted pixels.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel valuesass

Returns:

tversky loss value calculated on tversky index for predicted pixels.

Return type:

float

Example

unagi.utils.metric_utils.tversky_loss(y_true, y_pred)

unagi.utils.metric_utils.weighted_cross_entropy(pos_weight: float = 0.2) → Callable[[Any, Any], float]

Calculates weighted cross entropy loss on predicted pixels.

Parameters:

• y_true (tf.Tensor) – tensor of true pixel values
• y_pred (tf.Tensor) – tensor of predicted pixel valuesass

Returns:

loss value calculated based on the weight factor

Return type:

Callable[[Any, Any], float]

References

[1] keras implementation : https://lars76.github.io/neural-networks/object-detection/losses-for-segmentation/

Example

unagi.utils.metric_utils.weighted_cross_entropy(y_true, y_pred)

unagi.utils.model_utils

Contains the methods used to create the U-net architechture used in the model training such as DoubelConv layer, upsampling, and downsampling paths.

unagi.utils.model_utils.double_conv_layer(inputs: tensorflow.python.framework.ops.Tensor, kernel_size: int) → tensorflow.python.framework.ops.Tensor

Create a double convolution layer with mentioned inputs and filters.

Parameters:

• inputs (tf_tensor) – input keras layer
• kernel_size (int) – filter size/ kernel size for the tf_tensor

Returns:

tensor with mentioned number of filters

Return type:

tf_tensor

Example

unagi.utils.model_utils.double_conv_layer(Input, 32)

unagi.utils.model_utils.down_layer(inputs: tensorflow.python.framework.ops.Tensor, kernel_size: int) → tensorflow.python.framework.ops.Tensor

Create downsampling layer.

Parameters:

• inputs (tf_tensor) – input keras layer
• kernel_size (int) – filter size/ kernel size for the tf_tensor

Returns:

tensor with mentioned number of filters

Return type:

tf_tensor

See also

double_conv_layer()

Example

unagi.utils.model_utils.down_layer(tf_tensor, 64)

unagi.utils.model_utils.unet(width: int = 128, height: int = 128, channels: int = 1) → tensorflow.python.keras.engine.training.Model

Create U-net for input image/tensor size.

Parameters:

• width (int) – width of input tensor, (default is 128)
• height (int) – height of input tensor, (default is 128)
• channels (int) – number of channels in image, (default is 1)

Returns:

keras Model with mentioned number of filters and layers

Return type:

Model

See also

double_conv_layer(), down_layer(), up_layer()

Example

unagi.utils.model_utils.unet()

unagi.utils.model_utils.up_layer(inputs: tensorflow.python.framework.ops.Tensor, concats: tensorflow.python.framework.ops.Tensor, kernel_size: int) → tensorflow.python.framework.ops.Tensor

Create upsampling layer.

Parameters:

• inputs (tf_tensor) – input keras layer
• concats (tf_tensor) – keras layer to concat
• kernel_size (int) – filter size/ kernel size for the tf_tensor

Returns:

tensor with mentioned number of filters

Return type:

tf_tensor

See also

double_conv_layer()

Example

unagi.utils.model_utils.up_layer(input, pool_layer, 128)