suite2p.registration package

Submodules

suite2p.registration.bidiphase module

suite2p.registration.bidiphase.compute(frames)[source]

Returns the bidirectional phase offset, the offset between lines that sometimes occurs in line scanning.

Parameters

frames (frames x Ly x Lx) – random subsample of frames in binary (frames x Ly x Lx)

Returns

bidiphase – bidirectional phase offset in pixels

Return type

int

suite2p.registration.bidiphase.shift(frames, bidiphase)[source]

Shift last axis of ‘frames’ by bidirectional phase offset in-place, bidiphase.

Parameters
  • frames (frames x Ly x Lx) –

  • bidiphase (int) – bidirectional phase offset in pixels

Return type

None

suite2p.registration.metrics module

suite2p.registration.metrics.bin_median(mov, window=10)[source]
suite2p.registration.metrics.corr_to_template(mov, tmpl)[source]
suite2p.registration.metrics.filt_parallel(data, filt, num_cores)[source]
suite2p.registration.metrics.filt_worker(inputs)[source]
suite2p.registration.metrics.get_flow_metrics(ops)[source]

get farneback optical flow and some other stats from normcorre paper

suite2p.registration.metrics.get_pc_metrics(ops, use_red=False)[source]

Computes registration metrics using top PCs of registered movie

movie saved as binary file ops[‘reg_file’] metrics saved to ops[‘regPC’] and ops[‘X’] ‘regDX’ is nPC x 3 where X[:,0] is rigid, X[:,1] is average nonrigid, X[:,2] is max nonrigid shifts ‘regPC’ is average of top and bottom frames for each PC ‘tPC’ is PC across time frames

Parameters
  • ops (dict) – ‘nframes’, ‘Ly’, ‘Lx’, ‘reg_file’ (if use_red=True, ‘reg_file_chan2’) (optional, ‘refImg’, ‘block_size’, ‘maxregshiftNR’, ‘smooth_sigma’, ‘maxregshift’, ‘1Preg’)

  • use_red (bool, optional) – default False, whether to use ‘reg_file’ or ‘reg_file_chan2’

Returns

ops – The same as the ops input, but will now include ‘regPC’, ‘tPC’, and ‘regDX’.

Return type

dict

suite2p.registration.metrics.local_corr(mov, batch_size, num_cores)[source]

computes correlation image on mov (nframes x pixels x pixels)

suite2p.registration.metrics.optic_flow(mov, tmpl, nflows)[source]

optic flow computation using farneback

suite2p.registration.metrics.pc_register(pclow, pchigh, bidi_corrected, spatial_hp=None, pre_smooth=None, smooth_sigma=1.15, smooth_sigma_time=0, block_size=(128, 128), maxregshift=0.1, maxregshiftNR=10, reg_1p=False, snr_thresh=1.25, is_nonrigid=True, pad_fft=False, bidiphase_offset=0, spatial_taper=50.0)[source]

register top and bottom of PCs to each other

Parameters
  • pclow (float, array) – average of bottom of spatial PC: nPC x Ly x Lx

  • pchigh (float, array) – average of top of spatial PC: nPC x Ly x Lx

  • bidi_corrected (bool) – whether to do bidi correction.

  • spatial_hp (int) – high-pass filter window size for the spatial dimensions

  • pre_smooth (int) – low-pass filter window size for the spatial dimensions

  • smooth_sigma (int) – see registration settings

  • smooth_sigma_time (int) – see registration settings

  • block_size (int, int) – see registration settings

  • maxregshift (float) – see registration settings

  • maxregshiftNR (int) – see registration settings

  • reg_1p (bool) – see 1Preg settings

  • snr_thresh (float) – signal to noise threshold to use.

  • is_nonrigid (bool) –

  • pad_fft (bool) –

  • bidiphase_offset (int) –

  • spatial_taper (float) –

Returns

X – nPC x 3 where X[:,0] is rigid, X[:,1] is average nonrigid, X[:,2] is max nonrigid shifts

Return type

float array

suite2p.registration.metrics.pclowhigh(mov, nlowhigh, nPC, random_state)[source]

Compute mean of top and bottom PC weights for nPC’s of mov

computes nPC PCs of mov and returns average of top and bottom

Parameters
  • mov (frames x Ly x Lx) – subsampled frames from movie

  • nlowhigh (int) – number of frames to average at top and bottom of each PC

  • nPC (int) – number of PCs to compute

  • random_state – a value that sets the seed for the PCA randomizer.

Returns

  • pclow (float, array) – average of bottom of spatial PC: nPC x Ly x Lx

  • pchigh (float, array) – average of top of spatial PC: nPC x Ly x Lx

  • w (float, array) – singular values of decomposition of mov

  • v (float, array) – frames x nPC, how the PCs vary across frames

suite2p.registration.nonrigid module

suite2p.registration.nonrigid.block_interp(ymax1, xmax1, mshy, mshx, yup, xup)[source]

interpolate from ymax1 to mshy to create coordinate transforms

Parameters
  • ymax1

  • xmax1

  • mshy (Ly x Lx) – meshgrid in y

  • mshx (Ly x Lx) – meshgrid in x

  • yup (nimg x Ly x Lx) – y shifts for each coordinate

  • xup (nimg x Ly x Lx) – x shifts for each coordinate

suite2p.registration.nonrigid.calculate_nblocks(L, block_size=128)[source]

Returns block_size and nblocks from dimension length and desired block size

Parameters
  • L (int) –

  • block_size (int) –

Return type

Tuple[int, int]

Returns

  • block_size (int)

  • nblocks (int)

suite2p.registration.nonrigid.getSNR(cc, lcorr, lpad)[source]

Compute SNR of phase-correlation.

Parameters
  • cc (nimg x Ly x Lx) – The frame data to analyze

  • lcorr (int) –

  • lpad (int) – border padding width

Returns

snr

Return type

float

suite2p.registration.nonrigid.make_blocks(Ly, Lx, block_size=(128, 128))[source]

Computes overlapping blocks to split FOV into to register separately

Parameters
  • Ly (int) – Number of pixels in the vertical dimension

  • Lx (int) – Number of pixels in the horizontal dimension

  • block_size (int, int) – block size

Returns

  • yblock (float array)

  • xblock (float array)

  • nblocks (int, int)

  • block_size (int, int)

  • NRsm (array)

suite2p.registration.nonrigid.map_coordinates(I, yc, xc, Y)[source]

In-place bilinear transform of image ‘I’ with ycoordinates yc and xcoordinates xc to Y

Parameters
  • I (Ly x Lx) –

  • yc (Ly x Lx) – new y coordinates

  • xc (Ly x Lx) – new x coordinates

  • Y (Ly x Lx) – shifted I

Return type

None

suite2p.registration.nonrigid.phasecorr(data, maskMul, maskOffset, cfRefImg, snr_thresh, NRsm, xblock, yblock, maxregshiftNR, subpixel=10, lpad=3)[source]

Compute phase correlations for each block

Parameters
  • data (nimg x Ly x Lx) –

  • maskMul (ndarray) – gaussian filter

  • maskOffset (ndarray) – mask offset

  • cfRefImg – FFT of reference image

  • snr_thresh (float) – signal to noise ratio threshold

  • NRsm

  • xblock (float array) –

  • yblock (float array) –

  • maxregshiftNR (int) –

  • subpixel (int) –

  • lpad (int) – upsample from a square +/- lpad

Returns

  • ymax1

  • xmax1

  • cmax1

suite2p.registration.nonrigid.phasecorr_reference(refImg0, maskSlope, smooth_sigma, yblock, xblock, pad_fft=False)[source]

Computes taper and fft’ed reference image for phasecorr.

Parameters
  • refImg0 (array) –

  • maskSlope

  • smooth_sigma

  • yblock (float array) –

  • xblock (float array) –

  • pad_fft (bool) – whether to do border padding in the fft step

Returns

  • maskMul

  • maskOffset

  • cfRefImg

suite2p.registration.nonrigid.shift_coordinates(data, yup, xup, mshy, mshx, Y)[source]

Shift data into yup and xup coordinates

Parameters
  • data (nimg x Ly x Lx) –

  • yup (nimg x Ly x Lx) – y shifts for each coordinate

  • xup (nimg x Ly x Lx) – x shifts for each coordinate

  • mshy (Ly x Lx) – meshgrid in y

  • mshx (Ly x Lx) – meshgrid in x

  • Y (nimg x Ly x Lx) – shifted data

suite2p.registration.nonrigid.transform_data(data, nblocks, xblock, yblock, ymax1, xmax1, bilinear=True)[source]

Piecewise affine transformation of data using block shifts ymax1, xmax1

Parameters
  • data (nimg x Ly x Lx) –

  • nblocks ((int, int)) –

  • xblock (float array) –

  • yblock (float array) –

  • ymax1 (nimg x nblocks) – y shifts of blocks

  • xmax1 (nimg x nblocks) – y shifts of blocks

  • bilinear (bool (optional, default=True)) – do bilinear interpolation, if False do nearest neighbor

Returns

Y – shifted data

Return type

float32, nimg x Ly x Lx

suite2p.registration.nonrigid.upsample_block_shifts(Lx, Ly, nblocks, xblock, yblock, ymax1, xmax1)[source]

upsample blocks of shifts into full pixel-wise maps for shifting

this function upsamples ymax1, xmax1 so that they are nimg x Ly x Lx for later bilinear interpolation

Parameters
  • Lx (int) – number of pixels in the horizontal dimension

  • Ly (int) – number of pixels in the vertical dimension

  • nblocks ((int, int)) –

  • xblock (float array) –

  • yblock (float array) –

  • ymax1 (nimg x nblocks) – y shifts of blocks

  • xmax1 (nimg x nblocks) – y shifts of blocks

Returns

  • yup (nimg x Ly x Lx) – y shifts for each coordinate

  • xup (nimg x Ly x Lx) – x shifts for each coordinate

suite2p.registration.register module

suite2p.registration.register.compute_crop(xoff, yoff, corrXY, th_badframes, badframes, maxregshift, Ly, Lx)[source]

determines how much to crop FOV based on motion

determines badframes which are frames with large outlier shifts (threshold of outlier is th_badframes) and it excludes these badframes when computing valid ranges from registration in y and x

Parameters
  • xoff (int) –

  • yoff (int) –

  • corrXY

  • th_badframes

  • badframes

  • maxregshift

  • Ly (int) – Height of a frame

  • Lx (int) – Width of a frame

Returns

  • badframes

  • yrange

  • xrange

suite2p.registration.register.compute_reference(ops, frames)[source]

computes the reference image

picks initial reference then iteratively aligns frames to create reference

Parameters
  • ops (dictionary) – need registration options

  • frames (3D array, int16) – size [nimg_init x Ly x Lx], frames to use to create initial reference

Returns

refImg – size [Ly x Lx], initial reference image

Return type

2D array, int16

suite2p.registration.register.compute_reference_masks(refImg, ops=None)[source]
suite2p.registration.register.enhanced_mean_image(ops)[source]

computes enhanced mean image and adds it to ops

Median filters ops[‘meanImg’] with 4*diameter in 2D and subtracts and divides by this median-filtered image to return a high-pass filtered image ops[‘meanImgE’]

Parameters

ops (dictionary) – uses ‘meanImg’, ‘aspect’, ‘spatscale_pix’, ‘yrange’ and ‘xrange’

Returns

ops – ‘meanImgE’ field added

Return type

dictionary

suite2p.registration.register.pick_initial_reference(frames)[source]

computes the initial reference image

the seed frame is the frame with the largest correlations with other frames; the average of the seed frame with its top 20 correlated pairs is the inital reference frame returned

Parameters

frames (3D array, int16) – size [frames x Ly x Lx], frames from binary

Returns

refImg – size [Ly x Lx], initial reference image

Return type

2D array, int16

suite2p.registration.register.register_binary(ops, refImg=None, raw=True)[source]

main registration function

if ops is a list of dictionaries, each will be registered separately

Parameters
  • ops (dictionary or list of dicts) – ‘Ly’, ‘Lx’, ‘batch_size’, ‘align_by_chan’, ‘nonrigid’ (optional ‘keep_movie_raw’, ‘raw_file’)

  • refImg (2D array (optional, default None)) –

  • raw (bool (optional, default True)) – use raw_file for registration if available, if False forces reg_file to be used

Returns

ops – ‘nframes’, ‘yoff’, ‘xoff’, ‘corrXY’, ‘yoff1’, ‘xoff1’, ‘corrXY1’, ‘badframes’

Return type

dictionary

suite2p.registration.register.register_frames(refAndMasks, frames, ops=None)[source]

register frames to reference image

Parameters
  • ops (dictionary or list of dicts) – ‘Ly’, ‘Lx’, ‘batch_size’, ‘align_by_chan’, ‘nonrigid’ (optional ‘keep_movie_raw’, ‘raw_file’)

  • refImg (2D array (optional, default None)) –

  • raw (bool (optional, default True)) – use raw_file for registration if available, if False forces reg_file to be used

Returns

ops – ‘nframes’, ‘yoff’, ‘xoff’, ‘corrXY’, ‘yoff1’, ‘xoff1’, ‘corrXY1’, ‘badframes’

Return type

dictionary

suite2p.registration.register.shift_frames(frames, yoff, xoff, yoff1, xoff1, ops=None)[source]

suite2p.registration.rigid module

suite2p.registration.rigid.apply_masks(data, maskMul, maskOffset)[source]

Returns a 3D image ‘data’, multiplied by ‘maskMul’ and then added ‘maskOffet’.

Parameters
  • data (nImg x Ly x Lx) –

  • maskMul (ndarray) –

  • maskOffset (ndarray) –

Returns

maskedData

Return type

nImg x Ly x Lx

suite2p.registration.rigid.compute_masks(refImg, maskSlope)[source]

Returns maskMul and maskOffset from an image and slope parameter

Parameters
  • refImg (Ly x Lx) – The image

  • maskSlope

Return type

Tuple[ndarray, ndarray]

Returns

  • maskMul (float arrray)

  • maskOffset (float array)

suite2p.registration.rigid.phasecorr(data, cfRefImg, maxregshift, smooth_sigma_time)[source]

compute phase correlation between data and reference image

Parameters
  • data (int16) – array that’s frames x Ly x Lx

  • maxregshift (float) – maximum shift as a fraction of the minimum dimension of data (min(Ly,Lx) * maxregshift)

  • smooth_sigma_time (float) – how many frames to smooth in time

Return type

Tuple[int, int, float]

Returns

  • ymax (int) – shifts in y from cfRefImg to data for each frame

  • xmax (int) – shifts in x from cfRefImg to data for each frame

  • cmax (float) – maximum of phase correlation for each frame

suite2p.registration.rigid.phasecorr_reference(refImg, smooth_sigma=None, pad_fft=False)[source]

Returns reference image fft’ed and complex conjugate and multiplied by gaussian filter in the fft domain, with standard deviation ‘smooth_sigma’ computes fft’ed reference image for phasecorr.

Parameters

refImg (2D array, int16) – reference image

Returns

cfRefImg

Return type

2D array, complex64

suite2p.registration.rigid.shift_frame(frame, dy, dx)[source]

Returns frame, shifted by dy and dx

Parameters
  • frame (Ly x Lx) –

  • dy (int) – vertical shift amount

  • dx (int) – horizontal shift amount

Returns

frame_shifted – The shifted frame

Return type

Ly x Lx

suite2p.registration.utils module

suite2p.registration.utils.combine_offsets_across_batches(offset_list, rigid)[source]
suite2p.registration.utils.complex_fft2(img, pad_fft=False)[source]

Returns the complex conjugate of the fft-transformed 2D array ‘img’, optionally padded for speed.

Parameters
  • img (Ly x Lx) – The image to process

  • pad_fft (bool) – Whether to pad the image

Return type

ndarray

suite2p.registration.utils.convolve(mov, img)[source]

Returns the 3D array ‘mov’ convolved by a 2D array ‘img’.

Parameters
  • mov (nImg x Ly x Lx) – The frames to process

  • img (2D array) – The convolution kernel

Returns

convolved_data

Return type

nImg x Ly x Lx

suite2p.registration.utils.gaussian_fft(sig, Ly, Lx)[source]

gaussian filter in the fft domain with std sig and size Ly,Lx

Parameters
  • sig

  • Ly (int) – frame height

  • Lx (int) – frame width

Returns

fhg – smoothing filter in Fourier domain

Return type

np.ndarray

suite2p.registration.utils.kernelD(xs, ys, sigL=0.85)[source]

Gaussian kernel from xs (1D array) to ys (1D array), with the ‘sigL’ smoothing width for up-sampling kernels, (best between 0.5 and 1.0)

Parameters
  • xs (ndarray) –

  • ys (ndarray) –

  • sigL (float) –

Return type

ndarray

suite2p.registration.utils.kernelD2(xs, ys)[source]
Parameters
  • xs (int) –

  • ys (int) –

Return type

ndarray

suite2p.registration.utils.mat_upsample(lpad, subpixel=10)[source]

upsampling matrix using gaussian kernels

Parameters
  • lpad (int) –

  • subpixel (int) –

Returns

  • Kmat (np.ndarray)

  • nup (int)

suite2p.registration.utils.meshgrid_mean_centered(x, y)[source]

Returns a mean-centered meshgrid

Parameters
  • x (int) – The height of the meshgrid

  • y (int) – The width of the mehgrid

Return type

Tuple[ndarray, ndarray]

Returns

  • xx (int array)

  • yy (int array)

suite2p.registration.utils.spatial_high_pass(data, N)[source]

high pass filters data over axis=1,2 with window N

Parameters
  • data (Ly x Lx) – The image to smooth.

  • N (int) – The window size

Returns

smoothed_data – The smoothed frame

Return type

Ly x Lx

suite2p.registration.utils.spatial_smooth(data, window)[source]

Spatially smooth data using cumsum over axis=1,2 with window N

Parameters
  • data (Ly x Lx) – The image to smooth.

  • window (int) – The window size

Returns

smoothed_data – The smoothed frame

Return type

Ly x Lx

suite2p.registration.utils.spatial_taper(sig, Ly, Lx)[source]

Returns spatial taper on edges with gaussian of std sig

Parameters
  • sig

  • Ly (int) – frame height

  • Lx (int) – frame width

Returns

Return type

maskMul

suite2p.registration.utils.temporal_smooth(data, sigma)[source]

Returns Gaussian filtered ‘frames’ ndarray over first dimension

Parameters
  • data (nImg x Ly x Lx) –

  • sigma (float) – windowing parameter

Returns

smoothed_data – Smoothed data

Return type

nImg x Ly x Lx

suite2p.registration.zalign module

suite2p.registration.zalign.compute_zpos(Zreg, ops)[source]

compute z position of frames given z-stack Zreg

Parameters
  • Zreg (3D array) – size [nplanes x Ly x Lx], z-stack

  • ops (dictionary) – ‘reg_file’ <- binary to register to z-stack, ‘smooth_sigma’, ‘Ly’, ‘Lx’, ‘batch_size’

Returns

  • ops_orig

  • zcorr

suite2p.registration.zalign.register_stack(Z, ops)[source]
Parameters
  • Z

  • ops (dict) –

Returns

  • Zreg (nplanes x Ly x Lx) – Z-stack

  • ops (dict)

Module contents