Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

5.3.1. sammba.registration.anats_to_common

sammba.registration.anats_to_common(anat_filenames, write_dir, brain_volume, registration_kind='affine', use_rats_tool=True, nonlinear_levels=[1, 2, 3], nonlinear_minimal_patches=[75], nonlinear_weight_file=None, convergence=0.005, blur_radius_coarse=1.1, caching=False, verbose=1, unifize_kwargs=None, brain_masking_unifize_kwargs=None)

Create common template from native anatomical images and achieve their registration to it.

Parameters

anat_filenames : list of str

Paths to the anatomical images.

write_dir : str

Path to an existant directory to save output files to.

brain_volume : int

Volume of the brain in mm3 used for brain extraction. Typically 400 for mouse and 1800 for rat.

registration_kind : one of {‘rigid’, ‘affine’, ‘nonlinear’}, optional

The allowed transform kind.

use_rats_tool : bool, optional

If True, brain mask is computed using RATS Mathematical Morphology. Otherwise, a histogram-based brain segmentation is used.

nonlinear_levels : list of int, optional

Maximal levels for each nonlinear warping iteration. Passed iteratively to nipype.interfaces.afni.Qwarp

nonlinear_minimal_patches : list of int, optional

Minimal patches for the final nonlinear warps, passed to nipype.interfaces.afni.Qwarp

nonlinear_weight_file : str, optional

Path to a mask used to weight non-linear registration. Ideally should include not just the whole brain but also extend in all directions to include some amount of surrounding head tissue.

convergence : float, optional

Convergence limit, passed to nipype.interfaces.afni.Allineate

blur_radius_coarse : float, optional

Radius passed to nipype.interfaces.afni.Allineate for the “-twoblur” option

caching : bool, optional

If True, caching is used for all the registration steps.

verbose : int, optional

Verbosity level. Note that caching implies some verbosity in any case.

unifize_kwargs : dict, optional

Is passed to nipype.interfaces.afni.Unifize, to control bias correction of the template.

brain_masking_unifize_kwargs : dict, optional

Is passed to nipype.interfaces.afni.Unifize, to tune the seperate bias correction step done prior to brain masking.

Returns

data : sklearn.datasets.base.Bunch

Dictionary-like object, the interest attributes are :

• registeredlist of str.

  Paths to registered images. Note that they have undergone a bias correction step before.

• transformslist of str.

  Paths to the transforms from the raw images to the registered images.

Notes

nonlinear_weight_file: Without this weight mask, for non-linear registration a mask is generated by binarizing the mean of images that have been brain and affine-registered, then evenly dilating it to include some surrounding head tissue. The non-linear registration is then weighted to work only within this mask. This substantially improves performance by 1) reducing the number of voxels to analyse, and 2) avoiding other parts of the head where structures are highly variable and signal often poor. However, this automatically-generated mask is frequently sub-optimal, usually due to missing paraflocculi and inappropriate dilation.

Of course, it is impossible to know ahead of time where to weight the image before the brains/heads have been registered to each other. So in practice a first running of this script is done up until and including the affine stage (the default). The user should then manually use 3dmask_tool or some other software tool to create an intersect/frac/union mask of the _Unifized_for_brain_extraction_masked_resample_shr_affine_catenated files. These can then be dilated as needed to include some surrounding head tissue (which helps to better distinguish the brain-non-brain boundary). Missing regions can be added manually. This does not have to be done precisely, only roughly, and it is better to include too much tissue than too little. The procedure should then be rerun as non-linear, but using this weight mask. use_rats_tool: If use_rats_tool is turned on, RATS tool is used for brain extraction and has to be cited. For more information, see RATS