qsirecon.workflows.recon package

Reconstruction pipeline nodes

This module contains the functions that build the nipype workflows from the workflow specs.

Converting between file formats

qsirecon.workflows.recon.converters.init_mif_to_fibgz_wf(inputs_dict, name='mif_to_fibgz', qsirecon_suffix='', params={})

Converts a MRTrix mif file to DSI Studio fib file.

This workflow uses sh2amp to sample the FODs on the standard DSI Studio ODF direction set. These are then loaded and converted to the fib MATLAB v4 format and peak directions are detected using Dipy.

Inputs

mif_file

MRTrix format mif file containing sh coefficients representing FODs.

Outputs

fibgz

DSI Studio fib file containing the FODs from the input mif_file.

qsirecon.workflows.recon.converters.init_fibgz_to_mif_wf(name='fibgz_to_mif', qsirecon_suffix='', params={})

Needs Documentation

Dipy Reconstruction workflows

qsirecon.workflows.recon.dipy.init_dipy_brainsuite_shore_recon_wf(inputs_dict, name='dipy_3dshore_recon', qsirecon_suffix='', params={})

Reconstruct EAPs, ODFs, using 3dSHORE (brainsuite-style basis set).

Inputs

qsirecon outputs

Outputs

shore_coeffs

3dSHORE coefficients

rtop

Voxelwise Return-to-origin probability.

rtap

Voxelwise Return-to-axis probability.

rtpp

Voxelwise Return-to-plane probability.

Params

write_fibgz: bool

True writes out a DSI Studio fib file

write_mif: bool

True writes out a MRTrix mif file with sh coefficients

convert_to_multishell: str

either “HCP”, “ABCD”, “lifespan” will resample the data with this scheme

radial_order: int

Radial order for spherical harmonics (even)

zeta: float

Zeta parameter for basis set.

tau:float

Diffusion parameter (default= 4 * np.pi**2)

regularization

“L2” or “L1”. Default is “L2”

lambdaN

LambdaN parameter for L2 regularization. (default=1e-8)

lambdaL

LambdaL parameter for L2 regularization. (default=1e-8)

regularization_weighting: int or “CV”

L1 regualrization weighting. Default “CV” (use cross-validation). Can specify a static value to use in all voxels.

l1_positive_constraint: bool

Use positivity constraint.

l1_maxiter

Maximum number of iterations for L1 optization. (Default=1000)

l1_alpha

Alpha parameter for L1 optimization. (default=1.0)

pos_grid: int

Grid points for estimating EAP(default=11)

pos_radius

Radius for EAP estimation (default=20e-03)

qsirecon.workflows.recon.dipy.init_dipy_mapmri_recon_wf(inputs_dict, name='dipy_mapmri_recon', qsirecon_suffix='', params={})

Reconstruct EAPs, ODFs, using 3dSHORE (brainsuite-style basis set).

Inputs

qsirecon outputs

Outputs

shore_coeffs

3dSHORE coefficients

rtop

Voxelwise Return-to-origin probability.

rtap

Voxelwise Return-to-axis probability.

rtpp

Voxelwise Return-to-plane probability.

msd

Voxelwise MSD

qiv

q-space inverse variance

lapnorm

Voxelwise norm of the Laplacian

Params

write_fibgz: bool

True writes out a DSI Studio fib file

write_mif: bool

True writes out a MRTrix mif file with sh coefficients

radial_order: int

An even integer that represent the order of the basis

laplacian_regularization: bool

Regularize using the Laplacian of the MAP-MRI basis.

laplacian_weighting: str or scalar

The string ‘GCV’ makes it use generalized cross-validation to find the regularization weight. A scalar sets the regularization weight to that value and an array will make it selected the optimal weight from the values in the array.

positivity_constraint: bool

Constrain the propagator to be positive.

pos_grid: int

Grid points for estimating EAP(default=15)

pos_radius

Radius for EAP estimation (default=20e-03) or “adaptive”

anisotropic_scalingbool,

If True, uses the standard anisotropic MAP-MRI basis. If False, uses the isotropic MAP-MRI basis (equal to 3D-SHORE).

eigenvalue_thresholdfloat,

Sets the minimum of the tensor eigenvalues in order to avoid stability problem.

bval_thresholdfloat,

Sets the b-value threshold to be used in the scale factor estimation. In order for the estimated non-Gaussianity to have meaning this value should set to a lower value (b<2000 s/mm^2) such that the scale factors are estimated on signal points that reasonably represent the spins at Gaussian diffusion.

dti_scale_estimationbool,

Whether or not DTI fitting is used to estimate the isotropic scale factor for isotropic MAP-MRI. When set to False the algorithm presets the isotropic tissue diffusivity to static_diffusivity. This vastly increases fitting speed but at the cost of slightly reduced fitting quality. Can still be used in combination with regularization and constraints.

static_diffusivityfloat,

the tissue diffusivity that is used when dti_scale_estimation is set to False. The default is that of typical white matter D=0.7e-3 _[5].

cvxpy_solverstr, optional

cvxpy solver name. Optionally optimize the positivity constraint with a particular cvxpy solver. See http://www.cvxpy.org/ for details. Default: None (cvxpy chooses its own solver)

qsirecon.workflows.recon.dipy.init_dipy_dki_recon_wf(inputs_dict, name='dipy_dki_recon', qsirecon_suffix='', params={})

Fit DKI.

This workflow corresponds to the “DKI_reconstruction” pipeline action.

Parameters:

• inputs_dict (dict) – Dictionary containing the input node fields.

• name (str) – Name of the workflow.

• qsirecon_suffix (str) – Suffix for the qsirecon outputs.

• params (dict) – Dictionary containing the parameters for the workflow. Parameters that can be passed to the workflow are:

  • wmtibool

    Whether to compute microstructural metrics.

  • write_fibgzbool

    Whether to write out a DSI Studio fib file.

  • write_mifbool

    Whether to write out a MRTrix mif file with sh coefficients.

  • radial_orderint

    An even integer that represents the order of the basis.

Outputs:

• tensor (str) – Path to the tensor file.

• fa (str) – Path to the FA file.

• md (str) – Path to the MD file.

• rd (str) – Path to the RD file.

• ad (str) – Path to the AD file.

• color_fa (str) – Path to the color FA file.

• kfa (str) – Path to the KFA file.

• mk (str) – Path to the MK file.

• ak (str) – Path to the AK file.

• rk (str) – Path to the RK file.

• mkt (str) – Path to the MKT file.

• awf (str) – Only if wmti is True

• rde (str) – Only if wmti is True

• tortuosity (str) – Only if wmti is True

• trace (str) – Only if wmti is True

• recon_scalars (str) – Path to the recon_scalars file.

See also

qsirecon.interfaces.dipy.KurtosisReconstruction, qsirecon.interfaces.dipy.KurtosisReconstructionMicrostructure, qsirecon.interfaces.dipy.KurtosisReconstructionMSDKI, qsirecon.interfaces.recon_scalars.DIPYDKIReconScalars

DSI Studio workflows

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_recon_wf(inputs_dict, name='dsi_studio_recon', qsirecon_suffix='', params={})

Reconstructs diffusion data using DSI Studio.

This workflow creates a .src.gz file from the input dwi, bvals and bvecs, then reconstructs ODFs using GQI.

Inputs

Default qsirecon inputs

Outputs

fibgz

A DSI Studio fib file containing GQI ODFs, peaks and scalar values.

Params

ratio_of_mean_diffusion_distance: float

Default 1.25. Distance to sample EAP at.

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_connectivity_wf(inputs_dict, name='dsi_studio_connectivity', params={}, qsirecon_suffix='')

Calculate streamline-based connectivity matrices using DSI Studio.

DSI Studio has a deterministic tractography algorithm that can be used to estimate pairwise regional connectivity. It calculates multiple connectivity measures.

Inputs

fibgz

A DSI Studio fib file produced by DSI Studio reconstruction.

trk_file

a DSI Studio trk.gz file

Outputs

matfile

A MATLAB-format file with numerous connectivity matrices for each atlas.

Params

fiber_count

number of streamlines to generate. Cannot also specify seed_count

seed_count

Number of seeds to track from. Does not guarantee a fixed number of streamlines and cannot be used with the fiber_count option.

method

0: streamline (Euler) 4: Runge Kutta

seed_plan

0: = traits.Enum((0, 1), argstr=”–seed_plan=%d”)

initial_dir

Seeds begin oriented as 0: the primary orientation of the ODF 1: a random orientation or 2: all orientations

connectivity_type

“pass” to count streamlines passing through a region. “end” to force streamlines to terminate in regions they count as connecting.

connectivity_value

“count”, “ncount”, “fa” used to quantify connection strength.

random_seed

Setting to True generates truly random (not-reproducible) seeding.

fa_threshold

If not specified, will use the DSI Studio Otsu threshold. Otherwise specigies the minimum qa value per fixed to be used for tracking.

step_size

Streamline propagation step size in millimeters.

turning_angle

Maximum turning angle in degrees for steamline propagation.

smoothing

DSI Studio smoothing factor

min_length

Minimum streamline length in millimeters.

max_length

Maximum streamline length in millimeters.

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_export_wf(inputs_dict, name='dsi_studio_export', params={}, qsirecon_suffix='')

Export scalar maps from a DSI Studio fib file into NIfTI files with correct headers.

This workflow exports gfa, fa0, fa1, fa2 and iso.

Inputs

fibgz

A DSI Studio fib file

Outputs

gfa

NIfTI file containing generalized fractional anisotropy (GFA).

fa0

Quantitative Anisotropy for the largest fixel in each voxel.

fa1

Quantitative Anisotropy for the second-largest fixel in each voxel.

fa2

Quantitative Anisotropy for the third-largest fixel in each voxel.

iso

Isotropic component of the ODF in each voxel.

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_autotrack_wf(inputs_dict, params={}, qsirecon_suffix='', name='dsi_studio_autotrack_wf')

Run DSI Studio’s AutoTrack method to produce bundles and bundle stats.

Inputs

fibgz

A DSI Studio fib file produced by DSI Studio reconstruction.

Outputs

tck_files

MRtrix3 format tck files for each bundle

bundle_names

Names that describe which bundles are present in tck_files

Params:

track_id: str

specify the id number or the name of the bundle. The id can be found in /atlas/ICBM152/HCP1065.tt.gz.txt . This text file is included in DSI Studio package (For Mac, right-click on dsi_studio_64.app to find content). You can specify partial name of the bundle:

example: for tracking left and right arcuate fasciculus, assign –track_id=0,1 or –track_id=arcuate (DSI Studio will find bundles with names containing “arcuate”, case insensitive)

example: for tracking left and right arcuate and cingulum, assign -track_id=0,1,2,3 or -track_id=arcuate,cingulum

track_voxel_ratio: float

the track-voxel ratio for the total number of streamline count. A larger value gives better mapping with the expense of computation time. (default: 2.0)

tolerance: str

the tolerance for the bundle recognition. The unit is in mm. Multiple values can be assigned using comma separator. A larger value may include larger track variation but also subject to more false results. (default: “22,26,30”)

yield_rate: float

This rate will be used to terminate tracking early if DSI Studio finds that the fiber tracking is not generating results. (default: 0.00001)

smoothing: float

Smoothing serves like a “momentum”. For example, if smoothing is 0, the propagation direction is independent of the previous incoming direction. If the smoothing is 0.5, each moving direction remains 50% of the “momentum”, which is the previous propagation vector. This function makes the tracks appear smoother. In implementation detail, there is a weighting sum on every two consecutive moving directions. For smoothing value 0.2, each subsequent direction has 0.2 weightings contributed from the previous moving direction and 0.8 contributed from the income direction. To disable smoothing set its value to 0. Assign 1.0 to do a random selection of the value from 0% to 95%.

otsu_threshold: float

The ratio of otsu threshold to derive default anisotropy threshold.

model_name: str

The name of the model used for ODFs (default “gqi”)

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_connectivity_wf(inputs_dict, name='dsi_studio_connectivity', params={}, qsirecon_suffix='')

Calculate streamline-based connectivity matrices using DSI Studio.

DSI Studio has a deterministic tractography algorithm that can be used to estimate pairwise regional connectivity. It calculates multiple connectivity measures.

Inputs

fibgz

A DSI Studio fib file produced by DSI Studio reconstruction.

trk_file

a DSI Studio trk.gz file

Outputs

matfile

A MATLAB-format file with numerous connectivity matrices for each atlas.

Params

fiber_count

number of streamlines to generate. Cannot also specify seed_count

seed_count

Number of seeds to track from. Does not guarantee a fixed number of streamlines and cannot be used with the fiber_count option.

method

0: streamline (Euler) 4: Runge Kutta

seed_plan

0: = traits.Enum((0, 1), argstr=”–seed_plan=%d”)

initial_dir

Seeds begin oriented as 0: the primary orientation of the ODF 1: a random orientation or 2: all orientations

connectivity_type

“pass” to count streamlines passing through a region. “end” to force streamlines to terminate in regions they count as connecting.

connectivity_value

“count”, “ncount”, “fa” used to quantify connection strength.

random_seed

Setting to True generates truly random (not-reproducible) seeding.

fa_threshold

If not specified, will use the DSI Studio Otsu threshold. Otherwise specigies the minimum qa value per fixed to be used for tracking.

step_size

Streamline propagation step size in millimeters.

turning_angle

Maximum turning angle in degrees for steamline propagation.

smoothing

DSI Studio smoothing factor

min_length

Minimum streamline length in millimeters.

max_length

Maximum streamline length in millimeters.

qsirecon.workflows.recon.dsi_studio.init_dsi_studio_export_wf(inputs_dict, name='dsi_studio_export', params={}, qsirecon_suffix='')

Export scalar maps from a DSI Studio fib file into NIfTI files with correct headers.

This workflow exports gfa, fa0, fa1, fa2 and iso.

Inputs

fibgz

A DSI Studio fib file

Outputs

gfa

NIfTI file containing generalized fractional anisotropy (GFA).

fa0

Quantitative Anisotropy for the largest fixel in each voxel.

fa1

Quantitative Anisotropy for the second-largest fixel in each voxel.

fa2

Quantitative Anisotropy for the third-largest fixel in each voxel.

iso

Isotropic component of the ODF in each voxel.

MRTrix workflows

Note that in nipype interfaces the threading-controlling attribute is nthreads, not the typical num_threads expected by nipype. To keep threading consistent between nipype and mrtrix, the nthreads attribute needs to be set in the interface and the n_procs attribute needs to be set on the Node.

qsirecon.workflows.recon.mrtrix.init_mrtrix_csd_recon_wf(inputs_dict, name='mrtrix_recon', qsirecon_suffix='', params={})

Create FOD images for WM, GM and CSF.

This workflow uses mrtrix tools to run csd on multishell data. At the end, mtnormalise is run.

Parameters:

params (dict) – Parameters for the workflow. The following keys are supported: - response : dict. Parameters for estimating the response function.

The following keys are supported:

• algorithm : str. The algorithm to use for response function estimation. Supported values are “dhollander” and “msmt_5tt”.

• method_5tt : str. The method to use for 5tt segmentation. Supported values are “hsvs”.

• fod : dict. Parameters for dwi2fod. The following keys are supported:

  • algorithm : str. The algorithm to use for FOD estimation. Supported values are “msmt_csd” and “ss3t_csd”.

  • max_sh : list. The maximum harmonic degree of the response function.

• mtnormalize : bool. Should the FODs be mtnormalized?

Inputs:

• *Default qsirecon inputs*

• qsiprep_5tt_hsvs – A hybrid surface volume segmentation 5tt image aligned with the QSIRecon T1w

Outputs:

• wm_txt – SH fiber response function for white matter

• wm_fod – FOD SH coefficients for white matter

• gm_txt – SH fiber response function for gray matter

• gm_fod – FOD SH coefficients for gray matter

• csf_txt – SH fiber response function for CSF

• csf_fod – FOD SH coefficients for CSF

• fod_sh_mif – The same file as wm_fod.

See also

qsirecon.interfaces.mrtrix.MRTrixIngress, qsirecon.interfaces.mrtrix.EstimateFOD, qsirecon.interfaces.mrtrix.SS3TDwi2Response, qsirecon.interfaces.mrtrix.SS3TEstimateFOD, qsirecon.interfaces.mrtrix.MTNormalize

qsirecon.workflows.recon.mrtrix.init_mrtrix_tractography_wf(inputs_dict, name='mrtrix_tracking', qsirecon_suffix='', params={})

Run tractography

This workflow uses mrtrix tools to run csd on multishell data.

Inputs

fod_sh_mif

mif file containing spherical harmonics for tractography

Outputs

global_wm_fod

FOD SH image enhanced by global tractography

global_iso_fod

FOD SH coefficients for other tissue compartments.

l1_penalty

the residual data energy image, including the L1-penalty imposed by the particle potential

qsirecon.workflows.recon.mrtrix.init_mrtrix_connectivity_wf(inputs_dict, name='mrtrix_connectivity', params={}, qsirecon_suffix='')

Runs tck2connectome on a tck file.

Inputs

tck_file

mrtrix3 tck file.

Outputs

matfile

A MATLAB-format file with numerous connectivity matrices for each atlas.

Miscellaneous workflows

qsirecon.workflows.recon.utils.init_discard_repeated_samples_wf(inputs_dict, name='discard_repeats', qsirecon_suffix='', params={})

Remove a sample if a similar direction/gradient has already been sampled.

qsirecon.workflows.recon.utils.init_conform_dwi_wf(inputs_dict, name='conform_dwi', qsirecon_suffix='', params={})

If data were preprocessed elsewhere, ensure the gradients and images conform to LPS+ before running other parts of the pipeline.

Submodules

• qsirecon.workflows.recon.amico module
• qsirecon.workflows.recon.anatomical module
• qsirecon.workflows.recon.build_workflow module
• qsirecon.workflows.recon.converters module
• qsirecon.workflows.recon.dipy module
• qsirecon.workflows.recon.dsi_studio module
• qsirecon.workflows.recon.mrtrix module
• qsirecon.workflows.recon.pyafq module
• qsirecon.workflows.recon.scalar_mapping module
• qsirecon.workflows.recon.steinhardt module
• qsirecon.workflows.recon.tortoise module
• qsirecon.workflows.recon.utils module