$project

$project provides tools for counting cell colonies on plates of growth medium.

Look how easy it is to use:

<TODO>

Features

• Convolutional neural networks for image processing with (hopefully) less parameter tuning

Installation

Install $project by running:

pip install $project

Contribute

• Issue Tracker: github.com/sheaconlon/$project/issues
• Source Code: github.com/sheaconlon/$project

Support

If you are having issues, you can email us at sheaconlon at berkeley.edu.

dataset module

class src.dataset.Dataset(path, segment_size=None)

A dataset consisting of some examples of input/output pairs. Minimizes memory usage by keeping most of the dataset on disk at any given time.

Note that if there are extra examples beyond a multiple of SEGMENT_SIZE,

then these examples will be ignored.

close()

Close this dataset. This dataset will not be useable afterward.

This method must be called because it deletes temporary files on disk.

get_batch(size)

Get a batch of examples.

Parameters:size (int) – The number of examples. Returns:

The inputs and outputs of the batch. Each

array has size rows, where the i-th row corresponds to the i-th example.

Return type:(tuple of np.ndarray)

get_data_fn(batch_size, num_batches)

Get a data function for this dataset.

Parameters:

• batch_size (int) – The number of examples to put in each batch.
• num_batches (int) – The number of batches to produce.

Returns:

A data function giving num_batches batches of batch_size

examples each.

Return type:

(func)

initialize_from_aspects(path, transform)

Initialize by reading some examples’ aspects and generating inputs

and outputs from them.

Each directory in the data directory will be interpreted as

representing an example. In each of these example directories, each file will be interpreted as representing an aspect of the example, with the aspect’s name being the file’s base name and the aspect’s value being the file’s contents. Each aspect file must be in either a PNG or CSV format, with the appropriate file extension. Images must be 8-bit grayscale.

Parameters:

• path (str) – The path to the data directory.
• transform (func) – A function that when called with a dictionary mapping aspect names to aspect values for a particular example returns a tuple of input np.ndarray and output np.ndarray for that example.

load_image_mask_pairs(image_dir, mask_dir, dims)

Makes the inputs be the pixels of the images in one directory and

makes the outputs be the pixels of correspondingly-named mask images in another directory.

Finds pairs of images and mask images by listing the files in the mask

directory. Therefore, while all mask images need to have an image, not all images need to have a mask image.

Parameters:

• image_dir (str) – The path to the directory containing the images.
• mask_dir (str) – The path to the directory containing the mask images.
• dims (tuple of int) – The dimensions to resize the images and mask images to. Should be a 2-element tuple of height and width.

load_images_and_excel_labels(image_dir_path, label_sheet_path, filename_col, label_col, shape)

Makes the inputs be the pixels of the images in some directory and

the labels be given by an Excel spreadsheet mapping those images’ filenames to integers.

Parameters:

• image_dir_path (str) – The path to the directory containing the images.
• label_sheet_path (str) – The path to the spreadsheet containing the labels.
• filename_col (str) – The column in the spreadsheet that contains the filenames.
• label_col (str) – The column in the spreadsheet that contains the labels.
• shape (tuple of int) – The shape to resize the images to. Should be a 3-element tuple of height, width, and channel depth.

load_images_masks_labels_from_json(metadata_path, image_path_getter, mask_path_getter, label_getter, shape)

Assumes there is a JSON metadata file which contains, for each

example, the path of an image, the path of a mask image, and a label. Makes the inputs be the images with pixels in the black area of the mask image set to black. Makes the outputs be the labels.

Note that this will resize the mask images, which will lead to mask

image values that are neither black nor white. Pixels whose average value over R, G, and B is less than MaskedImagesFromMetadataIterator.MASK_EXCLUDE_MAX will be considered black.

Parameters:

• metadata_path (str) – The path to the JSON metadata file.
• image_path_getter (func(dict) -> str) – A function that takes the metadata for an example and returns the path to the example’s image.
• mask_path_getter (func(dict) -> str) – A function that takes the JSON metadata for an example and returns the path to the example’s mask image.
• label_getter (func(dict) -> int) – A function that takes the JSON metadata for an example and returns the example’s label.
• shape (tuple of int) – The shape to resize the images and mask images to. Should be a 3-element tuple of height, width, and channel depth.

map(fn)

Map a function onto this dataset.

Parameters:fn (func(tuple of np.ndarray) -> sequence of tuple of np.ndarray) – A function that takes in an example as a tuple of input and output. It returns a sequence of one or more new examples to replace the passed in example with.

map_batch(fn)

Map a function onto this dataset by applying it to batches.

Parameters:fn (func(tuple of np.ndarray) -> tuple of np.ndarray) – A function that takes in an array of inputs and an array of outputs for a batch of examples. It returns a new array of inputs and a new array of outputs to replace this batch.

set_segment_size(n)

Set the segment size of this dataset, the number of examples that

this dataset stores in each of its files.

Any extra examples beyond a multiple of the new segment size will be

discarded.

Parameters:n (int) – The new segment size.

size()

Return the size of this dataset.

Returns:(int) The size of this dataset.

split(p, path_larger, path_smaller)

Split this dataset.

Note: Will assign entire segments to one part of the split or the other.

Result may not approximate p well if there aren’t many segments. If the number of segments is very small, there is the possibility for errors.

Parameters:

• p (float) – The proportion of the dataset to put in the smaller part of the split.
• path_larger (str) – The path to a directory in which to store the larger part of the split.
• path_smaller (str) – The path to a directory in which to store the smaller part of the split.

Returns:

The two datasets that result from the

split. The smaller one is last.

Return type:

(tuple of dataset.Dataset)

losses module

src.losses.make_class_difference_loss(class_fn=<function <lambda>>, exp=1)

Make a class-difference loss function.

The cvlass difference loss is this: sum_{(c,y)} sum_{i=0}^7 y_i|class_fn(i) - class_fn(c)|^exp

c is the correct class for an example y is the softmax of the model’s output for an example (a vector)

Parameters:

• class_fn (func(tf.Tensor) -> tf.Tensor) – A function that takes class numbers and returns numbers. Applied to the class numbers before they are used in the calculation. Default is the identity function.
• exp (float) – The exponent on the class difference. Default is 1.

src.losses.make_cross_entropy_loss()

Make a softmax cross-entropy loss function.

Returns:

(func) Cross-entropy loss function. Takes as input the correct outputs

(np.ndarray) and predicted outputs (np.ndarray) for a batch of examples. Returns the cross-entropy loss for that batch (tf.Tensor).

metric module

class src.metric.BaseMetric

A metric.

evaluate(model)

Evaluate a model. Also records the result.

Parameters:model (model.BaseModel) – The model. Returns:(tf.Tensor) The value of this metric for the model.

get_results()

Get the results for this metric from all past evaluations.

Returns:

In the first list, the i-th element is the number

of examples seen at the i-th evaluation. In the second list, the i-th element is the value of this metric during the i-th evaluation.

Return type:(tuple of lists)

class src.metric.ConfusionMatrixMetric(batch, num_classes)

A confusion matrix metric.

evaluate(model)

Calculate the confusion matrix of a model. Also records the result.

Parameters:model (model.BaseModel) – The model. Must be a classifier, whose output is an array of per-class scores. Returns:

An array of size (num_classes, num_classes) where the value at

(i, j) is the number of times that the model predicted class i when the true class was class j.

plot(title, height, width)

Plot this metric.

class src.metric.LossMetric(batch, loss_fn)

A loss metric.

evaluate(model)

Calculate the loss of a model. Also records the result.

Parameters:model (model.BaseModel) – The model. Returns:(float) The loss.

plot(title, x_lab, y_lab, height, width)

Plot this metric.

class src.metric.NonexclusiveConfusionMatrixMetric(batch, num_classes)

A nonexclusive confusion matrix metric.

A nonexclusive confusion matrix views a model as producing a prediction

which is a probability distribution over classes. Instead of tallying one prediction for the class of maximal score/probability as in normal confusion matrices, it tallies a fractional prediction for each class. It then normalizes the entire confusion matrix so that its entries sum to the number of examples, as in normal confusion matrices. Note that to the calculate the probability distribution over classes, the scores are passed through softmax.

evaluate(model)

Calculate the nonexclusive confusion matrix of a model. Also records

the result.

Parameters:model (model.BaseModel) – The model. Must be a classifier, whose output is an array of per-class scores. Returns:

An array of size (num_classes, num_classes) where the value at

(i, j) is like the number of times that the model predicted class i when the true class was class j.

class src.metric.OffByCountMetric(batch, num_classes)

An off-by count metric.

evaluate(model)

Calculate the off-by counts of a model. Also records the result.

Parameters:model (model.BaseModel) – The model. Returns:

An array with shape (2*self._num_classes + 1) where

the entries are the number of times the model’s prediction was off by -num_classes, …, 0, …, and num_classes, respectively.

Return type:(np.ndarray)

class src.metric.PredictionThroughputMetric(batch)

A prediction time metric.

evaluate(model)

Calculate the average prediction throughput of a model. Also records

the result.

Parameters:model (model.BaseModel) – The model. Returns:

The average number of examples per second that the model

can predict.

Return type:(float)

model module

class src.model.BaseModel(save_dir, chkpt_save_interval, loss_fn, optimizer_factory)

A model.

evaluate(metrics)

Evaluate some metrics about the model.

Parameters:(dict (str, metrics.BaseMetric)) – A mapping from metric names to metrics. Returns:

A mapping from metric names to the metric

results.

Return type:(dict(str, np.ndarray))

get_global_step()

Get the number of training iterations that this model has gone through.

predict(inputs)

Predict the outputs for some inputs.

Parameters:inputs (np.ndarray) – The inputs. Returns:The predicted outputs. Return type:(np.ndarray)

train(dataset, seconds)

Train the model on some data.

Parameters:

• dataset (dataset.Dataset) – The dataset to train on.
• seconds ((int)) – The (approximate) number of seconds to train for.

neural_net module

class src.neural_net.BatchNormalizationLayer(axis, name)

A batch normalization layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.ConvolutionalLayer(n_filters, window_side, window_stride, padding_method, weight_init, bias_init=None, weight_reg=None, bias_reg=None, name=None)

A convolutional layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.DropoutLayer(keep_prob, noise_shape, seed, name)

A dropout layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, size]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.FlatLayer(name)

A flattening layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.FullLayer(size, weight_init, bias_init, weight_reg=None, bias_reg=None, name=None)

A fully-connected layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, size]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.LocalResponseNormalizationLayer(depth_radius, bias, alpha, beta, name)

A local response normalization layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.PoolingLayer(pooling_type, window_side, window_stride, padding_method, name)

A pooling layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

class src.neural_net.TransferLayer(transfer_fn, name)

A transfer layer of a neural network.

output(previous)

Get the output of this layer.

Parameters:previous (tf.Tensor) – The output of the layer before this one. Must have shape [n_batches, height, width, channels]. Returns:A tf.Tensor representing the output of this layer.

postprocess module

src.postprocess.count_regions(image, patch_size, patch_classifier, batch_size, min_dist, min_diam, sampling_interval=1, debug=False)

Count the number of regions in an image. Uses a classifier that can, for

any given pixel of the image, give the probabilities of that pixel being inside a region, on the edge of a region, and outside all regions.

Treats the edges of the image accoring to the “valid” strategy.

Parameters:

• image (np.ndarray) – The image. Must have shape (height, width, channels).
• patch_size (int) – The side length of the patches to feed to patch_classifier, in pixels. Must be odd and at least 3.
• patch_classifier (func) – The patch scorer. Takes as argument a np.ndarray of shape (num_patches, patch_size, patch_size, channels) giving a sequence of patches of the image. Returns a np.ndarray of shape (num_patches, 3), where the i-th row pertains to the pixel at the center of the i-th patch and gives the probabilities of that pixel being inside a region, on the edge of a region, and outside all regions, respectively.
• batch_size (int) – The ideal number of patches to submit to patch_scorer in each call.
• min_dist (int) – The minimum distance between the centers of two regions, in pixels.
• min_diam (float) – The minimum diameter of a region, in pixels.
• sampling_interval (int) – In every square of the image with side length sampling_interval pixels, a single pixel will be chosen for classification. The default value is 1, which causes every pixel to be classified.
• debug (bool) – Whether to plot each intermediate step for debugging purposes. False by default.

Returns:

(int) The number of regions in the image.

preprocess module

src.preprocess.divide_median_normalize(images)

Normalize some images by dividing by their median values.

The normalization is performed independently for each channel of each image.

Parameters:images (np.ndarray) – The images. Must have shape (num_images, height, width, num_channels). Returns:The normalized images. Return type:(np.ndarray)

src.preprocess.extract_patches(image, class_image, size, max_patches=inf, class_dist=None)

Extract square patches of an image and their corresponding classes.

Uses the “VALID” padding method, meaning that no patches centered near the

edge of the image are extracted.

Parameters:

• image (np.ndarray) – The image. Must have shape (height, width, channels).
• class_image (np.ndarray) – The class image. Must have shape (height, width) and type int. classes[y, x] gives the class of the patch centered at (x, y) in the image.
• size (int) – The desired side length (in pixels) of the patches. Must be odd.
• max_patches (int) – The maximum number of patches. Up to this many patches will be returned. Fewer will be returned if necessary to produce the desired class_dist. If omitted or None, the maximum is infinity.
• class_dist (dict(int, float)) – The desired class distribution of the patches. class_dist[cls] is the fraction of the patches which should be of cls. If omitted or None, a uniform distribution is assumed. Note that the resulting class distribution will not be exactly class_dist.

Returns:

Patches of the image (shape

(n, size, size, 3)) and their corresponding classes (shape (n)).

Return type:

(tuple(np.ndarray, np.ndarray))

Throws:

ValueError if there are not enough patches of some class to fulfill

the request.

src.preprocess.one_hot_encode(labels, num_classes)

One-hot encodes labels.

Parameters:

• labels (np.ndarray) – An array of labels. Assumed to have shape (batch_size, 1).
• num_classes (int) – The number of classes.

Returns:

(np.ndarray) An array of one-hot encoded labels with shape

(batch_size, num_classes)

src.preprocess.smdm_normalize(images, window, padding)

Normalizes an image using the “divide by global median, subtract local mean”

approach.

Normalizes each channel independently.

Parameters:

• images (np.ndarray) – An array of images. Assumed to have shape (batch_size, height, width, channels).
• window (int) – The window size that should be used for the “subtract local mean” step. Must be odd.
• padding (str) – The type of padding to use when computing local means. Must be one of “CONSTANT”, “REFLECT”, or “SYMMETRIC”.

Returns:

(np.ndarray) A normalized array of images.

Throws:

ValueError: The window size was even.

src.preprocess.subtract_mean_normalize(images)

Normalize some images by subtracting their mean values.

The normalization is performed independently for each channel of each image.

Parameters:images (np.ndarray) – The images. Must have shape (num_images, height, width, num_channels). Returns:The normalized images. Return type:(np.ndarray)

src.preprocess.variance_of_variance_curve(images, min_size, max_size, num_sizes, samples)

Calculate the variance of variance curve of some images.

The variance of variance curve is a mapping from patch size to the variance

of the variances of the patches of that size. Variances are taken over all the positions and all the channels of a patch. Patch sizes are logarithmically spaced in the range [min_size, max_size]. min_size and max_size are included.

See extract_patches(…) for further description of patches.

Parameters:

• images (np.ndarray) – The images. Must have shape (num_images, height, width, num_channels).
• min_size (int) – The smallest patch size to include. Must be odd.
• max_size (int) – The largest patch size to include. Must be odd.
• num_sizes (int) – The number of patch sizes to include.
• samples (int) – The number of patches to sample for the variance calculation for each patch size.

Returns:

Two np.ndarrays, both of shape (num_sizes). The first array

contains the included patch sizes. The second array contains the corresponding variances of variances.

Return type:

(tuple)

utilities module

src.utilities.tensor_eval(tensor)

Evaluate a tensor.

Parameters:tensor (tf.Tensor) – The tensor. Returns:(np.ndarray) The value of the tensor.

visualization module

src.visualization.plot_confusion_matrix(mtx, title, height, width)

Plot a confusion matrix.

Parameters:

• mtx (np.ndarray) – An output of metrics.ConfusionMatrixMetric.evaluate.
• title (str) – A title for the plot.
• height (int) – The height of the plot, in inches.
• width (int) – The width of the plot, in inches.

src.visualization.plot_images(images, cols, dims, title, subtitles=None, path=None)

Plot images in a grid.

Parameters:

• images (np.ndarray) – The images. Must have shape (num_images, …).
• cols (int) – The number of grid columns.
• dims (tuple of float) – The dimensions to plot each image with, as a tuple of height and width, both in inches.
• title (str) – The title for the plot.
• subtitles (list of str) – The list of subtitles for the images. The i-th element is the subtitle for the i-th image. If omitted or None, no subtitles are plotted.
• path (str) – The path to save the plot to. If None or omitted, the plot is showed.

src.visualization.plot_line(xs, ys, title, x_label, y_label, height, width)

Plot a line.

Parameters:

• xs (list of float) – The x-values.
• ys (list of float) – The y-values.
• title (str) – The title.
• x_label (str) – The label for the x-axis.
• y_label (str) – The label for the y-axis.
• height (int) – The height of the plot, in inches.
• width (int) – The width of the plot, in inches.

src.visualization.plot_lines(xs, sets_of_ys, title, x_label, y_label, line_labels, height, width)

Plot some lines.

Parameters:

• xs (list of float) – The x-values.
• sets_of_ys (list of np.ndarray) – The y-values. The y-value of the j-th line at xs[i] is ys[i][j].
• title (str) – The title.
• x_label (str) – The label for the x-axis.
• y_label (str) – The label for the y-axis.
• line_labels (list of str) – The labels for the lines.
• height (int) – The height of the plot, in inches.
• width (int) – The width of the plot, in inches.

src.visualization.plot_scatter(xs, ys, title, x_label, y_label, height, width)

Make a scatterplot.

Parameters:

• xs (list of float) – The x-values.
• ys (list of float) – The y-values.
• title (str) – The title.
• x_label (str) – The label for the x-axis.
• y_label (str) – The label for the y-axis.
• height (int) – The height of the plot, in inches.
• width (int) – The width of the plot, in inches.