NIPY logo

Site Navigation

NIPY Community

Github repo

Table Of Contents

This Page

algorithms.registration.groupwise_registration

Module: algorithms.registration.groupwise_registration

Inheritance diagram for nipy.algorithms.registration.groupwise_registration:

Classes

FmriRealign4d

class nipy.algorithms.registration.groupwise_registration.FmriRealign4d(images, slice_order, interleaved=None, tr=1.0, tr_slices=None, start=0.0, time_interp=True, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, slice_info=None)

Bases: nipy.algorithms.registration.groupwise_registration.Realign4d

Methods

estimate
resample
__init__(images, slice_order, interleaved=None, tr=1.0, tr_slices=None, start=0.0, time_interp=True, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, slice_info=None)

Spatiotemporal realignment class for fMRI series.

Parameters :

images : image or list of images

Single or multiple input 4d images representing one or several fMRI runs.

tr : float

Inter-scan repetition time, i.e. the time elapsed between two consecutive scans. The unit in which tr is given is arbitrary although it needs to be consistent with the tr_slices and start arguments.

tr_slices : float

Inter-slice repetition time, same as tr for slices. If None, acquisition is assumed continuous and tr_slices is set to tr divided by the number of slices.

start : float

Starting acquisition time respective to the implicit time origin.

slice_order : str or array-like

If str, one of {‘ascending’, ‘descending’}. If array-like, then the order in which the slices were collected in time. For instance, the following represents an ascending contiguous sequence:

slice_order = [0, 1, 2, ...]

interleaved : bool

Deprecated.

Whether slice acquisition order is interleaved. Ignored if slice_order is array-like.

If slice_order==’ascending’ and interleaved==True, the assumed slice order is:

[0, 2, 4, ..., 1, 3, 5, ...]

If slice_order==’descending’ and interleaved==True, the assumed slice order is:

[N-1, N-3, N-5, ..., N-2, N-4, N-6]

Given that there exist other types of interleaved acquisitions depending on scanner settings and manufacturers, it is strongly recommended to input the slice_order as an array unless you are sure what you are doing.

slice_info : None or tuple, optional

None, or a tuple with slice axis as the first element and direction as the second, for instance (2, 1). If None, then guess the slice axis, and direction, as the closest to the z axis, as estimated from the affine.

estimate(loops=5, between_loops=None, align_runs=True, speedup=5, borders=(1, 1, 1), optimizer='ncg', xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)
resample(r=None, align_runs=True)

Return the resampled run number r as a 4d nipy-like image. Returns all runs as a list of images if r == None.

Image4d

class nipy.algorithms.registration.groupwise_registration.Image4d(data, affine, tr, tr_slices=None, start=0.0, slice_order='ascending', interleaved=None, slice_info=None)

Bases: object

Class to represent a sequence of 3d scans (possibly acquired on a slice-by-slice basis).

Object remains empty until the data array is actually loaded in memory.

Parameters :data : nd array or proxy (function that actually gets the array)

Methods

free_data
get_data
get_shape
scanner_time
z_to_slice
__init__(data, affine, tr, tr_slices=None, start=0.0, slice_order='ascending', interleaved=None, slice_info=None)

Configure fMRI acquisition time parameters.

free_data()
get_data()
get_shape()
scanner_time(zv, t)

tv = scanner_time(zv, t) zv, tv are grid coordinates; t is an actual time value.

z_to_slice(z)

Account for the fact that slices may be stored in reverse order wrt the scanner coordinate system convention (slice 0 == bottom of the head)

Realign4d

class nipy.algorithms.registration.groupwise_registration.Realign4d(images, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>)

Bases: object

Methods

estimate
resample
__init__(images, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>)
estimate(loops=5, between_loops=None, align_runs=True, speedup=5, borders=(1, 1, 1), optimizer='ncg', xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)
resample(r=None, align_runs=True)

Return the resampled run number r as a 4d nipy-like image. Returns all runs as a list of images if r == None.

Realign4dAlgorithm

class nipy.algorithms.registration.groupwise_registration.Realign4dAlgorithm(im4d, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, transforms=None, time_interp=True, subsampling=(1, 1, 1), borders=(1, 1, 1), optimizer='ncg', optimize_template=True, xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)

Bases: object

Methods

align_to_refscan
estimate_instant_motion
estimate_motion
init_instant_motion
resample
resample_full_data
set_fmin
set_transform
__init__(im4d, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, transforms=None, time_interp=True, subsampling=(1, 1, 1), borders=(1, 1, 1), optimizer='ncg', optimize_template=True, xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)
align_to_refscan()

The motion_estimate method aligns scans with an online template so that spatial transforms map some average head space to the scanner space. To conventionally redefine the head space as being aligned with some reference scan, we need to right compose each head_average-to-scanner transform with the refscan’s ‘to head_average’ transform.

estimate_instant_motion(t)

Estimate motion parameters at a particular time.

estimate_motion()

Optimize motion parameters for the whole sequence. All the time frames are initially resampled according to the current space/time transformation, the parameters of which are further optimized sequentially.

init_instant_motion(t)

Pre-compute and cache some constants (at fixed time) for repeated computations of the alignment energy.

The idea is to decompose the average temporal variance via:

V = (n-1)/n V* + (n-1)/n^2 (x-m*)^2

with x the considered volume at time t, and m* the mean of all resampled volumes but x. Only the second term is variable when

one volumes while the others are fixed. A similar decomposition is used for the global variance, so we end up with:

V/V0 = [nV* + (x-m*)^2] / [nV0* + (x-m0*)^2]

resample(t)

Resample a particular time frame on the (sub-sampled) working grid.

x,y,z,t are “head” grid coordinates X,Y,Z,T are “scanner” grid coordinates

resample_full_data()
set_fmin(optimizer, stepsize, **kwargs)

Return the minimization function

set_transform(t, pc)

Functions

nipy.algorithms.registration.groupwise_registration.adjust_subsampling(speedup, dims)
nipy.algorithms.registration.groupwise_registration.interp_slice_order(Z, slice_order)
nipy.algorithms.registration.groupwise_registration.make_grid(dims, subsampling=(1, 1, 1), borders=(0, 0, 0))
nipy.algorithms.registration.groupwise_registration.realign4d(runs, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, time_interp=True, align_runs=True, loops=5, between_loops=5, speedup=5, borders=(1, 1, 1), optimizer='ncg', xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)
Parameters :

runs : list of Image4d objects

Returns :

transforms : list

nested list of rigid transformations

transforms map an ‘ideal’ 4d grid (conventionally aligned with the :

first scan of the first run) to the ‘acquisition’ 4d grid for each :

run :

nipy.algorithms.registration.groupwise_registration.resample4d(im4d, transforms, time_interp=True)

Resample a 4D image according to the specified sequence of spatial transforms, using either 4D interpolation if time_interp is True and 3D interpolation otherwise.

nipy.algorithms.registration.groupwise_registration.scanner_coords(xyz, affine, from_world, to_world)
nipy.algorithms.registration.groupwise_registration.single_run_realign4d(im4d, affine_class=<class 'nipy.algorithms.registration.affine.Rigid'>, time_interp=True, loops=5, speedup=5, borders=(1, 1, 1), optimizer='ncg', xtol=1.0000000000000001e-05, ftol=1.0000000000000001e-05, gtol=1.0000000000000001e-05, stepsize=9.9999999999999995e-07, maxiter=64, maxfun=None, refscan=0)

Realign a single run in space and time.

Parameters :

im4d : Image4d instance

speedup : int or sequence

If a sequence, implement a multi-scale