Table Of Contents

Search

Enter search terms or a module, class or function name.

Motion correction

The SIMA package can be used to motion correct sequentially acquired images. The package implements several strategies, all of which have a common interface described below.

class sima.motion.MotionEstimationStrategy
correct(dataset, savedir, channel_names=None, info=None, correction_channels=None, trim_criterion=None)

Create a motion-corrected dataset.

Parameters:
  • dataset (sima.ImagingDataset or list of sima.Sequence) – Dataset or sequences to be motion corrected.
  • savedir (str) – The directory used to store the dataset. If the directory name does not end with .sima, then this extension will be appended.
  • channel_names (list of str, optional) – Names for the channels. Defaults to [‘0’, ‘1’, ‘2’, ...].
  • info (dict) – Data for the order and timing of the data acquisition. See sima.ImagingDataset for details.
  • correction_channels (list of int, optional) – Information from the channels corresponding to these indices will be used for motion correction. By default, all channels will be used.
  • trim_criterion (float, optional) – The required fraction of frames during which a location must be within the field of view for it to be included in the motion-corrected imaging frames. By default, only locations that are always within the field of view are retained.
Returns:

dataset – The motion-corrected dataset.
Return type:

sima.ImagingDataset
estimate(dataset)

Estimate the displacements for a dataset.

Parameters:dataset (sima.ImagingDataset) –
Returns:displacements
Return type:list of ndarray of int

The specific strategies for motion correction are listed below. These strategies must be initialized as documented below, and then can be applied to datasets using the generic interface described above.

class sima.motion.HiddenMarkov2D(granularity=2, num_states_retained=50, max_displacement=None, n_processes=1, restarts=None, verbose=True)

Hidden Markov model (HMM) in two dimensions.

Parameters:
  • granularity (int, str, or tuple, optional) – The granularity of the calculated displacements. A separate displacement can be calculated for each frame (granularity=0 or granularity=’frame’), each plane (1 or ‘plane’), each row (2 or ‘row’), or pixel (3 or ‘column’). As well, a separate displacement can be calculated for every n consecutive elements (e.g. granularity=(‘row’, 8) for every 8 rows). Defaults to one displacement per row.
  • num_states_retained (int, optional) – Number of states to retain at each time step of the HMM. Defaults to 50.
  • max_displacement (array of int, optional) – The maximum allowed displacement magnitudes in [y,x]. By default, arbitrarily large displacements are allowed.
  • n_processes (int, optional) – Number of pool processes to spawn to parallelize frame alignment. Defaults to 1.
  • restarts (int, optional) – How often to reinitialize the hidden Markov model. This can be useful if there are long breaks between frames or planes. Parameter values of 0 or 1 reinitialize the hidden states every frame or plane, respectively. By default, the hidden distribution of positions is never reinitialized during the sequence.
  • verbose (bool, optional) – Whether to print information about progress.

References

  • Dombeck et al. 2007. Neuron. 56(1): 43-57.
  • Kaifosh et al. 2013. Nature Neuroscience. 16(9): 1182-4.
class sima.motion.HiddenMarkov3D(granularity=2, num_states_retained=50, max_displacement=None, n_processes=1, restarts=None, verbose=True)

Hidden Markov model (HMM) with displacements in three dimensions.

Parameters:
  • granularity (int, str, or tuple, optional) – The granularity of the calculated displacements. A separate displacement can be calculated for each frame (granularity=0 or granularity=’frame’), each plane (1 or ‘plane’), each row (2 or ‘row’), or pixel (3 or ‘column’). As well, a separate displacement can be calculated for every n consecutive elements (e.g.granularity=(‘row’, 8) for every 8 rows). Defaults to one displacement per row.
  • num_states_retained (int, optional) – Number of states to retain at each time step of the HMM. Defaults to 50.
  • max_displacement (array of int, optional) – The maximum allowed displacement magnitudes in [z, y,x]. By default, arbitrarily large displacements are allowed.
  • n_processes (int, optional) – Number of pool processes to spawn to parallelize frame alignment. Defaults to 1.
  • restarts (int, optional) – How often to reinitialize the hidden Markov model. This can be useful if there are long breaks between frames or planes. Parameter values of 0 or 1 reinitialize the hidden states every frame or plane, respectively. default, the hidden distribution of positions is never reinitialized during the sequence.
  • verbose (bool, optional) – Whether to print information about progress.

References

  • Dombeck et al. 2007. Neuron. 56(1): 43-57.
  • Kaifosh et al. 2013. Nature Neuroscience. 16(9): 1182-4.
class sima.motion.DiscreteFourier2D(upsample_factor=1, max_displacement=None, num_images_for_mean=100, randomise_frames=True, err_thresh=0.01, max_iterations=5, rotation_scaling=False, save_fmt='mptiff', save_name=None, n_processes=1, verbose=False, return_registered=False)

Motion correction of image sequences by ‘efficient subpixel image registration by cross correlation’. A reference image is iteratively computed by aligning and averaging a subset of images/frames.

Parameters:
  • upsample_factor (int, optional) – upsample factor. final pixel alignment has resolution of 1/upsample_factor. if 1 only pixel level shifts are made - faster - and no interpolation. Default: 1.
  • max_displacement (array of int, optional) – The maximum allowed displacement magnitudes in [y,x]. Default: None.
  • num_images_for_mean (int, optional) – number of images to use to make the aligned mean image. Default: 100.
  • randomise_frames (bool, optional) – randomise the images selected to make the mean image? if false the first ‘num_frames_for_mean’ frames will be used. Default: True.
  • err_thresh (float, optional) – the threshold of mean pixel offset at which to stop aligning the mean image. Default: 0.01.
  • max_iterations (int, optional) – the maximum number of iterations to compute the aligned mean image. Default: 5.
  • rotation_scaling (bool, optional) – not yet implemented. Default: False.
  • save_name (string, optional) – the file name for saving the final registered array of images to disk from within method. If None or ‘none’, the array will not be saved. Default: None.
  • save_fmt (string, optional) – the tiff format to save as. options include ‘mptiff’, ‘bigtiff’, ‘singles’. Default: ‘mptiff’.
  • n_processes (int, optional) – number of workers to use (multiprocessing). Default: 1.
  • verbose (bool, optional) – enable verbose mode. Default: False.
  • return_registered (bool, optional) – return registered frames? Default: False.

References

Parts of the code are based on: skimage.feature.register_translation, which is a port of MATLAB code by Manuel Guizar-Sicairos, Samuel T. Thurman, and James R. Fienup, “Efficient subpixel image registration algorithms,” Optics Letters 33, 156-158 (2008).

class sima.motion.PlaneTranslation2D(max_displacement=None, method='correlation', n_processes=1)

Estimate 2D translations for each plane.

Parameters:
  • max_displacement (array of int, optional) – The maximum allowed displacement magnitudes in [y,x]. By default, arbitrarily large displacements are allowed.
  • method ({‘correlation’, ‘ECC’}) – Alignment method to be used.
  • n_processes (int, optional) – Number of pool processes to spawn to parallelize frame alignment. Defaults to 1.
class sima.motion.VolumeTranslation(max_displacement=None, criterion=None)

Translate 3D volumes to maximize the correlation.

Parameters:
  • max_displacement (array of int, optional) – The maximum allowed displacement magnitudes in [z,y,x]. By default, arbitrarily large displacements are allowed.
  • criterion (float, optional) – The number of standard deviations below the mean correlation that a frame’s correlation can have following displacement for the displacement to be considered valid. Invalid displacements will be masked.
class sima.motion.ResonantCorrection(base_strategy, offset=0)

Motion estimation strategy for resonant scanner data.

When acquiring data imaging data with a resonant scanner, the data acquired when imaging the same positions can be substantially different depending no whether the resonant scanner is moving in one direction or the other when passing over that row. This can cause problems when trying to motion correct the data, since even rows are collected while scanning in one direction and odd rows are collected by scanning in the other direction.

The class defined here addresses this issue by using only the even rows to estimate the displacements, and then uses those displacements to motion-correct the entire dataset.

Parameters:
  • base_strategy (sima.motion.MotionEstimationStrategy) – The underlying motion estimation strategy that will be used.
  • offset (int) – Horizontal displacement to be added to odd rows. Note the convention that row 0 (i.e. the “first” row) is considered even.