deepcell.utils

Deepcell Utilities Module

backbone_utils

Functions for creating model backbones

deepcell.utils.backbone_utils.featurenet_3D_backbone(input_tensor=None, input_shape=None, n_filters=32, **kwargs)[source]

Construct the deepcell backbone with five convolutional units

Parameters:

  • input_tensor (tensor) – Input tensor to specify input size

  • n_filters (int) – Number of filters for convolutional layers

Returns:

List of backbone layers, list of backbone names

Return type:

tuple

deepcell.utils.backbone_utils.featurenet_3D_block(x, n_filters)[source]

Add a set of layers that make up one unit of the featurenet 3D backbone

Parameters:

  • x (tensorflow.keras.Layer) – Keras layer object to pass to backbone unit

  • n_filters (int) – Number of filters to use for convolutional layers

Returns:

Keras layer object

Return type:

tensorflow.keras.Layer

deepcell.utils.backbone_utils.featurenet_backbone(input_tensor=None, input_shape=None, n_filters=32, **kwargs)[source]

Construct the deepcell backbone with five convolutional units

Parameters:

  • input_tensor (tensor) – Input tensor to specify input size

  • n_filters (int) – Number of filters for convolutional layers

Returns:

List of backbone layers, list of backbone names

Return type:

tuple

deepcell.utils.backbone_utils.featurenet_block(x, n_filters)[source]

Add a set of layers that make up one unit of the featurenet backbone

Parameters:

  • x (tensorflow.keras.Layer) – Keras layer object to pass to backbone unit

  • n_filters (int) – Number of filters to use for convolutional layers

Returns:

Keras layer object

Return type:

tensorflow.keras.Layer

deepcell.utils.backbone_utils.get_backbone(backbone, input_tensor=None, input_shape=None, use_imagenet=False, return_dict=True, frames_per_batch=1, **kwargs)[source]

Retrieve backbones for the construction of feature pyramid networks.

Parameters:

  • backbone (str) – Name of the backbone to be retrieved.

  • input_tensor (tensor) – The input tensor for the backbone. Should have channel dimension of size 3

  • use_imagenet (bool) – Load pre-trained weights for the backbone

  • return_dict (bool) – Whether to return a dictionary of backbone layers, e.g. {'C1': C1, 'C2': C2, 'C3': C3, 'C4': C4, 'C5': C5}. If false, the whole model is returned instead

  • kwargs (dict) – Keyword dictionary for backbone constructions. Relevant keys include 'include_top', 'weights' (should be None), 'input_shape', and 'pooling'.

Returns:

An instantiated backbone

Return type:

tensorflow.keras.Model

Raises:

data_utils

Functions for making training data

deepcell.utils.data_utils.get_data(file_name, mode='sample', test_size=0.2, seed=0)[source]

Load data from NPZ file and split into train and test sets

Parameters:

  • file_name (str) – path to NPZ file to load

  • mode (str) – if ‘siamese_daughters’, returns lineage information from .trk file otherwise, returns the same data that was loaded.

  • test_size (float) – percent of data to leave as testing holdout

  • seed (int) – seed number for random train/test split repeatability

Returns:

dict of training data, and a dict of testing data

Return type:

(dict, dict)

deepcell.utils.data_utils.get_max_sample_num_list(y, edge_feature, output_mode='sample', padding='valid', window_size_x=30, window_size_y=30)[source]

For each set of images and each feature, find the maximum number of samples for to be used. This will be used to balance class sampling.

Parameters:

  • y (numpy.array) – mask to indicate which pixels belong to which class

  • edge_feature (list) – [1, 0, 0], the 1 indicates the feature is the cell edge

  • output_mode (str) – ‘sample’ or ‘conv’

  • padding (str) – ‘valid’ or ‘same’

Returns:

list of maximum sample size for all classes

Return type:

list

deepcell.utils.data_utils.relabel_movie(y)[source]

Relabels unique instance IDs to be from 1 to N

Parameters:

y (numpy.array) – tensor of integer labels

Returns:

relabeled tensor with sequential labels

Return type:

numpy.array

deepcell.utils.data_utils.reshape_matrix(X, y, reshape_size=256)[source]

Reshape matrix of dimension 4 to have x and y of size reshape_size. Adds overlapping slices to batches. E.g. reshape_size of 256 yields (1, 1024, 1024, 1) -> (16, 256, 256, 1) The input image is divided into subimages of side length reshape_size, with the last row and column of subimages overlapping the one before the last if the original image side lengths are not divisible by reshape_size.

Parameters:

  • X (numpy.array) – raw 4D image tensor

  • y (numpy.array) – label mask of 4D image data

  • reshape_size (int, list) – size of the output tensor If input is int, output images are square with side length equal reshape_size. If it is a list of 2 ints, then the output images size is reshape_size[0] x reshape_size[1]

Returns:

reshaped X and y 4D tensors in shape[1:3] = (reshape_size, reshape_size), if reshape_size is an int, and shape[1:3] = reshape_size, if reshape_size is a list of length 2

Return type:

numpy.array

Raises:
deepcell.utils.data_utils.reshape_movie(X, y, reshape_size=256)[source]

Reshape tensor of dimension 5 to have x and y of size reshape_size. Adds overlapping slices to batches. E.g. reshape_size of 256 yields (1, 5, 1024, 1024, 1) -> (16, 5, 256, 256, 1)

Parameters:

  • X (numpy.array) – raw 5D image tensor

  • y (numpy.array) – label mask of 5D image tensor

  • reshape_size (int) – size of the square output tensor

Returns:

reshaped X and y tensors in shape (reshape_size, reshape_size)

Return type:

numpy.array

Raises:
deepcell.utils.data_utils.sample_label_matrix(y, window_size=(30, 30), padding='valid', max_training_examples=10000000.0, data_format=None)[source]

Sample a 4D Tensor, creating many small images of shape window_size.

Parameters:

  • y (numpy.array) – label masks with the same shape as X data

  • window_size (tuple) – size of window around each pixel to sample

  • padding (str) – padding type ‘valid’ or ‘same’

  • max_training_examples (int) – max number of samples per class

  • data_format (str) – ‘channels_first’ or ‘channels_last’

Returns:

4 arrays of coordinates of each sampled pixel

Return type:

tuple

deepcell.utils.data_utils.sample_label_movie(y, window_size=(30, 30, 5), padding='valid', max_training_examples=10000000.0, data_format=None)[source]

Sample a 5D Tensor, creating many small voxels of shape window_size.

Parameters:

  • y (numpy.array) – label masks with the same shape as X data

  • window_size (tuple) – size of window around each pixel to sample

  • padding (str) – padding type ‘valid’ or ‘same’

  • max_training_examples (int) – max number of samples per class

  • data_format (str) – ‘channels_first’ or ‘channels_last’

Returns:

5 arrays of coordinates of each sampled pixel

Return type:

tuple

deepcell.utils.data_utils.trim_padding(nparr, win_x, win_y, win_z=None)[source]

Trim the boundaries of the numpy array to allow for a sliding window of size (win_x, win_y) to not slide over regions without pixel data

Parameters:

  • nparr (numpy.array) – numpy array to trim

  • win_x (int) – number of row pixels to ignore on either side

  • win_y (int) – number of column pixels to ignore on either side

  • win_y – number of column pixels to ignore on either side

Returns:

trimmed numpy array of size x - 2 * win_x - 1, y - 2 * win_y - 1

Return type:

numpy.array

Raises:

ValueError – nparr.ndim is not 4 or 5

export_utils

Save Keras models as a SavedModel for TensorFlow Serving

deepcell.utils.export_utils.export_model(keras_model, export_path, model_version=0, weights_path=None, include_optimizer=True, overwrite=True, save_format='tf')[source]

Export a model for use with TensorFlow Serving.

DEPRECATED: tf.keras.models.save_model is preferred.

Parameters:

  • keras_model (tensorflow.keras.Model) – Instantiated Keras model.

  • export_path (str) – Destination to save the exported model files.

  • model_version (int) – Integer version of the model.

  • weights_path (str) – Path to a .h5 or .tf weights file.

  • include_optimizer (bool) – Whether to export the optimizer.

  • overwrite (bool) – Whether to overwrite any existing files in export_path.

  • save_format (str) – Saved model format, one of 'tf' or 'h5'.

deepcell.utils.export_utils.export_model_to_tflite(model_file, export_path, calibration_images, norm=True, location=True, file_name='model.tflite')[source]

Export a saved keras model to tensorflow-lite with int8 precision.

Deprecated since version 0.12.4: The export_model_to_tflite function is deprecated and will be removed in 0.13. Use tf.keras.models.save_model instead.

This export function has only been tested with PanopticNet models. For the export to be successful, the PanopticNet model must have norm_method set to None, location set to False, and the upsampling layers must use bilinear interpolation.

Parameters:

  • model_file (str) – Path to saved model file

  • export_path (str) – Directory to save the exported tflite model

  • calibration_images (numpy.array) – Array of images used for calibration during model quantization

  • norm (bool) – Whether to normalize calibration images.

  • location (bool) – Whether to append a location image to calibration images.

  • file_name (str) – File name for the exported model. Defaults to ‘model.tflite’

io_utils

Utilities for reading/writing files

deepcell.utils.io_utils.get_image(file_name)[source]

DEPRECATED. Use skimage.io.imread instead.

Read image from file and returns it as a tensor.

Parameters:

file_name (str) – path to image file

Returns:

numpy array of image data

Return type:

numpy.array

deepcell.utils.io_utils.save_model_output(output, output_dir, feature_name='', channel=None, data_format=None)[source]

Save model output as tiff images in the provided directory

Parameters:

  • output (numpy.array) – Output of a model. Expects channel to have its own axis.

  • output_dir (str) – Directory to save the model output images.

  • feature_name (str) – Optional description to start each output image filename.

  • channel (int) – If given, only saves this channel.

misc_utils

Miscellaneous utility functions

deepcell.utils.misc_utils.get_sorted_keys(dict_to_sort)[source]

Gets the keys from a dict and sorts them in ascending order. Assumes keys are of the form Ni, where N is a letter and i is an integer.

Parameters:

dict_to_sort (dict) – dict whose keys need sorting

Returns:

list of sorted keys from dict_to_sort

Return type:

list

deepcell.utils.misc_utils.sorted_nicely(ll)[source]

Sort a list of strings by the numerical order of all substrings

Parameters:

l (list) – List of strings to sort

Returns:

a sorted list

Return type:

list

plot_utils

Utilities plotting data

deepcell.utils.plot_utils.cf(x_coord, y_coord, sample_image)[source]

Format x and y coordinates for printing

Parameters:

  • x_coord (int) – X coordinate

  • y_coord (int) – y coordinate

  • sample_image (numpy.array) – Sample image for numpy arrays

Returns:

formatted coordinates (x, y, z).

Return type:

str

deepcell.utils.plot_utils.create_rgb_image(input_data, channel_colors)[source]

Takes a stack of 1- or 2-channel data and converts it to an RGB image

Parameters:

  • input_data – 4D stack of images to be converted to RGB

  • channel_colors – list specifying the color for each channel

Returns:

transformed version of input data into RGB version

Return type:

numpy.array

Raises:

  • ValueError – if len(channel_colors) is not equal to number of channels

  • ValueError – if invalid channel_colors provided

  • ValueError – if input_data is not 4D, with 1 or 2 channels

deepcell.utils.plot_utils.get_js_video(images, batch=0, channel=0, cmap='jet', vmin=0, vmax=0, interval=200, repeat_delay=1000)[source]

Create a JavaScript video as HTML for visualizing 3D data as a movie.

Parameters:

  • images (numpy.array) – images to display as video

  • batch (int) – batch number of images to plot

  • channel (int) – channel index to plot

  • vmin (int) – lower end of data range covered by colormap

  • vmax (int) – upper end of data range covered by colormap

Returns:

JS HTML to display video

Return type:

str

deepcell.utils.plot_utils.make_outline_overlay(rgb_data, predictions)[source]

Overlay a segmentation mask with image data for easy visualization

Parameters:

  • rgb_data – 3 channel array of images, output of create_rgb_data

  • predictions – segmentation predictions to be visualized

Returns:

overlay image of input data and predictions

Return type:

numpy.array

Raises:

  • ValueError – If predictions are not 4D

  • ValueError – If there is not matching RGB data for each prediction

deepcell.utils.plot_utils.plot_error(loss_hist_file, saved_direc, plot_name)[source]

Plot the training and validation error from the npz file

Parameters:

  • loss_hist_file (str) – full path to .npz loss history file

  • saved_direc (str) – full path to directory where the plot is saved

  • plot_name (str) – the name of plot

deepcell.utils.plot_utils.plot_training_data_2d(X, y, max_plotted=5)[source]
deepcell.utils.plot_utils.plot_training_data_3d(X, y, num_image_stacks, frames_to_display=5)[source]

Plot 3D training data

Parameters:

  • X (numpy.array) – Raw 3D data

  • y (numpy.array) – Labels for 3D data

  • num_image_stacks (int) – number of independent 3D examples to plot

  • frames_to_display (int) – number of frames of X and y to display

tracking_utils

Utilities for tracking cells

train_utils

Utilities for training neural nets

deepcell.utils.train_utils.count_gpus()[source]

Get the number of available GPUs.

Returns:

count of GPUs as integer

Return type:

int

deepcell.utils.train_utils.get_callbacks(model_path, save_weights_only=False, lr_sched=None, tensorboard_log_dir=None, reduce_lr_on_plateau=False, monitor='val_loss', verbose=1)[source]

Returns a list of callbacks used for training

Parameters:

  • model_path – (str) path for the h5 model file.

  • save_weights_only – (bool) if True, then only the model’s weights will be saved.

  • lr_sched (function) – learning rate scheduler per epoch. from rate_scheduler.

  • tensorboard_log_dir (str) – log directory for tensorboard.

  • monitor (str) – quantity to monitor.

  • verbose (int) – verbosity mode, 0 or 1.

Returns:

a list of callbacks to be passed to model.fit()

Return type:

list

deepcell.utils.train_utils.rate_scheduler(lr=0.001, decay=0.95)[source]

Schedule the learning rate based on the epoch.

Parameters:

  • lr (float) – initial learning rate

  • decay (float) – rate of decay of the learning rate

Returns:

A function that takes in the epoch and returns a learning rate.

Return type:

function

transform_utils

Utilities for data transformations

deepcell.utils.transform_utils.inner_distance_transform_2d(mask, bins=None, erosion_width=None, alpha=0.1, beta=1)[source]

Transform a label mask with an inner distance transform.

inner_distance = 1 / (1 + beta * alpha * distance_to_center)
Parameters:

  • mask (numpy.array) – A label mask (y data).

  • bins (int) – The number of transformed distance classes.

  • erosion_width (int) – number of pixels to erode edges of each labels

  • alpha (float, str) – coefficent to reduce the magnitude of the distance value. If “auto”, determines alpha for each cell based on the cell area.

  • beta (float) – scale parameter that is used when alpha is “auto”.

Returns:

a mask of same shape as input mask, with each label being a distance class from 1 to bins.

Return type:

numpy.array

Raises:

ValueError – alpha is a string but not set to “auto”.

deepcell.utils.transform_utils.inner_distance_transform_3d(mask, bins=None, erosion_width=None, alpha=0.1, beta=1, sampling=[0.5, 0.217, 0.217])[source]

Transform a label mask for a z-stack with an inner distance transform.

inner_distance = 1 / (1 + beta * alpha * distance_to_center)
Parameters:

  • mask (numpy.array) – A label mask (y data).

  • bins (int) – The number of transformed distance classes.

  • erosion_width (int) – Number of pixels to erode edges of each labels

  • alpha (float, str) – Coefficent to reduce the magnitude of the distance value. If 'auto', determines alpha for each cell based on the cell area.

  • beta (float) – Scale parameter that is used when alpha is “auto”.

  • sampling (list) – Spacing of pixels along each dimension.

Returns:

A mask of same shape as input mask, with each label being a distance class from 1 to bins.

Return type:

numpy.array

Raises:

ValueError – alpha is a string but not set to “auto”.

deepcell.utils.transform_utils.inner_distance_transform_movie(mask, bins=None, erosion_width=None, alpha=0.1, beta=1)[source]

Transform a label mask with an inner distance transform. Applies the 2D transform to each frame.

Parameters:

  • mask (numpy.array) – A label mask (y data).

  • bins (int) – The number of transformed distance classes.

  • erosion_width (int) – Number of pixels to erode edges of each labels.

  • alpha (float, str) – Coefficent to reduce the magnitude of the distance value. If “auto”, determines alpha for each cell based on the cell area.

  • beta (float) – Scale parameter that is used when alpha is “auto”.

Returns:

A mask of same shape as input mask, with each label being a distance class from 1 to bins.

Return type:

numpy.array

Raises:

ValueError – alpha is a string but not set to “auto”.

deepcell.utils.transform_utils.outer_distance_transform_2d(mask, bins=None, erosion_width=None, normalize=True)[source]

Transform a label mask with an outer distance transform.

Parameters:

  • mask (numpy.array) – A label mask (y data).

  • bins (int) – The number of transformed distance classes. If None, returns the continuous outer transform.

  • erosion_width (int) – Number of pixels to erode edges of each labels

  • normalize (bool) – Normalize the transform of each cell by that cell’s largest distance.

Returns:

A mask of same shape as input mask, with each label being a distance class from 1 to bins.

Return type:

numpy.array

deepcell.utils.transform_utils.outer_distance_transform_3d(mask, bins=None, erosion_width=None, normalize=True, sampling=[0.5, 0.217, 0.217])[source]

Transforms a label mask for a z stack with an outer distance transform. Uses scipy’s distance_transform_edt

Parameters:

  • mask (numpy.array) – A z-stack of label masks (y data).

  • bins (int) – The number of transformed distance classes.

  • erosion_width (int) – Number of pixels to erode edges of each labels.

  • normalize (bool) – Normalize the transform of each cell by that cell’s largest distance.

  • sampling (list) – Spacing of pixels along each dimension.

Returns:

3D Euclidiean Distance Transform

Return type:

numpy.array

deepcell.utils.transform_utils.outer_distance_transform_movie(mask, bins=None, erosion_width=None, normalize=True)[source]

Transform a label mask for a movie with an outer distance transform. Applies the 2D transform to each frame.

Parameters:

  • mask (numpy.array) – A label mask (y data).

  • bins (int) – The number of transformed distance classes.

  • erosion_width (int) – number of pixels to erode edges of each labels.

  • normalize (bool) – Normalize the transform of each cell by that cell’s largest distance.

Returns:

a mask of same shape as input mask, with each label being a distance class from 1 to bins

Return type:

numpy.array

deepcell.utils.transform_utils.pixelwise_transform(mask, dilation_radius=None, data_format=None, separate_edge_classes=False)[source]

Transforms a label mask for a z stack edge, interior, and background

Parameters:

  • mask (numpy.array) – tensor of labels

  • dilation_radius (int) – width to enlarge the edge feature of each instance

  • data_format (str) – A string, one of channels_last (default) or channels_first. The ordering of the dimensions in the inputs. channels_last corresponds to inputs with shape (batch, height, width, channels) while channels_first corresponds to inputs with shape (batch, channels, height, width).

  • separate_edge_classes (bool) – Whether to separate the cell edge class into 2 distinct cell-cell edge and cell-background edge classes.

Returns:

An array with the same shape as mask, except the channel axis will be a one-hot encoded semantic segmentation for 3 main features: [cell_edge, cell_interior, background]. If separate_edge_classes is True, the cell_interior feature is split into 2 features and the resulting channels are: [bg_cell_edge, cell_cell_edge, cell_interior, background].

Return type:

numpy.array