API Documentation

motion_correction Module

frame_corrector Class

MotionCorrect Class

class jnormcorre.motion_correction.MotionCorrect(lazy_dataset: lazy_data_loader, max_shifts: tuple[int, int] = (6, 6), frames_per_split: int = 1000, num_splits_to_process_rig: int | None = None, niter_rig: int = 1, pw_rigid: bool = False, strides: tuple[int, int] = (96, 96), overlaps: tuple[int, int] = (32, 32), max_deviation_rigid: int = 3, num_splits_to_process_els: int | None = None, niter_els: int = 1, min_mov: float | None = None, upsample_factor_grid: int = 4, bigtiff: bool = False)[source]

class implementing motion correction operations

__init__(lazy_dataset: lazy_data_loader, max_shifts: tuple[int, int] = (6, 6), frames_per_split: int = 1000, num_splits_to_process_rig: int | None = None, niter_rig: int = 1, pw_rigid: bool = False, strides: tuple[int, int] = (96, 96), overlaps: tuple[int, int] = (32, 32), max_deviation_rigid: int = 3, num_splits_to_process_els: int | None = None, niter_els: int = 1, min_mov: float | None = None, upsample_factor_grid: int = 4, bigtiff: bool = False) → None[source]

Constructor class for motion correction operations

Parameters:

  • lazy_dataset (lazy_data_loader) – Lazy data loader for loading frames of the data

  • max_shifts (Tuple) – Two integers, specifying maximum shift in the two FOV dimensions (height, width)

  • frames_per_split (int) – Integer larger than 1. Number of frames we use to generate each local template.

  • num_splits_to_process_rig (int) – Number of splits we process per iteration of rigid motion correction

  • niter_rig (int) – Number of iterations of rigid motion correction

  • pw_rigid (bool) – Whether we additionally run piecewise rigid registration

  • strides (Tuple) – Two integers, used to specify patch dimensions for pwrigid registration

  • overlaps (Tuple) – Overlap b/w patches. strides[i] + overlaps[i] are the patch size dimensions.

  • max_deviation_rigid (int) – Specifies max number of pixels a patch can deviate from the rigid shifts.

  • num_splits_to_process_els (int) – Number of splits we process per iteration of pwrigid motion correction

  • niter_els – Number of iterations of piecewise rigid registration

  • min_mov (float) –

  • bigtiff (bool) – Indicates whether or not movie is saved as a bigtiff or regular tiff

motion_correct(template: ndarray | None = None, save_movie: bool | None = False) → tuple[FrameCorrector, str][source]

General driver function which performs motion correction

Parameters:

  • template (ndarray) – Template provided by user for motion correction default

  • save_movie (bool) – Flag for saving motion corrected file(s) as memory mapped file(s)

Returns:

  • frame_corrector_obj (jnormcorre.motion_correction.frame_corrector) – Object for applying frame correction with final inferred template

  • target_file (str) – path to saved file

Rigid Motion Correction Function

jnormcorre.motion_correction.register_frames_to_template_rigid(img: Array | ndarray | bool_ | number | bool | int | float | complex, template: Array | ndarray | bool_ | number | bool | int | float | complex, max_shifts: Array | ndarray | bool_ | number | bool | int | float | complex, add_to_movie: Array | ndarray | bool_ | number | bool | int | float | complex) → tuple[Array | ndarray | bool_ | number | bool | int | float | complex, Array | ndarray | bool_ | number | bool | int | float | complex]

Performs rigid registration of a series of frames to a single template.

Parameters:

  • img (jnp.array) – Shape (T, x, y), frames we want to register. T is number of frames, x and y are spatial dims

  • template (jnp.array) – Shape (x, y). Template image

  • max_shifts (jnp.array) – Has 2 integers specifying max shift in both FOV dimensions

  • add_to_movie (jnp.array) – Scalar value in jnp.array for adding to each frame.

Returns:

  • aligned (jnp.array) – Shape (T, x, y). Aligned version of “img” to template.

  • shifts (jnp.array) – Shape (T, 2). Row i describes dimension 1 and dimension 2 shifts applied to ith frame

jnormcorre.motion_correction.register_to_template_and_transfer_rigid(img: Array | ndarray | bool_ | number | bool | int | float | complex, img_filtered: Array | ndarray | bool_ | number | bool | int | float | complex, template: Array | ndarray | bool_ | number | bool | int | float | complex, max_shifts: tuple[int, int], add_to_movie: Array | ndarray | bool_ | number | bool | int | float | complex) → tuple[Array | ndarray | bool_ | number | bool | int | float | complex, Array | ndarray | bool_ | number | bool | int | float | complex]

This routine estimates the shifts needed to align one image stack (img_filtered) to a template, and applies those estimated shifts to img. This can be very useful for dual color imaging, 1p calcium imaging, and many other use cases.

Parameters:

  • img (np.array) – Shape (T, x, y), frames we want to register. T is number of frames, x and y are spatial dims

  • img_filtered (np.array). Shape (T, x, y) –

  • template (np.array) – Shape (x, y). Template image

  • max_shifts (np.array) – Has 2 integers specifying max shift in both FOV dimensions

  • add_to_movie (np.array) – Scalar value in jnp.array for adding to each frame.

Returns:

  • aligned (jnp.array) – Shape (T, x, y). Aligned version of “img” to template.

  • shifts (jnp.array) – Shape (T, 2). Row i describes dimension 1 and dimension 2 shifts applied to ith frame.

jnormcorre.motion_correction.register_frames_to_template_pwrigid(img: Array | ndarray | bool_ | number | bool | int | float | complex, template: Array | ndarray | bool_ | number | bool | int | float | complex, strides_0: int, strides_1: int, overlaps_0: int, overlaps_1: int, max_shifts: Array | ndarray | bool_ | number | bool | int | float | complex, upsample_factor_fft: int, max_deviation_rigid: int, add_to_movie: Array | ndarray | bool_ | number | bool | int | float | complex) → tuple[Array | ndarray | bool_ | number | bool | int | float | complex, Array | ndarray | bool_ | number | bool | int | float | complex]

Perform piecewise rigid motion correction iteration by (1) dividing the FOV in patches (2) motion correcting each patch separately (3) upsampling the motion correction vector field (4) stitching back together the corrected subpatches

Parameters:

  • img (np.ndarray) – Shape (T, x, y) Frames to register to template. T is number of frames, x and y spatial dims

  • template (np.ndarray) – Shape (x, y). The reference image

  • strides_0 (int) – The strides of the patches in which the FOV is subdivided along dimension 0.

  • strides_1 (int) – The strides of the patches in which the FOV is subdivided along dimension 1.

  • overlaps_0 (int) – Amount of pixel overlap between patches along dimension 0

  • overlaps_1 (int) – Amount of pixel overlap between patches along dimension 1

  • max_shifts (tuple) – Max shifts in x and y

  • upsample_factor_fft (int) – The resolution of fractional shifts

  • max_deviation_rigid (int) – Maximum deviation in shifts of each patch from the rigid shift (should not be large)

  • add_to_movie (np.array) – Constant offset to add to movie before registration to avoid negative values.

Returns:

  • new_img (jnp.array) – Shape (T, x, y), motion corrected version of img.

  • total_shifts (jnp.array) – Shape (T, num_patches, 2). For the i-th frame, we apply shifts to “num_patches” different patches. See below for more info.

In general, the coordinates of the k-th patch corresponding to total_shifts[i, k, :] are given this code

from jnormcorre import motion_correction
start, end = motion_correction.get_patch_start_and_end_coords(x, y, strides_0, strides_1,
            overlaps_0, overlaps_1)

They can be used as follows:

img_i[start[0]:end[0], start[1]:end[1]]
jnormcorre.motion_correction.register_to_template_and_transfer_pwrigid(img: Array | ndarray | bool_ | number | bool | int | float | complex, img_filtered: Array | ndarray | bool_ | number | bool | int | float | complex, template: Array | ndarray | bool_ | number | bool | int | float | complex, strides_0: int, strides_1: int, overlaps_0: int, overlaps_1: int, max_shifts: Array | ndarray | bool_ | number | bool | int | float | complex, upsample_factor_fft: int, max_deviation_rigid: int, add_to_movie: Array | ndarray | bool_ | number | bool | int | float | complex) → tuple[Array | ndarray | bool_ | number | bool | int | float | complex, Array | ndarray | bool_ | number | bool | int | float | complex]

Here we estimate the piecewise rigid shifts needed to optimally align the image stack imgs_filtered to template. Then we apply those estimated shifts to the image stack`img`. This is useful in the context of 1p imaging, where we might want to estimated shifts from a high-pass filtered movie, or in dual color imaging, where we might want to use a brighter channel to estimate shifts that we apply to a dimmer one.

Perform piecewise rigid motion correction on 1p data by (1) dividing the FOV in patches (2) motion correcting each patch separately (3) upsampling the motion correction vector field (4) stiching back together the corrected subpatches

Parameters:

  • img (np.ndarray) – Shape (T, x, y) Frames to register to template. T is number of frames, x and y spatial dims

  • imgs_filtered (np.ndarray). Shape (T, x, y) –

  • template (np.ndarray) – Shape (x, y). The reference image

  • strides_0 (int) – The strides of the patches in which the FOV is subdivided along dimension 0.

  • strides_1 (int) – The strides of the patches in which the FOV is subdivided along dimension 1.

  • overlaps_0 (int) – Amount of pixel overlap between patches along dimension 0

  • overlaps_1 (int) – Amount of pixel overlap between patches along dimension 1

  • max_shifts (tuple) – Max shifts in x and y

  • upsample_factor_fft (int) – The resolution of fractional shifts

  • max_deviation_rigid (int) – Maximum deviation in shifts of each patch from the rigid shift (should not be large)

  • add_to_movie (np.array) – Constant offset to add to movie before registration to avoid negative values.

Returns:

  • new_img (jnp.array) – Shape (T, x, y), motion corrected version of img.

  • total_shifts (jnp.array) – Shape (T, num_patches, 2). For the i-th frame, we apply shifts to “num_patches” different patches. See below for more info.

In general, the coordinates of the k-th patch corresponding to total_shifts[i, k, :] are given this code

from jnormcorre import motion_correction
start, end = motion_correction.get_patch_start_and_end_coords(x, y, strides_0, strides_1,
            overlaps_0, overlaps_1)

They can be used as follows:

img_i[start[0]:end[0], start[1]:end[1]]

jnormcorre.utils.lazy_array API

class jnormcorre.utils.lazy_array.lazy_data_loader[source]

Bases: ABC

This captures the numpy array-like functionality that all data loaders for motion correction need to contain

Key: To implement support for a new file type, you just need to specify the key properties below (dtype, shape, ndim) and then implement the function _compute_at_indices. Adapted from mesmerize core: https://github.com/nel-lab/mesmerize-core/blob/master/mesmerize_core/arrays/_base.py

abstract dtype()

data type

abstract shape()

Array shape (n_frames, dims_x, dims_y)

ndim()

Number of dimensions

abstract _compute_at_indices(indices: list | int | slice) → ndarray[source]

Lazy computation logic goes here to return frames. Slices the array over time (dimension 0) at the desired indices.

Parameters

indices: Union[list, int, slice]
the user’s desired way of picking frames, either an int, list of ints, or slice

i.e. slice object or int passed from __getitem__()

Returns

np.ndarray

array at the indexed slice

__getitem__(item: int | list | ndarray | Tuple[int | ndarray | slice | range])[source]
abstract property dtype: str

data type

property ndim: int

Number of dimensions

abstract property shape: Tuple[int, int, int]

Array shape (n_frames, dims_x, dims_y)

jnormcorre.utils.registrationarrays

class jnormcorre.utils.registrationarrays.TiffArray(filename)[source]
__init__(filename)[source]

TiffArray data loading object. Supports loading data from multipage tiff files.

Parameters:

filename (str) – Path to file

class jnormcorre.utils.registrationarrays.Hdf5Array(filename: str, field: str)[source]
__init__(filename: str, field: str) → None[source]

Generic lazy loader for Hdf5 files video files, where data is stored as (T, x, y). T is number of frames, x and y are the field of view dimensions (height and width).

Parameters:

  • filename (str) – Path to filename

  • field (str) – Field of hdf5 file containing data

class jnormcorre.utils.registrationarrays.RegistrationArray(registration_obj: FrameCorrector, data_to_register: lazy_data_loader, pw_rigid=False, reference_data: lazy_data_loader | None = None)[source]
__init__(registration_obj: FrameCorrector, data_to_register: lazy_data_loader, pw_rigid=False, reference_data: lazy_data_loader | None = None)[source]

Class for registering 2D functional imaging data on the fly. Useful for visualization libraries etc.

Parameters:

  • registration_obj (jnormcorre.motion_correction.FrameCorrector) – Object which can perform registration

  • data_to_register (jnormcorre.utils.lazy_array.lazy_data_loader) – Data loading object

  • pw_rigid (bool) – Indicates whether we apply rigid or piecewise rigid registration to frames

  • [Optional (reference_data) – A reference stack. If provided, the algorithm will find optimal alignment between template and each frame of this stack. It will then apply these shifts to “data_to_register”

class jnormcorre.utils.registrationarrays.FilteredArray(raw_data_loader: lazy_data_loader, filter_function: Callable, batching: int = 100)[source]
__init__(raw_data_loader: lazy_data_loader, filter_function: Callable, batching: int = 100)[source]

Class for loading and filtering data; this is broadly useful because we often want to spatially filter data to expose salient signals. We use this filtered version of the data to estimate shifts :param raw_data_loader: An object that supports the lazy_data_loader interface.

This can be for e.g. a custom object that reads data from disk, an array in RAM (like a numpy ndarray) or anything else

Parameters:

  • filter_function (Callable) – A function that applies a spatial filter to every frame of a data array. It takes an input movie of shape (frames, fov dim 1, fov dim 2) and returns a filtered movie of the same shape. The type of the output is cast to numpy array in this function.

  • batching (int) – Max number of frames we process on GPU at a time, used to avoid OOM errors.