nipype.interfaces.mrtrix.tensors module

ConstrainedSphericalDeconvolution

Link to code

Bases: CommandLine

Wrapped executable: csdeconv.

Perform non-negativity constrained spherical deconvolution.

Note that this program makes use of implied symmetries in the diffusion profile. First, the fact the signal attenuation profile is real implies that it has conjugate symmetry, i.e. Y(l,-m) = Y(l,m)* (where * denotes the complex conjugate). Second, the diffusion profile should be antipodally symmetric (i.e. S(x) = S(-x)), implying that all odd l components should be zero. Therefore, this program only computes the even elements. Note that the spherical harmonics equations used here differ slightly from those conventionally used, in that the (-1)^m factor has been omitted. This should be taken into account in all subsequent calculations. Each volume in the output image corresponds to a different spherical harmonic component, according to the following convention:

  • [0] Y(0,0)

  • [1] Im {Y(2,2)}

  • [2] Im {Y(2,1)}

  • [3] Y(2,0)

  • [4] Re {Y(2,1)}

  • [5] Re {Y(2,2)}

  • [6] Im {Y(4,4)}

  • [7] Im {Y(4,3)}

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> csdeconv = mrt.ConstrainedSphericalDeconvolution()
>>> csdeconv.inputs.in_file = 'dwi.mif'
>>> csdeconv.inputs.encoding_file = 'encoding.txt'
>>> csdeconv.run()
Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Diffusion-weighted image. Maps to a command-line argument: %s (position: -3).

  • response_file (a pathlike object or string representing an existing file) – The diffusion-weighted signal response function for a single fibre population (see EstimateResponse). Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • debug (a boolean) – Display debugging messages. Maps to a command-line argument: -debug.

  • directions_file (a pathlike object or string representing an existing file) – A text file containing the [ el az ] pairs for the directions: Specify the directions over which to apply the non-negativity constraint (by default, the built-in 300 direction set is used). Maps to a command-line argument: -directions %s (position: -2).

  • encoding_file (a pathlike object or string representing an existing file) – Gradient encoding, supplied as a 4xN text file with each line is in the format [ X Y Z b ], where [ X Y Z ] describe the direction of the applied gradient, and b gives the b-value in units (1000 s/mm^2). See FSL2MRTrix. Maps to a command-line argument: -grad %s (position: 1).

  • 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: {})

  • filter_file (a pathlike object or string representing an existing file) – A text file containing the filtering coefficients for each even harmonic order.the linear frequency filtering parameters used for the initial linear spherical deconvolution step (default = [ 1 1 1 0 0 ]). Maps to a command-line argument: -filter %s (position: -2).

  • iterations (an integer) – The maximum number of iterations to perform for each voxel (default = 50). Maps to a command-line argument: -niter %s.

  • lambda_value (a float) – The regularisation parameter lambda that controls the strength of the constraint (default = 1.0). Maps to a command-line argument: -lambda %s.

  • mask_image (a pathlike object or string representing an existing file) – Only perform computation within the specified binary brain mask image. Maps to a command-line argument: -mask %s (position: 2).

  • maximum_harmonic_order (an integer) – Set the maximum harmonic order for the output series. By default, the program will use the highest possible lmax given the number of diffusion-weighted images. Maps to a command-line argument: -lmax %s.

  • normalise (a boolean) – Normalise the DW signal to the b=0 image. Maps to a command-line argument: -normalise (position: 3).

  • out_filename (a pathlike object or string representing a file) – Output filename. Maps to a command-line argument: %s (position: -1).

  • threshold_value (a float) – The threshold below which the amplitude of the FOD is assumed to be zero, expressed as a fraction of the mean value of the initial FOD (default = 0.1). Maps to a command-line argument: -threshold %s.

Outputs:

spherical_harmonics_image (a pathlike object or string representing an existing file) – Spherical harmonics image.

DWI2SphericalHarmonicsImage

Link to code

Bases: CommandLine

Wrapped executable: dwi2SH.

Convert base diffusion-weighted images to their spherical harmonic representation.

This program outputs the spherical harmonic decomposition for the set measured signal attenuations. The signal attenuations are calculated by identifying the b-zero images from the diffusion encoding supplied (i.e. those with zero as the b-value), and dividing the remaining signals by the mean b-zero signal intensity. The spherical harmonic decomposition is then calculated by least-squares linear fitting. Note that this program makes use of implied symmetries in the diffusion profile.

First, the fact the signal attenuation profile is real implies that it has conjugate symmetry, i.e. Y(l,-m) = Y(l,m)* (where * denotes the complex conjugate). Second, the diffusion profile should be antipodally symmetric (i.e. S(x) = S(-x)), implying that all odd l components should be zero. Therefore, this program only computes the even elements.

Note that the spherical harmonics equations used here differ slightly from those conventionally used, in that the (-1)^m factor has been omitted. This should be taken into account in all subsequent calculations.

Each volume in the output image corresponds to a different spherical harmonic component, according to the following convention:

  • [0] Y(0,0)

  • [1] Im {Y(2,2)}

  • [2] Im {Y(2,1)}

  • [3] Y(2,0)

  • [4] Re {Y(2,1)}

  • [5] Re {Y(2,2)}

  • [6] Im {Y(4,4)}

  • [7] Im {Y(4,3)}

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> dwi2SH = mrt.DWI2SphericalHarmonicsImage()
>>> dwi2SH.inputs.in_file = 'diffusion.nii'
>>> dwi2SH.inputs.encoding_file = 'encoding.txt'
>>> dwi2SH.run()
Mandatory Inputs:

  • encoding_file (a pathlike object or string representing an existing file) – Gradient encoding, supplied as a 4xN text file with each line is in the format [ X Y Z b ], where [ X Y Z ] describe the direction of the applied gradient, and b gives the b-value in units (1000 s/mm^2). See FSL2MRTrix. Maps to a command-line argument: -grad %s (position: 1).

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

Optional Inputs:

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

  • 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: {})

  • maximum_harmonic_order (a float) – Set the maximum harmonic order for the output series. By default, the program will use the highest possible lmax given the number of diffusion-weighted images. Maps to a command-line argument: -lmax %s.

  • normalise (a boolean) – Normalise the DW signal to the b=0 image. Maps to a command-line argument: -normalise (position: 3).

  • out_filename (a pathlike object or string representing a file) – Output filename. Maps to a command-line argument: %s (position: -1).

Outputs:

spherical_harmonics_image (a pathlike object or string representing an existing file) – Spherical harmonics image.

Directions2Amplitude

Link to code

Bases: CommandLine

Wrapped executable: dir2amp.

convert directions image to amplitudes

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> amplitudes = mrt.Directions2Amplitude()
>>> amplitudes.inputs.in_file = 'peak_directions.mif'
>>> amplitudes.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – The input directions image. Each volume corresponds to the x, y & z component of each direction vector in turn. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • display_debug (a boolean) – Display debugging messages. Maps to a command-line argument: -debug.

  • display_info (a boolean) – Display information messages. Maps to a command-line argument: -info.

  • 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: {})

  • num_peaks (an integer) – The number of peaks to extract (default is 3). Maps to a command-line argument: -num %s.

  • out_file (a pathlike object or string representing a file) – The output amplitudes image. Maps to a command-line argument: %s (position: -1).

  • peak_directions (a list of from 2 to 2 items which are a float) – Phi theta. the direction of a peak to estimate. The algorithm will attempt to find the same number of peaks as have been specified using this option phi: the azimuthal angle of the direction (in degrees). theta: the elevation angle of the direction (in degrees, from the vertical z-axis). Maps to a command-line argument: -direction %s.

  • peaks_image (a pathlike object or string representing an existing file) – The program will try to find the peaks that most closely match those in the image provided. Maps to a command-line argument: -peaks %s.

  • quiet_display (a boolean) – Do not display information messages or progress status. Maps to a command-line argument: -quiet.

Outputs:

out_file (a pathlike object or string representing an existing file) – Amplitudes image.

EstimateResponseForSH

Link to code

Bases: CommandLine

Wrapped executable: estimate_response.

Estimates the fibre response function for use in spherical deconvolution.

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> estresp = mrt.EstimateResponseForSH()
>>> estresp.inputs.in_file = 'dwi.mif'
>>> estresp.inputs.mask_image = 'dwi_WMProb.mif'
>>> estresp.inputs.encoding_file = 'encoding.txt'
>>> estresp.run()
Mandatory Inputs:

  • encoding_file (a pathlike object or string representing an existing file) – Gradient encoding, supplied as a 4xN text file with each line is in the format [ X Y Z b ], where [ X Y Z ] describe the direction of the applied gradient, and b gives the b-value in units (1000 s/mm^2). See FSL2MRTrix. Maps to a command-line argument: -grad %s (position: 1).

  • in_file (a pathlike object or string representing an existing file) – Diffusion-weighted images. Maps to a command-line argument: %s (position: -3).

  • mask_image (a pathlike object or string representing an existing file) – Only perform computation within the specified binary brain mask image. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • debug (a boolean) – Display debugging messages. Maps to a command-line argument: -debug.

  • 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: {})

  • maximum_harmonic_order (an integer) – Set the maximum harmonic order for the output series. By default, the program will use the highest possible lmax given the number of diffusion-weighted images. Maps to a command-line argument: -lmax %s.

  • normalise (a boolean) – Normalise the DW signal to the b=0 image. Maps to a command-line argument: -normalise.

  • out_filename (a pathlike object or string representing a file) – Output filename. Maps to a command-line argument: %s (position: -1).

  • quiet (a boolean) – Do not display information messages or progress status. Maps to a command-line argument: -quiet.

Outputs:

response (a pathlike object or string representing an existing file) – Spherical harmonics image.

FSL2MRTrix

Link to code

Bases: BaseInterface

Converts separate b-values and b-vectors from text files (FSL style) into a 4xN text file in which each line is in the format [ X Y Z b ], where [ X Y Z ] describe the direction of the applied gradient, and b gives the b-value in units (1000 s/mm^2).

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> fsl2mrtrix = mrt.FSL2MRTrix()
>>> fsl2mrtrix.inputs.bvec_file = 'bvecs'
>>> fsl2mrtrix.inputs.bval_file = 'bvals'
>>> fsl2mrtrix.inputs.invert_y = True
>>> fsl2mrtrix.run()
Mandatory Inputs:

  • bval_file (a pathlike object or string representing an existing file) – FSL b-values file (1xN text file).

  • bvec_file (a pathlike object or string representing an existing file) – FSL b-vectors file (3xN text file).

Optional Inputs:

  • invert_x (a boolean) – Inverts the b-vectors along the x-axis. (Nipype default value: False)

  • invert_y (a boolean) – Inverts the b-vectors along the y-axis. (Nipype default value: False)

  • invert_z (a boolean) – Inverts the b-vectors along the z-axis. (Nipype default value: False)

  • out_encoding_file (a pathlike object or string representing a file) – Output encoding filename.

Outputs:

encoding_file (a pathlike object or string representing a file) – The gradient encoding, supplied as a 4xN text file with each line is in the format [ X Y Z b ], where [ X Y Z ] describe the direction of the applied gradientand b gives the b-value in units (1000 s/mm^2).

FindShPeaks

Link to code

Bases: CommandLine

Wrapped executable: find_SH_peaks.

identify the orientations of the N largest peaks of a SH profile

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> shpeaks = mrt.FindShPeaks()
>>> shpeaks.inputs.in_file = 'csd.mif'
>>> shpeaks.inputs.directions_file = 'dirs.txt'
>>> shpeaks.inputs.num_peaks = 2
>>> shpeaks.run()
Mandatory Inputs:

  • directions_file (a pathlike object or string representing an existing file) – The set of directions to use as seeds for the peak finding. Maps to a command-line argument: %s (position: -2).

  • in_file (a pathlike object or string representing an existing file) – The input image of SH coefficients. Maps to a command-line argument: %s (position: -3).

Optional Inputs:

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

  • display_debug (a boolean) – Display debugging messages. Maps to a command-line argument: -debug.

  • display_info (a boolean) – Display information messages. Maps to a command-line argument: -info.

  • 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: {})

  • num_peaks (an integer) – The number of peaks to extract (default is 3). Maps to a command-line argument: -num %s.

  • out_file (a pathlike object or string representing a file) – The output image. Each volume corresponds to the x, y & z component of each peak direction vector in turn. Maps to a command-line argument: %s (position: -1).

  • peak_directions (a list of from 2 to 2 items which are a float) – Phi theta. the direction of a peak to estimate. The algorithm will attempt to find the same number of peaks as have been specified using this option phi: the azimuthal angle of the direction (in degrees). theta: the elevation angle of the direction (in degrees, from the vertical z-axis). Maps to a command-line argument: -direction %s.

  • peak_threshold (a float) – Only peak amplitudes greater than the threshold will be considered. Maps to a command-line argument: -threshold %s.

  • peaks_image (a pathlike object or string representing an existing file) – The program will try to find the peaks that most closely match those in the image provided. Maps to a command-line argument: -peaks %s.

  • quiet_display (a boolean) – Do not display information messages or progress status. Maps to a command-line argument: -quiet.

Outputs:

out_file (a pathlike object or string representing an existing file) – Peak directions image.

GenerateDirections

Link to code

Bases: CommandLine

Wrapped executable: gendir.

generate a set of directions evenly distributed over a hemisphere.

Example

>>> import nipype.interfaces.mrtrix as mrt
>>> gendir = mrt.GenerateDirections()
>>> gendir.inputs.num_dirs = 300
>>> gendir.run()
Mandatory Inputs:

num_dirs (an integer) – The number of directions to generate. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • display_debug (a boolean) – Display debugging messages. Maps to a command-line argument: -debug.

  • display_info (a boolean) – Display information messages. Maps to a command-line argument: -info.

  • 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: {})

  • niter (an integer) – Specify the maximum number of iterations to perform. Maps to a command-line argument: -niter %s.

  • out_file (a pathlike object or string representing a file) – The text file to write the directions to, as [ az el ] pairs. Maps to a command-line argument: %s (position: -1).

  • power (a float) – Specify exponent to use for repulsion power law. Maps to a command-line argument: -power %s.

  • quiet_display (a boolean) – Do not display information messages or progress status. Maps to a command-line argument: -quiet.

Outputs:

out_file (a pathlike object or string representing an existing file) – Directions file.

nipype.interfaces.mrtrix.tensors.concat_files(bvec_file, bval_file, invert_x, invert_y, invert_z)