Name: MRtrix3_connectome
Owner: BIDS Apps
Description: Generate subject connectomes from raw image data and perform inter-subject connection density normalisation, using tools provided in the *MRtrix3* software package.
Created: 2016-08-04 16:26:23.0
Updated: 2018-05-24 11:54:35.0
Pushed: 2018-05-24 06:23:29.0
Homepage: http://www.mrtrix.org/
Size: 341
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This BIDS App enables generation and subsequent group analysis of structural connectomes generated from diffusion MRI data. The analysis pipeline relies primarily on the MRtrix3 software package, and includes a number of state-of-the-art methods for image processing, tractography reconstruction, connectome generation and inter-subject connection density normalisation.
NOTE: App is still under development; script is not guaranteed to be operational for all use cases.
Due to use of the Anatomically-Constrained Tractography (ACT) framework, correction of
EPI susceptibility distortions is a prerequisite for this pipeline. Currently, this is
only possible within this pipeline through use of the FSL tool topup
, which relies
on the presence of spin-echo EPI images with differences in phase encoding to estimate
the causative inhomogeneity field. In the absence of such data, this pipeline is not
currently applicable; though recommendations for alternative mechanisms for such
correction in the Issues page are welcome, and development of novel techniques for
performing this correction are additionally underway.
While many common DICOM conversion software are capable of providing data characterising
the phase and slice encoding performed in the acquisition protocol, which are subsequently
used by this pipeline to automate DWI data pre-processing, for some softwares and/or
some data (particularly those not acquired on a Siemens platform), such data may not be
present in the sidecar JSON files for files in the BIDS dwi/
and fmap/
directories.
In this circumstance, it will be necessary for users to manually enter the relevant
information into these files in order for this script to be capable of processing the
data. Every JSON file in these two directories should contain the BIDS fields
PhaseEncodingDirection
and TotalReadoutTime
. For DWI data, it is also preferable to
provide the SliceEncodingDirection
and SliceTiming
fields. More information on these
data can be found in the BIDS documentation.
Please use the official MRtrix3 documentation for reference. Additional information may be found in the online MRtrix3 community forum.
Experiencing problems? You can either post a private message to me on the
MRtrix3 community forum, or you can report it
directly to the GitHub issues list.
In both cases, please include as much information as possible; this may include re-running
the script using the --debug
option, which will provide additional information at the
terminal, and preserve temporary files generated by the script within your target output
directory, which can be forwarded to the developer.
When using this pipeline, please use the following snippet to acknowledge the relevant work (amend as appropriate depending on options used):
Structural connectomes were generated principally using tools provided in the MRtrix3 software package (http://mrtrix.org). This included: DWI denoising (Veraart et al., 2016), Gibbs ringing removal (Kellner et al., 2016), pre-processing (Andersson et al., 2003; Andersson and Sotiropoulos, 2015; Andersson et al., 2016) and bias field correction (Tustison et al., 2010 OR Zhang et al., 2001); inter-modal registration (Bhushan et al., 2015); brain extraction (Smith, 2002 OR Iglesias et al., 2011), T1 tissue segmentation (Zhang et al., 2001; Smith, 2002; Patenaude et al., 2011; Smith et al., 2012); spherical deconvolution (Tournier et al., 2004; Jeurissen et al., 2014); probabilistic tractography (Tournier et al., 2010) utilizing Anatomically-Constrained Tractography (Smith et al., 2012) and dynamic seeding (Smith et al., 2015b); SIFT2 (Smith et al., 2015b); T1 parcellation (((Avants et al., 2008 OR Andersson et al., 2010) AND (Tzourio-Mazoyer et al., 2002 OR Craddock et al., 2012 OR (Zalesky et al., 2010 AND Perry et al., 2017))) OR (Dale et al., 1999 AND (Desikan et al., 2006 OR Destrieux et al., 2010 OR Glasser et al., 2016))); robust structural connectome construction (Smith et al., 2015a; Yeh et al., 2016).
rsson, J. L.; Skare, S. & Ashburner, J. How to correct susceptibility distortions in spin-echo echo-planar images: application to diffusion tensor imaging. NeuroImage, 2003, 20, 870-888
rsson, J. L. R.; Jenkinson, M. & Smith, S. Non-linear registration, aka spatial normalisation. FMRIB technical report, 2010, TR07JA2
rsson, J. L. & Sotiropoulos, S. N. An integrated approach to correction for off-resonance effects and subject movement in diffusion MR imaging. NeuroImage, 2015, 125, 1063-1078
rsson, J. L. R. & Graham, M. S. & Zsoldos, E. & Sotiropoulos, S. N. Incorporating outlier detection and replacement into a non-parametric framework for movement and distortion correction of diffusion MR images. NeuroImage, 2016, 141, 556-572
ts, B. B.; Epstein, C. L.; Grossman, M. & Gee, J. C. Symmetric diffeomorphic image registration with cross-correlation: Evaluating automated labeling of elderly and neurodegenerative brain. Medical Image Analysis, 2008, 12, 26-41
han, C.; Haldar, J. P.; Choi, S.; Joshi, A. A.; Shattuck, D. W. & Leahy, R. M. Co-registration and distortion correction of diffusion and anatomical images based on inverse contrast normalization. NeuroImage, 2015, 115, 269-280
dock, R. C.; James, G. A.; Holtzheimer, P. E.; Hu, X. P.; Mayberg, H. S. A whole brain fMRI atlas generated via spatially constrained spectral clustering. Human Brain Mapping, 2012, 33(8), 1914-1928
, A. M.; Fischl, B. & Sereno, M. I. Cortical Surface-Based Analysis: I. Segmentation and Surface Reconstruction. NeuroImage, 1999, 9, 179-194
kan, R. S.; Ségonne, F.; Fischl, B.; Quinn, B. T.; Dickerson, B. C.; Blacker, D.; Buckner, R. L.; Dale, A. M.; Maguire, R. P.; Hyman, B. T.; Albert, M. S. & Killiany, R. J. An automated labeling system for subdividing the human cerebral cortex on MRI scans into gyral based regions of interest NeuroImage, 2006, 31, 968-980
rieux, C.; Fischl, B.; Dale, A. & Halgren, E. Automatic parcellation of human cortical gyri and sulci using standard anatomical nomenclature NeuroImage, 2010, 53, 1-15
ser, M. F.; Coalson, T. S.; Robinson, E. C.; Hacker, C. D.; Harwell, J.; Yacoub, E.; Ugurbil, K.; Andersson, J.; Beckmann, C. F.; Jenkinson, M.; Smith, S. M. & Van Essen, D. C. A multi-modal parcellation of human cerebral cortex. Nature, 2016, 536, 171-178
sias, J. E.; Liu, C. Y.; Thompson, P. M. & Tu, Z. Robust Brain Extraction Across Datasets and Comparison With Publicly Available Methods. IEEE Transactions on Medical Imaging, 2011, 30, 1617-1634
issen, B; Tournier, J-D; Dhollander, T; Connelly, A & Sijbers, J. Multi-tissue constrained spherical deconvolution for improved analysis of multi-shell diffusion MRI data NeuroImage, 2014, 103, 411-426
ner, E.; Dhital, B.; Kiselev, V. G.; Reisert, M. Gibbs-ringing artifact removal based on local subvoxel-shifts. Magnetic Resonance in Medicine, 2006, 76(5), 1574-1581
naude, B.; Smith, S. M.; Kennedy, D. N. & Jenkinson, M. A Bayesian model of shape and appearance for subcortical brain segmentation. NeuroImage, 2011, 56, 907-922
y, A.; Wen, W.; Kochan, N. A.; Thalamuthu, A.; Sachdev, P. S.; Breakspear, M. The independent influences of age and education on functional brain networks and cognition in healthy older adults. Human Brain Mapping, 2017, 38(10), 5094-5114
h, S. M. Fast robust automated brain extraction. Human Brain Mapping, 2002, 17, 143-155
h, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. Anatomically-constrained tractography: Improved diffusion MRI streamlines tractography through effective use of anatomical information. NeuroImage, 2012, 62, 1924-1938
h, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. The effects of SIFT on the reproducibility and biological accuracy of the structural connectome. NeuroImage, 2015a, 104, 253-265
h, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. SIFT2: Enabling dense quantitative assessment of brain white matter connectivity using streamlines tractography. NeuroImage, 2015b, 119, 338-351
nier, J.-D.; Calamante, F., Gadian, D.G. & Connelly, A. Direct estimation of the fiber orientation density function from diffusion-weighted MRI data using spherical deconvolution. NeuroImage, 2004, 23, 1176-1185
nier, 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
ison, N.; Avants, B.; Cook, P.; Zheng, Y.; Egan, A.; Yushkevich, P. & Gee, J. N4ITK: Improved N3 Bias Correction. IEEE Transactions on Medical Imaging, 2010, 29, 1310-1320
rio-Mazoyer, N.; Landeau, B.; Papathanassiou, D.; Crivello, F.; Etard, O.; Delcroix, N.; Mazoyer, B. & Joliot, M. Automated Anatomical Labeling of activations in SPM using a Macroscopic Anatomical Parcellation of the MNI MRI single-subject brain. NeuroImage, 15(1), 273?289
art, J.; Fieremans, E. & Novikov, D.S. Diffusion MRI noise mapping using random matrix theory Magn. Res. Med., 2016, early view, doi:10.1002/mrm.26059
C.H.; Smith, R.E.; Liang, X.; Calamante, F.; Connelly, A. Correction for diffusion MRI fibre tracking biases: The consequences for structural connectomic metrics. Neuroimage, 2016, doi: 10.1016/j.neuroimage.2016.05.047
sky, A.; Fornito, A.; Harding, I. H.; Cocchi, L.; Yücel, M.; Pantelis, C. & Bullmore, E. T. Whole-brain anatomical networks: Does the choice of nodes matter? NeuroImage, 2010, 50, 970-983
g, Y.; Brady, M. & Smith, S. Segmentation of brain MR images through a hidden Markov random field model and the expectation-maximization algorithm. IEEE Transactions on Medical Imaging, 2001, 20, 45-57
Generate structural connectomes based on diffusion-weighted and T1-weighted image data using state-of-the-art reconstruction tools, particularly those provided in MRtrix3
mrtrix3_connectome.py bids_dir output_dir analysis_level [ options ]
–output_verbosity
The verbosity of script output (number from 1 to 3); higher values result in more generated data being included in the output directory
–parcellation
The choice of connectome parcellation scheme (compulsory for participant-level analysis). Options are: aal,aal2,craddock200,craddock400,desikan,destrieux,hcpmmp1,perry512
–preprocessed
Indicate that the subject DWI data have been preprocessed, and hence initial image processing steps will be skipped (also useful for testing)
–streamlines
The number of streamlines to generate for each subject
–template_reg
The choice of registration software for mapping subject to template space. Options are: ants, fsl
-d/–debug
In the event of encountering an issue with the script, re-run with this flag set to provide more useful information to the developer
-h/–help
Display help information for the script
-n/–n_cpus number
Use this number of threads in MRtrix3 multi-threaded applications (0 disables multi-threading)
-s/–skip-bids-validator
Skip BIDS validation
-v/–version
show program's version number and exit
Author: Robert E. Smith (robert.smith@florey.edu.au)
Copyright: Copyright (c) 2008-2018 the MRtrix3 contributors.
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, you can obtain one at http://mozilla.org/MPL/2.0/.
MRtrix is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
For more details, see http://www.mrtrix.org/.
The bids/MRtrix3_connectome Docker container enables users to generate structural connectomes from diffusion MRI data using state-of-the-art techniques. The pipeline requires that data be organized in accordance with the BIDS specification.
In your terminal, type:
cker pull bids/mrtrix3_connectome
To run the script in participant level mode (for processing one subject only), use e.g.:
cker run -i --rm \
-v /Users/yourname/data:/bids_dataset \
-v /Users/yourname/outputs:/outputs \
bids/mrtrix3_connectome \
/bids_dataset /outputs participant --participant_label 01 --parcellation desikan
Following processing of all participants, the script can be run in group analysis mode using e.g.:
cker run -i --rm \
-v /Users/yourname/data:/bids_dataset \
-v /Users/yourname/output:/output \
bids/mrtrix3_connectome \
/bids_dataset /output group
If you wish to run this script on a computing cluster, we recommend the use of
Singularity. Although built for Docker, this container
can be converted using the
docker2singularity
tool.
The script mrtrix3_connectome.py
can additionally be used outside of this Docker
container, as a stand-alone Python script build against the MRtrix3 Python libraries.
Using the script in this way requires setting the PYTHONPATH
environment variable to
include the path to the MRtrix3 lib/
directory where it is installed on your local
system, as described here.
When used in this way, the command-line interface of the script will be more consistent
with the rest of MRtrix3. Note however that this script may make use of MRtrix3
features or bug fixes that have not yet been merged into the master
branch; in this
case, it may be necessary to install the same version of MRtrix3 as that installed
within “Dockerfile
“.