.. AUTO-GENERATED FILE -- DO NOT EDIT!

interfaces.mrtrix3.tracking
===========================


.. _nipype.interfaces.mrtrix3.tracking.Tractography:


.. index:: Tractography

Tractography
------------

`Link to code <file:///build/nipype-1.1.8/nipype/interfaces/mrtrix3/tracking.py#L231>`__

Wraps the executable command ``tckgen``.

Performs streamlines tractography after selecting the appropriate
algorithm.

.. [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                               # doctest: +ELLIPSIS
'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()                                 # doctest: +SKIP

Inputs::

        [Mandatory]
        in_file: (an existing file name)
                input file to be processed
                argument: ``%s``, position: -2
        out_file: (a file name, nipype default value: tracked.tck)
                output file containing tracks
                argument: ``%s``, position: -1

        [Optional]
        cutoff: (a float)
                set the FA or FOD amplitude cutoff for terminating tracks (default
                is 0.1)
                argument: ``-cutoff %f``
        n_tracks: (an integer (int or long))
                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
                argument: ``-number %d``
        backtrack: (a boolean)
                allow tracks to be truncated
                argument: ``-backtrack``
        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
                argument: ``-initdirection %f,%f,%f``
        seed_grid_voxel: (a tuple of the form: (an existing file name, an
                  integer (int or long)))
                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)
                argument: ``-seed_grid_per_voxel %s %d``
                mutually_exclusive: seed_image, seed_rnd_voxel
        seed_dynamic: (an existing file name)
                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.
                argument: ``-seed_dynamic %s``
        use_rk4: (a boolean)
                use 4th-order Runge-Kutta integration (slower, but eliminates
                curvature overshoot in 1st-order deterministic methods)
                argument: ``-rk4``
        select: (an integer (int or long))
                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
                argument: ``-select %d``
        nthreads: (an integer (int or long))
                number of threads. if zero, the number of available cpus will be
                used
                argument: ``-nthreads %d``
        angle: (a float)
                set the maximum angle between successive steps (default is 90deg x
                stepsize / voxelsize)
                argument: ``-angle %f``
        n_trials: (an integer (int or long))
                set the maximum number of sampling trials at each point (only used
                for probabilistic tracking)
                argument: ``-trials %d``
        cutoff_init: (a float)
                set the minimum FA or FOD amplitude for initiating tracks (default
                is the same as the normal cutoff)
                argument: ``-initcutoff %f``
        downsample: (a float)
                downsample the generated streamlines to reduce output file size
                argument: ``-downsample %f``
        out_seeds: (a file name, nipype default value: out_seeds.nii.gz)
                output the seed location of all successful streamlines to a file
                argument: ``-output_seeds %s``
        max_tracks: (an integer (int or long))
                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)
                argument: ``-maxnum %d``
        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)
                argument: ``-step %f``
        n_samples: (an integer (int or long), nipype default value: 4)
                set the number of FOD samples to take per step for the 2nd order
                (iFOD2) method
                argument: ``-samples %d``
        in_bval: (an existing file name)
                bvals file in FSL format
        environ: (a dictionary with keys which are a newbytes or None or a
                  newstr or None and with values which are a newbytes or None or a
                  newstr or None, nipype default value: {})
                Environment variables
        roi_excl: (an existing file name 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
                argument: ``-exclude %s``
        sph_trait: (a tuple of the form: (a float, a float, a float, a
                  float))
                argument: ``%f,%f,%f,%f``
        power: (an integer (int or long))
                raise the FOD to the power specified (default is 1/nsamples)
                argument: ``-power %d``
        min_length: (a float)
                set the minimum length of any track in mm (default is 5 x voxelsize)
                argument: ``-minlength %f``
        grad_file: (an existing file name)
                dw gradient scheme (MRTrix format
                argument: ``-grad %s``
        seed_rejection: (an existing file name)
                seed from an image using rejection sampling (higher values = more
                probable to seed from
                argument: ``-seed_rejection %s``
        grad_fsl: (a tuple of the form: (an existing file name, an existing
                  file name))
                (bvecs, bvals) dw gradient scheme (FSL format
                argument: ``-fslgrad %s %s``
        args: (a unicode string)
                Additional parameters to the command
                argument: ``%s``
        stop: (a boolean)
                stop propagating a streamline once it has traversed all include
                regions
                argument: ``-stop``
        seed_sphere: (a tuple of the form: (a float, a float, a float, a
                  float))
                spherical seed
                argument: ``-seed_sphere %f,%f,%f,%f``
        crop_at_gmwmi: (a boolean)
                crop streamline endpoints more precisely as they cross the GM-WM
                interface
                argument: ``-crop_at_gmwmi``
        roi_incl: (an existing file name 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
                argument: ``-include %s``
        bval_scale: (u'yes' or u'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).
                argument: ``-bvalue_scaling %s``
        max_length: (a float)
                set the maximum length of any track in mm (default is 100 x
                voxelsize)
                argument: ``-maxlength %f``
        noprecompt: (a boolean)
                do NOT pre-compute legendre polynomial values. Warning: this will
                slow down the algorithm by a factor of approximately 4
                argument: ``-noprecomputed``
        max_seed_attempts: (an integer (int or long))
                set the maximum number of times that the tracking algorithm should
                attempt to find an appropriate tracking direction from a given seed
                point
                argument: ``-max_seed_attempts %d``
        in_bvec: (an existing file name)
                bvecs file in FSL format
                argument: ``-fslgrad %s %s``
        algorithm: (u'iFOD2' or u'FACT' or u'iFOD1' or u'Nulldist' or
                  u'SD_Stream' or u'Tensor_Det' or u'Tensor_Prob', nipype default
                  value: iFOD2)
                tractography algorithm to be used
                argument: ``-algorithm %s``
        act_file: (an existing file name)
                use the Anatomically-Constrained Tractography framework during
                tracking; provided image must be in the 5TT (five - tissue - type)
                format
                argument: ``-act %s``
        unidirectional: (a boolean)
                track from the seed point in one direction only (default is to track
                in both directions)
                argument: ``-unidirectional``
        seed_gmwmi: (an existing file name)
                seed from the grey matter - white matter interface (only valid if
                using ACT framework)
                argument: ``-seed_gmwmi %s``
                requires: act_file
        seed_image: (an existing file name)
                seed streamlines entirely at random within mask
                argument: ``-seed_image %s``
        roi_mask: (an existing file name 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
                argument: ``-mask %s``
        seed_rnd_voxel: (a tuple of the form: (an existing file name, an
                  integer (int or long)))
                seed a fixed number of streamlines per voxel in a mask image; random
                placement of seeds in each voxel
                argument: ``-seed_random_per_voxel %s %d``
                mutually_exclusive: seed_image, seed_grid_voxel

Outputs::

        out_seeds: (a file name)
                output the seed location of all successful streamlines to a file
        out_file: (an existing file name)
                the output filtered tracks
