API Documentation

Here you can find the details of the various HNCcorr components.

This HNCcorr implementation has the following components:

  • Candidate - Contains the logic for segmenting a single cell.

  • Embedding - Provides the feature vector of each pixel.

  • GraphConstructor - Constructs the similarity graph.

  • HNC - Solves Hochbaum’s Normalized Cut (HNC) on a given similarity graph.

  • HNCcorr - Provides the overal logic for segmenting all cells in a movie.

  • Movie - Provides access to the data of a calcium imaging movie.

  • Patch - Represents a square subregion of a movie (used for segmenting a cell).

  • Positive / negative seed selector – Selects positive or negative seed pixels in a patch.

  • Post-processor - Selects the best segmentation (if any) for a cell.

  • Seeder - Generates candidate cell locations.

  • Segmentation - Represents a candidate segmentation of a cell.

Module contents

class hnccorr.base.HNCcorr(seeder, postprocessor, segmentor, positive_seed_selector, negative_seed_selector, graph_constructor, candidate_class, patch_class, embedding_class, patch_size)[source]

Bases: object

Implementation of the HNCcorr algorithm.

This class specifies all components of the algoritm and defines the procedure for segmenting the movie. How each candidate seed / location is evaluated is specified in the Candidate class.

References

Q Spaen, R Asín-Achá, SN Chettih, M Minderer, C Harvey, and DS Hochbaum (2019). HNCcorr: A Novel Combinatorial Approach for Cell Identification in Calcium-Imaging Movies. eNeuro, 6(2).

__init__(seeder, postprocessor, segmentor, positive_seed_selector, negative_seed_selector, graph_constructor, candidate_class, patch_class, embedding_class, patch_size)[source]

Initalizes HNCcorr object.

classmethod from_config(config=None)[source]

Initializes HNCcorr from an HNCcorrConfig object.

Provides a simple way to initialize an HNCcorr object from a configuration. Default components are used, and parameters are taken from the input configuration or inferred from the default configuration if not specified.

Parameters

config (HNCcorrConfig) – HNCcorrConfig object with modified configuration. Parameters that are not explicitly specified in the config object are taken from the default configuration DEFAULT_CONFIGURATION as defined in the hnccorr.config module.

Returns

Initialized HNCcorr object as parametrized by the configuration.

Return type

HNCcorr

segment(movie)[source]

Applies the HNCcorr algorithm to identify cells in a calcium-imaging movie.

Identifies cells the spatial footprints of cells in a calcium imaging movie. Cells are identified based on a set of candidate locations identified by the seeder. If a cell is found, the pixels in the spatial footprint are excluded as seeds for future segmentations. This prevents that a cell is segmented more than once. Although segmented pixels cannot seed a new segmentation, they may be segmented again.

Identified cells are accessible through the segmentations attribute.

Returns

Reference to itself.

segmentations_to_list()[source]

Exports segmentations to a list of dictionaries.

Each dictionary in the list corresponds to the footprint of a cell. Each dictionary contains the key coordinates containing a list of pixel coordinates. Each pixel coordinate is a tuple with the zero-indexed coordinates of the pixel. Pixels are indexed like matrix coordinates.

Returns

list[dict[tuple]]: List of cell coordinates.

class hnccorr.base.HNCcorrConfig(**entries)[source]

Bases: object

Configuration class for HNCcorr algorithm.

Enables tweaking the parameters of HNCcorr when used with the default components. Configurations are modular and can be combined using the addition operation.

Each parameter is accessible as an attribute when specified.

Variables

  • seeder_mask_size (int) – Width in pixels of the region used by the seeder to compute the average correlation between a pixel and its neighbors.

  • seeder_exclusion_padding (int) – Distance for excluding additional pixels surrounding segmented cells.

  • seeder_grid_size (int) – Size of grid bloc per dimension. Seeder maintains only the best candidate pixel for each grid block.

  • percentage_of_seeds (float[0, 1]) – Fraction of candidate seeds to evaluate.

  • postprocessor_min_cell_size (int) – Lower bound on pixel count of a cell.

  • postprocessor_max_cell_size (int) – Upper bound on pixel count of a cell.

  • postprocessor_preferred_cell_size (int) – Pixel count of a typical cell.

  • positive_seed_radius (int) – Radius of the positive seed square / superpixel.

  • negative_seed_circle_radius (int) – Radius in pixels of the circle with negative seeds.

  • negative_seed_circle_count (int) – Number of negative seeds.

  • gaussian_similarity_alpha (alpha) – Decay factor in gaussian similarity function.

  • sparse_computation_grid_distance (float) – 1 / grid_resolution. Width of each block in sparse computation.

  • sparse_computation_dimension (int) – Dimension of the low-dimensional space in sparse computation.

  • patch_size (int) – Size in pixel of each dimension of the patch.

  • _entries (dict) – Dict with parameter keys and values. Each parameter value (when defined) is also accessible as an attribute.

__add__(other)[source]

Combines two configurations and returns a new one.

If parameters are defined in both configurations, then other takes precedence.

Parameters

other (HNCcorrConfig) – Another configuration object.

Returns

Configuration with combined parameter sets.

Return type

HNCcorrConfig

Raises

TypeError – When other is not an instance of HNCcorrConfig.

__init__(**entries)[source]

Initializes HNCcorrConfig object.

class hnccorr.movie.Movie(name, data)[source]

Bases: object

Calcium imaging movie class.

Data is stored in an in-memory numpy array. Class supports both 2- and 3- dimensional movies.

Variables

  • name (str) – Name of the experiment.

  • _data (np.array) – Fluorescence data. Array has size T x N1 x N2. T is the number of frame (num_frames), N1 and N2 are the number of pixels in the first and second dimension respectively.

  • _data_size (tuple) – Size of array _data.

__getitem__(key)[source]

Provides direct access to the movie data.

Movie is stored in array with shape (T, N_1, N_2, …), where T is the number of frames in the movie. N_1, N_2, … are the number of pixels in the first dimension, second dimension, etc.

Parameters

key (tuple) – Valid index for a numpy array.

Returns

np.array

static _get_tiff_images_and_size(image_dir, num_images)[source]

Provides a sorted list of images and computes the required array size.

Data is assumed to be stored in 16-bit unsigned integers. Frame numbers are assumed to be padded with zeros: 00000, 00001, 00002, etc. This is required such that Python sorts the images correctly. Frame numbers can start from 0, 1, or any other number. Files must have the extension .tiff.

Parameters

  • image_dir (str) – Path of image folder.

  • num_images (int) – Number of images in the folder.

Returns

Tuple of the list of images and the array size.

Return type

tuple[List[Str], tuple]

static _read_images(images, output_array, subsampler)[source]

Loads images and copies them into the provided array.

Parameters

  • images (list[Str]) – Sorted list image paths.

  • output_array (np.array like) – T x N_1 x N_2 array-like object into which images should be loaded. T must equal the number of images in images. Each image should be of size N_1 x N_2.

  • subsampler –

Returns

The input array array.

Return type

np.array like

extract_valid_pixels(pixels)[source]

Returns subset of pixels that are valid coordinates for the movie.

classmethod from_tiff_images(name, image_dir, num_images, memmap=False, subsample=10)[source]

Loads tiff images into a numpy array.

Data is assumed to be stored in 16-bit unsigned integers. Frame numbers are assumed to be padded with zeros: 00000, 00001, 00002, etc. This is required such that Python sorts the images correctly. Frame numbers can start from 0, 1, or any other number. Files must have the extension .tiff.

If memmap is True, the data is not loaded into memory bot a memory mapped file on disk is used. The file is named $name.npy and is placed in the image_dir folder.

Parameters

  • name (str) – Movie name.

  • image_dir (str) – Path of image folder.

  • num_images (int) – Number of images in the folder.

  • memmap (bool) – If True, a memory-mapped file is used. (Default: False)

  • subsample (int) – Number of frames to average into a single frame.

Returns

Movie created from image files.

Return type

Movie

is_valid_pixel_coordinate(coordinate)[source]

Checks if coordinate is a coordinate for a pixel in the movie.

property num_dimensions

Dimension of the movie (excludes time dimension).

property num_frames

Number of frames in the movie.

property num_pixels

Number of pixels in the movie.

property pixel_shape

Resolution of the movie in pixels.