nipype.interfaces.mrtrix3.tracking module

Tractography

Link to code

Bases: MRTrix3Base

Wrapped executable: tckgen.

Performs streamlines tractography after selecting the appropriate algorithm.

References

[FACT]

Mori, S.; Crain, B. J.; Chacko, V. P. & van Zijl, P. C. M. Three-dimensional tracking of axonal projections in the brain by magnetic resonance imaging. Annals of Neurology, 1999, 45, 265-269

[iFOD1]

Tournier, J.-D.; Calamante, F. & Connelly, A. MRtrix: Diffusion tractography in crossing fiber regions. Int. J. Imaging Syst. Technol., 2012, 22, 53-66

[iFOD2]

Tournier, J.-D.; Calamante, F. & Connelly, A. Improved probabilistic streamlines tractography by 2nd order integration over fibre orientation distributions. Proceedings of the International Society for Magnetic Resonance in Medicine, 2010, 1670

[Nulldist]

Morris, D. M.; Embleton, K. V. & Parker, G. J. Probabilistic fibre tracking: Differentiation of connections from chance events. NeuroImage, 2008, 42, 1329-1339

[Tensor_Det]

Basser, P. J.; Pajevic, S.; Pierpaoli, C.; Duda, J. and Aldroubi, A. In vivo fiber tractography using DT-MRI data. Magnetic Resonance in Medicine, 2000, 44, 625-632

[Tensor_Prob]

Jones, D. Tractography Gone Wild: Probabilistic Fibre Tracking Using the Wild Bootstrap With Diffusion Tensor MRI. IEEE Transactions on Medical Imaging, 2008, 27, 1268-1274

Example

>>> import nipype.interfaces.mrtrix3 as mrt
>>> tk = mrt.Tractography()
>>> tk.inputs.in_file = 'fods.mif'
>>> tk.inputs.roi_mask = 'mask.nii.gz'
>>> tk.inputs.seed_sphere = (80, 100, 70, 10)
>>> tk.cmdline                               
'tckgen -algorithm iFOD2 -samples 4 -output_seeds out_seeds.nii.gz -mask mask.nii.gz -seed_sphere 80.000000,100.000000,70.000000,10.000000 fods.mif tracked.tck'
>>> tk.run()
Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Input file to be processed. Maps to a command-line argument: %s (position: -2).

  • out_file (a pathlike object or string representing a file) – Output file containing tracks. Maps to a command-line argument: %s (position: -1). (Nipype default value: tracked.tck)

Optional Inputs:

  • act_file (a pathlike object or string representing an existing file) – Use the Anatomically-Constrained Tractography framework during tracking; provided image must be in the 5TT (five - tissue - type) format. Maps to a command-line argument: -act %s.

  • algorithm (‘iFOD2’ or ‘FACT’ or ‘iFOD1’ or ‘Nulldist’ or ‘SD_Stream’ or ‘Tensor_Det’ or ‘Tensor_Prob’) – Tractography algorithm to be used – References:[FACT], [iFOD1], [iFOD2], [Nulldist], [Tensor_Det], [Tensor_Prob]. Maps to a command-line argument: -algorithm %s. (Nipype default value: iFOD2)

  • angle (a float) – Set the maximum angle between successive steps (default is 90deg x stepsize / voxelsize). Maps to a command-line argument: -angle %f.

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • backtrack (a boolean) – Allow tracks to be truncated. Maps to a command-line argument: -backtrack.

  • bval_scale (‘yes’ or ‘no’) – Specifies whether the b - values should be scaled by the square of the corresponding DW gradient norm, as often required for multishell or DSI DW acquisition schemes. The default action can also be set in the MRtrix config file, under the BValueScaling entry. Valid choices are yes / no, true / false, 0 / 1 (default: true). Maps to a command-line argument: -bvalue_scaling %s.

  • crop_at_gmwmi (a boolean) – Crop streamline endpoints more precisely as they cross the GM-WM interface. Maps to a command-line argument: -crop_at_gmwmi.

  • cutoff (a float) – Set the FA or FOD amplitude cutoff for terminating tracks (default is 0.1). Maps to a command-line argument: -cutoff %f.

  • cutoff_init (a float) – Set the minimum FA or FOD amplitude for initiating tracks (default is the same as the normal cutoff). Maps to a command-line argument: -initcutoff %f.

  • downsample (a float) – Downsample the generated streamlines to reduce output file size. Maps to a command-line argument: -downsample %f.

  • environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

  • grad_file (a pathlike object or string representing an existing file) – Dw gradient scheme (MRTrix format). Maps to a command-line argument: -grad %s. Mutually exclusive with inputs: grad_fsl.

  • grad_fsl (a tuple of the form: (a pathlike object or string representing an existing file, a pathlike object or string representing an existing file)) – (bvecs, bvals) dw gradient scheme (FSL format). Maps to a command-line argument: -fslgrad %s %s. Mutually exclusive with inputs: grad_file.

  • in_bval (a pathlike object or string representing an existing file) – Bvals file in FSL format.

  • in_bvec (a pathlike object or string representing an existing file) – Bvecs file in FSL format. Maps to a command-line argument: -fslgrad %s %s.

  • init_dir (a tuple of the form: (a float, a float, a float)) – Specify an initial direction for the tracking (this should be supplied as a vector of 3 comma-separated values. Maps to a command-line argument: -initdirection %f,%f,%f.

  • max_length (a float) – Set the maximum length of any track in mm (default is 100 x voxelsize). Maps to a command-line argument: -maxlength %f.

  • max_seed_attempts (an integer) – Set the maximum number of times that the tracking algorithm should attempt to find an appropriate tracking direction from a given seed point. Maps to a command-line argument: -max_seed_attempts %d.

  • max_tracks (an integer) – Set the maximum number of tracks to generate. The program will not generate more tracks than this number, even if the desired number of tracks hasn’t yet been reached (default is 100 x number). Maps to a command-line argument: -maxnum %d.

  • min_length (a float) – Set the minimum length of any track in mm (default is 5 x voxelsize). Maps to a command-line argument: -minlength %f.

  • n_samples (an integer) – Set the number of FOD samples to take per step for the 2nd order (iFOD2) method. Maps to a command-line argument: -samples %d. (Nipype default value: 4)

  • n_tracks (an integer) – Set the desired number of tracks. The program will continue to generate tracks until this number of tracks have been selected and written to the output file. Maps to a command-line argument: -number %d.

  • n_trials (an integer) – Set the maximum number of sampling trials at each point (only used for probabilistic tracking). Maps to a command-line argument: -trials %d.

  • noprecompt (a boolean) – Do NOT pre-compute legendre polynomial values. Warning: this will slow down the algorithm by a factor of approximately 4. Maps to a command-line argument: -noprecomputed.

  • nthreads (an integer) – Number of threads. if zero, the number of available cpus will be used. Maps to a command-line argument: -nthreads %d.

  • out_bval (a pathlike object or string representing a file) – Export bval file in FSL format.

  • out_bvec (a pathlike object or string representing a file) – Export bvec file in FSL format. Maps to a command-line argument: -export_grad_fsl %s %s.

  • out_seeds (a pathlike object or string representing a file) – Output the seed location of all successful streamlines to a file. Maps to a command-line argument: -output_seeds %s. (Nipype default value: out_seeds.nii.gz)

  • power (an integer) – Raise the FOD to the power specified (default is 1/nsamples). Maps to a command-line argument: -power %d.

  • roi_excl (a pathlike object or string representing an existing file or a tuple of the form: (a float, a float, a float, a float)) – Specify an exclusion region of interest, streamlines that enter ANY exclude region will be discarded. Maps to a command-line argument: -exclude %s.

  • roi_incl (a pathlike object or string representing an existing file or a tuple of the form: (a float, a float, a float, a float)) – Specify an inclusion region of interest, streamlines must traverse ALL inclusion regions to be accepted. Maps to a command-line argument: -include %s.

  • roi_mask (a pathlike object or string representing an existing file or a tuple of the form: (a float, a float, a float, a float)) – Specify a masking region of interest. If defined,streamlines exiting the mask will be truncated. Maps to a command-line argument: -mask %s.

  • seed_dynamic (a pathlike object or string representing an existing file) – Determine seed points dynamically using the SIFT model (must not provide any other seeding mechanism). Note that while this seeding mechanism improves the distribution of reconstructed streamlines density, it should NOT be used as a substitute for the SIFT method itself. Maps to a command-line argument: -seed_dynamic %s.

  • seed_gmwmi (a pathlike object or string representing an existing file) – Seed from the grey matter - white matter interface (only valid if using ACT framework). Maps to a command-line argument: -seed_gmwmi %s. Requires inputs: act_file.

  • seed_grid_voxel (a tuple of the form: (a pathlike object or string representing an existing file, an integer)) – Seed a fixed number of streamlines per voxel in a mask image; place seeds on a 3D mesh grid (grid_size argument is per axis; so a grid_size of 3 results in 27 seeds per voxel). Maps to a command-line argument: -seed_grid_per_voxel %s %d. Mutually exclusive with inputs: seed_image, seed_rnd_voxel.

  • seed_image (a pathlike object or string representing an existing file) – Seed streamlines entirely at random within mask. Maps to a command-line argument: -seed_image %s.

  • seed_rejection (a pathlike object or string representing an existing file) – Seed from an image using rejection sampling (higher values = more probable to seed from. Maps to a command-line argument: -seed_rejection %s.

  • seed_rnd_voxel (a tuple of the form: (a pathlike object or string representing an existing file, an integer)) – Seed a fixed number of streamlines per voxel in a mask image; random placement of seeds in each voxel. Maps to a command-line argument: -seed_random_per_voxel %s %d. Mutually exclusive with inputs: seed_image, seed_grid_voxel.

  • seed_sphere (a tuple of the form: (a float, a float, a float, a float)) – Spherical seed. Maps to a command-line argument: -seed_sphere %f,%f,%f,%f.

  • select (an integer) – Set the desired number of tracks. The program will continue to generate tracks until this number of tracks have been selected and written to the output file. Maps to a command-line argument: -select %d.

  • sph_trait (a tuple of the form: (a float, a float, a float, a float)) – Maps to a command-line argument: %f,%f,%f,%f.

  • step_size (a float) – Set the step size of the algorithm in mm (default is 0.1 x voxelsize; for iFOD2: 0.5 x voxelsize). Maps to a command-line argument: -step %f.

  • stop (a boolean) – Stop propagating a streamline once it has traversed all include regions. Maps to a command-line argument: -stop.

  • unidirectional (a boolean) – Track from the seed point in one direction only (default is to track in both directions). Maps to a command-line argument: -unidirectional.

  • use_rk4 (a boolean) – Use 4th-order Runge-Kutta integration (slower, but eliminates curvature overshoot in 1st-order deterministic methods). Maps to a command-line argument: -rk4.

Outputs:

  • out_file (a pathlike object or string representing an existing file) – The output filtered tracks.

  • out_seeds (a pathlike object or string representing a file) – Output the seed location of all successful streamlines to a file.