glimpse.experiment

Data Structures

class CorpusData(fields=None, **kw)

class_names = None

(list of str) Name for each object class, with indices corresponding to the values in the labels attribute.

labels = None

(1D ndarray of int) Class label for each input image

paths = None

(list of str) Path for each input image

training_set = None

(1D ndarray of bool) Mask indicating if each image is in the training set, as specified by user.

class ExtractorData(fields=None, **kw)

activation = None

(tuple of BaseState) Activation maps for each image, organized by (image, layer, scale, y, x).

model = None

(Model) Glimpse model

params = None

(Params) Parameters for Glimpse model XXX is this needed?

training_set = None

(1D ndarray of bool) Mask indicating if each image is in the training set, as used for prototype learning. This is None if corpus.training_set is given, or if prototypes are not derived from training data.

class EvaluationData(fields=None, **kw)

Parameters and results for classifier evaluation.

The evaluator creates feature vectors on the fly from activation maps in extractor.activation, based on values in evaluation.layers list. Thus, the set of feature vectors are not explicitly stored. The method for building these features is specified by the user via the feature_builder argument. See TrainAndTestClassifier() and CrossValidateClassifier().

layers = None

Layers from which features are extracted.

results = Data({})

Outcome of evaluation. This may contain one or more measurements of classifier accuracy, AUC, etc.

training_set = None

(1D ndarray of bool) Mask indicating if each image is in the training set, as used during evaluation. This is None if either corpus.training_set or extractor.training_set is given, or if a fixed training set is not used during evaluation (e.g., if cross-validation is used).

class ExperimentData(fields=None, **kw)

Results and settings for an experiment.

corpus = CorpusData({'class_names': None, 'labels': None, 'paths': None, 'training_set': None})

Input image data (exactly one).

evaluation = []

(list of EvaluationData) Classification performance on feature data (zero or more).

extractor = ExtractorData({'activation': None, 'model': None, 'params': None, 'training_set': None})

Feature extraction (exactly one).

Running Experiments

Verbose(flag=None)

Set the verbosity of log output.

Parameters:flag (bool) – Whether to enable verbose logging.

SetModel(exp, model=None, params=None, **kw)

Add a model to an existing experiment.

If model is passed, it is stored in the experiment’s extractor.model attribute. Otherwise, the parameters are created/updated, and used to create a new Model object.

Parameters:

• model (Model) – Existing model object to use.
• params (Params) – Existing model parameters to use.

All remaining keyword arguments are treated as model parameters and overwrite values in the (created or passed) params argument. This allows the set of parameters to be specified in short-hand as

>>> SetModel(param1=1, param2=2)

without creating a Params object.

SetCorpus(exp, root_dir, balance=False, reader=None)

Read images from the corpus directory.

This function assumes that each sub-directory contains images for exactly one object class, with a different object class for each sub-directory. Training and testing subsets are chosen automatically.

Parameters:

• root_dir (str) – Path to corpus directory.
• balance (bool) – Ensure an equal number of images from each class (by random selection).
• reader – Filesystem reader.

See also

SetCorpusSubdirs(), SetCorpusSplit()

SetCorpusSubdirs(exp, subdirs, balance=False, reader=None)

Read images from per-class corpus sub-directories.

This function assumes that each sub-directory contains images for exactly one object class, with a different object class for each sub-directory. Training and testing subsets are chosen automatically.

Parameters:

• subdirs (iterable of str) – Path of each corpus sub-directory.
• balance (bool) – Ensure an equal number of images from each class (by random selection).
• reader – Filesystem reader.

See also

SetCorpus(), SetCorpusSplit()

SetCorpusSplit(exp, train_dir, test_dir, reader=None)

Read images and training information from the corpus directory.

This function assumes that the train_dir and test_dir have the same set of sub-directories. Each sub-directory shoudl contain images for exactly one object class, with a different object class for each sub-directory.

Parameters:

• train_dir (str) – Path to corpus of training images.
• test_dir (str) – Path to corpus of test images.
• reader – Filesystem reader.

See also

SetCorpus(), SetCorpusSubdirs()

MakePrototypes(exp, num_prototypes, algorithm, pool=None, train_size=None, progress=None)

Create a set of S2 prototypes, and use them for this experiment.

Parameters:

• num_prototypes (int) – Number of prototypes to create.
• algorithm (callable or str) – Prototype learning algorithm, or name of such an algorithm.
• pool – Worker pool to use for parallel computation.
• train_size (float or int) – Size of training split, specified as a fraction (between 0 and 1) of total instances or as a number of instances (1 to N, where N is the number of available instances).
• progress – Handler for incremental progress updates.

If algorithm is a function, it will be called as

>>> algorithm(num_prototypes, model, make_training_exp, pool, progress)

where model is the experiment’s hierarchical model. The argument make_training_exp is a function that takes no arguments and returns the training experiment (i.e., an ExperimentData object containing only training images and labels. Calling this method has the side-effect that the original experiment’s extractor.training_set attribute will be set if corpus.training_set is empty.

If algorithm has a locations attribute, it is assumed to contain a list of num_prototypes x 4 arrays with list indexed by kernel width and array indexed by prototype. Each row of the array contains (image index, scale offset, y-offset, x-offset). The algorithm sets image indices relative to the training set, and this function rewrites those indices relative to the full corpus.

ComputeActivation(exp, layers, pool, save_all=False, progress=None)

Compute the model activity for all images in the experiment.

Parameters:

• layers (str or list of str) – One or more model layers to compute.
• pool – Worker pool to use for parallel computation.
• save_all (bool) – Whether to save activation for all model layers, rather than just those in layers.
• progress – Handler for incremental progress updates.

TrainAndTestClassifier(exp, layers, learner=None, train_size=None, feature_builder=None, score_func=None)

Evaluate extracted features using a fixed train/test split.

Parameters:

• layers (str or list of str) – Layers of model activity from which to extract features.
• learner – Learning algorithm, which is fit to features. This should be a scikit-learn classifier object. If not set, a LinearSVC object is used.
• train_size (float or int) – Size of training split, specified as a fraction (between 0 and 1) of total instances or as a number of instances (1 to N, where N is the number of available instances).
• feature_builder (callable) – A feature builder, such as ExtractFeatures() or ExtractHistogramFeatures().
• score_func (str) – Name of the scoring function to use, as specified by ResolveScoreFunction().

Creates a new entry in the experiment’s evaluation list, and sets the feature_builder, classifier, training_predictions, training_score, score_func, predictions, and score keys in its results dictionary.

CrossValidateClassifier(exp, layers, learner=None, feature_builder=None, num_folds=None, score_func=None)

Evaluate extracted features using a fixed train/test split.

Parameters:

• layers (str or list of str) – Layers of model activity from which to extract features.
• learner – Learning algorithm, which is fit to features. This should be a scikit-learn classifier object. If not set, a LinearSVC object is used.
• feature_builder (callable) – A feature builder, such as ExtractFeatures() or ExtractHistogramFeatures().
• num_folds (int) – Number of folds to use for cross-validation. Default is 10.

Creates a new entry in the experiment’s evaluation list, and sets the feature_builder, cross_validate, classifier, score_func, and score keys in its results dictionary. The number of folds can be deduced from the number of score values.

ExtractFeatures(layers, states)

Create feature vectors from the activation maps for a set of images.

Parameters:

• layers (LayerSpec or tuple of LayerSpec) – Model layers to use when constructing feature vector.
• features (list of BaseState) – Model activity for a set of images.

Return type:

2D ndarray of float

Returns:

1D feature vector for each image

ExtractHistogramFeatures(layers, states, low=0, high=0.2, bins=None)

Compute image features as a histogram over location and scale.

Parameters:

• layers (str or list of str) – One or more model layers to compute.
• states (list of BaseState) – Model state for each image.
• low (float) – Minimum range for histogram.
• high (float) – Maximum range for histogram.
• bins (float) – Number of bins in histogram.

Return type:

2-d array of float

Returns:

Feature vectors.

Prototype Algorithms

class ImprintAlg(record_locations=True)

Learn prototypes by imprinting from training images.

locations = None

Image locations from which samples were drawn.

class ShuffledAlg(record_locations=True)

Learn prototypes by shuffling a set of imprinted prototypes.

class UniformAlg(low=0, high=1)

Create prototypes by sampling components uniformly.

high = None

Upper limit of uniform distribution.

low = None

Lower limit of uniform distribution.

class KmeansAlg(learn_patches=None)

Learn prototypes as centroids of C1 patches using k-Means.

class MFWKmeansAlg

Learn patch models by meta-feature weighted k-Means clustering.

See also

mf_wkmeans.LearnPatchesFromImages.

num_regr_samples = None

Number of samples with which to train regr model

class OMWKmeansAlg

Learn patch models by object-mask weighted k-Means clustering.

See also

om_wkmeans.LearnPatchesFromImages.

base_weight = None

Weight added for all patches.

mask_dir = None

Directory containing object masks.

GetAlgorithmNames()

Lookup the name of all available prototype algorithm.

Return type:list of str Returns:Name of all known prototype algorithms, any of which can be passed to ResolveAlgorithm().

Analyzing Results

GetImagePaths(exp)

Returns the filename for each image in the corpus.

GetLabelNames(exp)

Returns the class name for each image in the corpus.

GetParams(exp)

Returns the model parameters for the experiment.

GetNumPrototypes(exp, kwidth=0)

Return the number of S2 prototypes in the model.

Parameters:kwidth (int) – Index of kernel shape.

GetImprintLocation(exp, prototype=0, kwidth=0)

Return the image location from which a prototype was imprinted.

This requires that the prototypes were learned by imprinting.

Parameters:

• prototype (int) – Index of S2 prototype.
• kwidth (int) – Index of kernel shape.

Returns:

Location information in the format (image index, scale, y-offset, x-offset), where scale and y- and x-offsets identify the S2 unit from which the prototype was “imprinted”.

Return type:

4 element array of int

GetPrototype(exp, prototype, kwidth=0)

Return an S2 prototype from the experiment.

Parameters:

• prototype (int) – Index of S2 prototype.
• kwidth (int) – Index of kernel shape.

GetImagePatchForImprintedPrototype(exp, prototype=0, kwidth=0)

Get the image patch used to create a given imprinted prototype.

Parameters:

• prototype (int) – Index of S2 prototype.
• kwidth (int) – Index of kernel shape.

Return type:

2d-array of float

Returns:

image data used to construct given imprinted prototype

GetBestPrototypeMatch(exp, image, prototype=0, kwidth=0)

Find the S2 unit with maximum response for a given prototype and image.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• prototype (int) – Index of S2 prototype.
• kwidth (int) – Index of kernel shape.

Return type:

3-tuple of int

Returns:

S2 unit, given as (scale, y, x)

GetImageActivity(exp, image, scale=0)

Returns image layer for a given image and scale.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band.

Return type:

2d array of float

Returns:

Image data.

GetTrainingSet(exp, evaluation=0)

Returns the experiment’s training set.

The extractor determines the training set by checking the experiment’s corpus.training_set attribute, and then randomly constructing a set if needed. The constructed set is stored in the experiment’s extractor.training_set attribute.

The evaluator determines the training set by checking the experiment’s extractor.training_set attribute, then its corpus.training_set, and then randomly constructing a set if needed. The constructed set is stored in the training_set attribute of the experiment’s new evaluation record created by the evaluator.

Parameters:evaluation (int) – Index of the evaluation record to use. Return type:1D array of bool Returns:Mask array indicating which images are in the training set.

GetPredictions(exp, training=False, evaluation=0)

Get information about classifier predictions.

Parameters:

• exp – Experiment data.
• training (bool) – Return information about training images. Otherwise, information about the test set is returned.
• evaluation (int) – Index of the evaluation record to use.

Return type:

list of 3-tuple of str

Returns:

filename, true label, and predicted label for each image in the set

GetEvaluationLayers(exp, evaluation=0)

Returns the model layers from which features were extracted.

Parameters:evaluation (int) – Index of the evaluation record to use. Return type:list of str Returns:Names of layers used for evaluation.

GetEvaluationResults(exp, evaluation=0)

Returns the results of a model evaluation.

Parameters:evaluation (int) – Index of the evaluation record to use. Return type:glimpse.util.data.Data Returns:Result data, with attributes that depend on the method of evaluation. In general, the feature_builder, score, score_func attributes will be available.

ShowS2Activity(exp, image, scale=0, prototype=0, kwidth=0)

Plot the S2 activity for a given image.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.
• prototype (int) – Index of S2 prototype to use.
• kwidth (int) – Index of kernel shape.

AnnotateS2Activity(exp, image, scale=0, prototype=0, kwidth=0)

Plot the S2 activity and image data for a given image.

This shows the image in the background, with the S2 activity on top.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.
• prototype (int) – Index of S2 prototype to use.
• kwidth (int) – Index of kernel shape.

AnnotateBestPrototypeMatch(exp, image, prototype=0, kwidth=0)

Plot the location that best matches a given S2 prototype.

This shows the image in the background, with a red box over the region elliciting maximal response.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• prototype (int) – Index of S2 prototype to use.
• kwidth (int) – Index of kernel shape.

AnnotateImprintedPrototype(exp, prototype=0, kwidth=0)

Plot the image region used to construct a given imprinted prototype.

This shows the image in the background, with a red box over the imprinted region.

Parameters:

• prototype (int) – Index of S2 prototype to use.
• kwidth (int) – Index of kernel shape.

ShowPrototype(exp, prototype, kwidth=0, **kw)

Plot the prototype activation.

There is one plot for each orientation band.

Parameters:

• prototype (int) – Index of S2 prototype to use.
• kwidth (int) – Index of kernel shape.
• colorbar (bool) – Add a colorbar to the plot.

ShowC1Activity(exp, image, scale=0, **kw)

Plot the C1 activation for a given image.

There is one plot for each orientation band.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.

AnnotateC1Activity(exp, image, scale=0, cols=2, colorbar=True, normalize=True)

Plot the C1 activation for a given image.

This shows the image in the background, with the activation plotted on top. There is one plot for each orientation band.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.

ShowS1Activity(exp, image, scale=0, **kw)

Plot the S1 activation for a given image.

There is one plot for each orientation band.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.

AnnotateS1Activity(exp, image, scale=0, cols=2, colorbar=True, normalize=True)

Plot the S1 activation for a given image.

This shows the image in the background, with the activation plotted on top. There is one plot for each orientation band.

Parameters:

• image – Path to image on disk, or index of image in experiment.
• scale (int) – Index of scale band to use.
• colorbar (bool) – Whether to show colorbar with plot.

ShowS1Kernels(exp, **kw)

Plot the S1 Gabor kernels.

There is one plot for each orientation band.

Miscellaneous

exception ExpError

Indicates that an error occurred while processing an Experiment.

class DirReader(ignore_hidden=True)

Read directory contents.

ReadDirs(dir_path)

Read list of sub-directories.

Parameters:dir_path (str) – Filesystem for directory to read. Return type:list of str Returns:List of sub-directories in directory.

ReadFiles(dir_path)

Read list of files.

Parameters:dir_path (str) – Filesystem for directory to read. Return type:list of str Returns:List of files in directory.

ignore_hidden = None

Ignore hidden directory entries (i.e., those starting with ‘.’).

ReadCorpusDirs(dirs, reader)

Create list of paths and class labels for a set of image directories.

Parameters:

• dirs (list of str) – Directory for each image class.
• reader – Filesystem reader.

ResolveLayers(exp, layers)

Resolve layer names to LayerSpec objects.

This is an internal function.

Parameters:layers (str or list of str) – One or more model layers to compute. Return type:list of LayerSpec Returns:Resolved layer specs.

BalanceCorpus(labels, shuffle=False)

Choose a subset of instances, such that the resulting corpus is balanced.

A balanced corpus has the same number of instances for each class.

Parameters:

• labels (1D array of int) – Instance class labels.
• shuffle (bool) – Whether to randomly choose the included instances. By default, instances in the tail of the list are always dropped.

Return type:

1D array of bool

Returns:

Mask of chosen instances.

GetCorpusByName(name)

Return the path to a sample corpus of images.

Parameters:name (str) – Corpus name. One of ‘easy’, ‘moderate’, or ‘hard’. Return type:str Returns:Filesystem path to corpus root directory.

Subpackages

• glimpse.experiment.mf_wkmeans
• glimpse.experiment.om_wkmeans