pydnn.preprocess module

Overview

Most of the code in this module is currently pretty specific to processing images like those in Kaggle’s plankton competition. Those images were unique in that they (1) were presented with a uniform background, (2) they varied in size in a way that provided meaningful information about the subject, and (3) they were mostly randomly oriented. These features have to do with real world constraints on the way that marine biologist collect the images, and are obviously quite different from popular datasets like ImageNet, MNIST, etc. As I (or others) use pydnn in a greater variety of machine learning contexts a variety of preprocessing approaches can be maintained here.

Training Set

pydnn.preprocess.split_training_data(data, batch_size, train_per, valid_per, test_per)

Split training data into training set, validation set and test sets. If split results in incomplete batches this function will allocate observations from incomplete batches in validation and test sets to the training set to attempt to make a complete batch. This function also reports on the split and whether there were observations that did not fit evenly into any batch. (Currently NN assumes a validation and test set, so if allocating 100% of data to training set, split_training_data() will duplicate the first batch of the training set for the validation and test sets so NN does not fail. In that case, obviously the validation and test loss will be meaningless.)

Parameters:
  • data (tuple) – all the data, including x and y values
  • batch_size (int) – number of observations that will be in each batch
  • train_per (float) – percentage of data to put in training set
  • valid_per (float) – percentage of data to put in validation set
  • test_per (float) – percentage of data to put in test set
Returns:

a list containing the training, validation and test sets, each of which is a list containing each variable (in the case where x data is a single image that will be a list of images and a list of y classes, but there can also be more than one x variable).

Preprocessors

Preprocessors take care of online augmentation, shuffling, zero centering and normalizing, resizing, and other related transformations of the traning data. Because the plankton images could be in any orientation, to achieve good performance it was important to augment the data with many rotations of the training set so the network could learn to recognize images in different orientations. Initially I experimented with 90 degree rotations and a flip, however I found that unconstrained degree rotations (Rotator360 and Rotator360PlusGeometry) performed better. Another approach that I experimented with was rotating and flipping all images into a canonicalized orientation based on their shape and size (Canonicalizer), which significantly improves early training progress, but shortly thereafter falls behind a 360 degree rotation approach.

Another thing that these preprocessors do is add additional data channels. For instance, since, in the case of the plankton dataset, the size of the images carries important information (because image size was related to the size of the organism) it was useful to add a data channel with the original image size (Rotator360), because that information is lost when uniformly resizing images to be fed into the neural network. Another approach, instead of the original image size, was to create a channel with the size of the largest contiguous image shape, and it’s rotation in comparison to it’s canonicalized rotation (Rotator360PlusGeometry).

class pydnn.preprocess.Rotator360(data, image_shape, resizer, rng, dtype='float32')

Rotates training set images randomly.

(Also zero centers by pixel, normalizes, shuffles, resizes, etc.)

Parameters:
  • data – x and y data
  • image_shape – the target image shape
  • resizer – the resizer to use when uniformly resizing images
  • rng – random number generator
  • dtype (string) – the datatype to output
class pydnn.preprocess.Rotator360PlusGeometry(data, image_shape, resizer, rng, dtype)

Rotates training set images randomly, but also generates additional geometric data about the size and orientation of the organism in the image.

(Also zero centers by pixel, normalizes, shuffles, resizes, etc.)

Parameters:
  • data – x and y data
  • image_shape – the target image shape
  • resizer – the resizer to use when uniformly resizing images
  • rng – random number generator
  • dtype (string) – the datatype to output
class pydnn.preprocess.Canonicalizer(data, image_shape, resizer, rng, dtype)

Rotates and flips all images into a canonicalized form. Using a statistical measure of object height rotates each image to minimize height. (Can also either (1) flip images so aggregate pixel intensity is highest in one corner, or (2) generate random flips of training images.)

(Also zero centers by pixel, normalizes, shuffles, resizes, etc.)

Parameters:
  • data – x and y data
  • image_shape – the target image shape
  • resizer – the resizer to use when uniformly resizing images
  • rng – random number generator
  • dtype (string) – the datatype to output

Resizing

Users do not use the resizers directly but pass them to a preprocessor to control how the preprocessor resizes images.

pydnn.preprocess.Resizer()

Base class for StretchResizer, ContiguousBoxPreserveAspectRatioResizer, ContiguousBoxStretchResizer, ThresholdBoxPreserveAspectRatioResizer, ThresholdBoxStretchResizer, PreserveAspectRatioResizer, and StochasticStretchResizer

Some resizers may want to resize training images differently from validation or testing images so this class gives them the option of doing so.

pydnn.preprocess.StretchResizer()

Stretches the images to a uniform shape ignoring aspect ratio

pydnn.preprocess.ContiguousBoxPreserveAspectRatioResizer(threshold)

First crops the images around the largest contiguous region, then stretches them to a uniform size preserving aspect ratio.

pydnn.preprocess.ContiguousBoxStretchResizer(threshold)

First crops the images around the largest contiguous region, then stretches them to a uniform ignoring aspect ratio.

pydnn.preprocess.ThresholdBoxPreserveAspectRatioResizer(threshold)

First crops the images, throwing away outside space without pixels that exceed a given threshold, then stretches them to a uniform size preserving aspect ratio.

pydnn.preprocess.ThresholdBoxStretchResizer(threshold)

First crops the images, throwing away outside space without pixels that exceed a given threshold, then stretches them to a uniform ignoring aspect ratio.

pydnn.preprocess.PreserveAspectRatioResizer()

Stretches images to a uniform size preserving aspect ratio.

pydnn.preprocess.StochasticStretchResizer(rng, rand_range)

Stretches images to a uniform size ignoring aspect ratio.

Randomly varies how much training images are stretched.