hnccorr.movie module

Components for calcium-imaging movies in HNCcorr.

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.

class hnccorr.movie.Patch(movie, center_seed, patch_size)[source]

Bases: object

Square subregion of Movie.

Patch limits the data used for the segmentation of a potential cell. Given a center seed pixel, Patch defines a square subregion centered on the seed pixel with width patch_size. If the square extends outside the movie boundaries, then the subregion is shifted such that it stays within the movie boundaries.

The patch also provides an alternative coordinate system with respect to the top left pixel of the patch. This pixel is the zero coordinate for the patch coordinate system. The coordinate offset is the coordinate of the top left pixel in the movie coordinate system.

Variables

  • _center_seed (tuple) – Seed pixel that marks the potential cell. The pixel is represented as a tuple of coordinates. The coordinates are relative to the movie. The top left pixel of the movie represents zero.

  • _coordinate_offset (tuple) – Movie coordinates of the pixel that represents the zero coordinate in the Patch object. Similar to the Movie, pixels in the Patch are indexed from the top left corner.

  • _data (np.array) – Subset of the Movie data. Only data for the patch is stored.

  • _movie (Movie) – Movie for which the Patch object is a subregion.

  • _num_dimensions (int) – Dimension of the patch. It matches the dimension of the movie.

  • _patch_size (int) – length of the patch in each dimension. Must be an odd number.

__getitem__(key)[source]

Access data for pixels in the patch. Indexed in patch coordinates.

__init__(movie, center_seed, patch_size)[source]

Initializes Patch object.

_compute_coordinate_offset()[source]

Computes the coordinate offset of the patch.

Confirms that the patch falls within the movie boundaries and shifts the patch if necessary. The center seed pixel may not be in the center of the patch if a shift is necessary.

_movie_indices()[source]

Computes the indices of the movie that correspond to the patch.

For a patch with top left pixel (5, 5) and bottom right pixel (9, 9), this method returns (:, 5:10, 5:10) which can be used to acccess the data corresponding to the patch in the movie.

enumerate_pixels()[source]

Returns the movie coordinates of the pixels in the patch.

property num_frames

Number of frames in the Movie.

property pixel_shape

Shape of the patch in pixels. Does not not included the time dimension.

to_movie_coordinate(patch_coordinate)[source]

Converts a movie coordinate into a patch coordinate.

Parameters

patch_coordinate (tuple) – Coordinates of a pixel in patch coordinate system.

Returns

Coordinate of pixel in movie coordinate system.

Return type

tuple

to_patch_coordinate(movie_coordinate)[source]

Converts a movie coordinate into a patch coordinate.

Parameters

movie_coordinate (tuple) – Coordinates of a pixel in movie coordinate system.

Returns

Coordinate of pixel in patch coordinate system.

Return type

tuple

class hnccorr.movie.Subsampler(movie_shape, subsample_frequency, buffer_size=10)[source]

Bases: object

Subsampler for averaging frames.

Averages subsample_frequency into a single frame. Stores averaged frames in a buffer and writes buffer to an output array.

Variables

  • _buffer (np.array) – (b, N_1, N_2) array where the frame averages are compiled.

  • _buffer_frame_count – (b, ) array with the number of frames used in each averaged frame.

  • _buffer_size (int) – Number of averaged frames to store in buffer. Short: b. Default is 10.

  • _buffer_start_index (int) – Index of averaged movie corresponding with first frame in the buffer.

  • _current_index (int) – Index of current frame in buffer.

  • _movie_shape (int) – Shape of input movie.

  • _num_effective_frames (int) – Number of frames in the averaged movie.

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

__init__(movie_shape, subsample_frequency, buffer_size=10)[source]

Initializes a subsampler object.

add_frame(frame)[source]

Adds frame to average.

Frames should be provided in order of appearance in the movie.

Parameters

frame (np.array) – (N_1, N_2) array with pixel intensities.

Returns

None

Raises

ValueError – If buffer is full.

advance_buffer()[source]

Empties buffer and advances the buffer indices for new frames

property buffer

Provides access to data in buffer. Corrects last buffer for movie length.

property buffer_full

True if buffer is full.

property buffer_indices

Indices in average movie corresponding to current buffer

property output_shape

Shape of average movie array.