.. _ref_other_tools: Other tools ================= .. role:: bash(code) :language: bash This section presents a collection of commonly used tools in our laboratory. It is worth noting that we do not typically develop or contribute to the code of these tools, hence they are given a separate section from other tools such as Scilpy, Dipy, or Tractoflow. To ensure efficient use of these tools, we strongly recommend that you download/clone and compile/install them all in the same location, and keep track of when and how you performed the installations. These tools are fundamental to most major projects in our lab, so you should be comfortable with their installation and basic usage. If not, at a minimum, you should understand what each tool is used for and how to obtain more information on its usage. .. _ref_mi_brain: MI-Brain -------- MI-Brain is a Diffusion MRI and Tractography visualization software designed to help medical professionals and researchers look and explore their data. It provides many features and tools for processing and visualizing tractograms. The software was created by `IMEKA `_ (a Sherbrooke company for diffusion MRI analysis co-founded by Maxime Descoteaux & Pierre-Marc Jodoin). .. figure:: /images/intro_to_software_mi_brain.png :scale: 25 % :align: center MI-Brain facilitates bundle segmentation and basic image/mask operations. Installation ^^^^^^^^^^^^ To install it (it might already be installed on a lab computer), follow these instructions depending on your OS, or refer to the `FAQ `_. **On Linux** * Download the Linux version of MI-Brain `here `_. * In a terminal, extract the .tar.gz release archive using :bash:`tar -xvzf NAME_OF_THE_FILE.tar.gz -C DIRECTORY_TO_PUT_MI_BRAIN`. * Add this to your .bashrc (you can change the name of the alias to your liking): :bash:`alias mibrain="bash DIRECTORY_TO_PUT_MI_BRAIN/MI-Brain.sh"`. * You can now open MI-Brain by typing :bash:`mibrain` in the terminal and pressing enter. **On MacOS** * Download the MacOS version of MI-Brain `here `_. * Open the .dmg file and drag the MI-Brain icon in the Application folder. **On Windows** * Download the Windows version of MI-Brain `here `_, along with the file named "vc_redist.x64.exe.zip". * Double-click on the "vc_redist.x64.exe" executable inside "vc_redist.x64.exe.zip" to install Microsoft Visual C++ 2015 Redistributable. * Double-click on the MI-Brain executable and follow the instructions. Useful Commands ^^^^^^^^^^^^^^^ Make sure to read the `wiki `__ and watch the `videos `_ for useful tips and tricks. If you are heavily using MI-Brain in your research, please cite this `conference abstract `_: *Rheault, F., Houde, J-C., Goyette, N., Morency, F., Descoteaux, M., MI-Brain, a software to handle tractograms and perform interactive virtual dissection, ISMRM Diffusion study group workshop, Lisbon, 2016* .. _ref_mrtrix: MRtrix ------ MRtrix is an open-source software package for diffusion MRI analysis and Tractography. It provides a suite of tools for processing, analyzing, and visualizing diffusion MRI data and streamlines. It is widely used in research and clinical applications. MRtrix is another set of tools to analyse diffusion data, much like Dipy and Scilpy. One main difference is that they use C++ whereas we use python, which may be slower but is easier to use open-source because of its readability? MRtrix pipeline is very similar in spirit to the Scilpy/Dipy and Tractoflow pipeline we implement at the SCIL. Both tools were created around the same time. Both are open source. Both are using a script approach. Generally, MRtrix's strong suit concerns the connectomics, voxel and fixel information (which is like a VBM or TBSS in the space of fODF fixels). See [`Raffelt et al 2015 `_, `Mito et al 2018 `_]. Scilpy/Dipy's advantages: Scilpy/Dipy is written in python, which might be easier to read by the community than MRtrix's C++. Its strong suit concerns streamlines and bundles instead of the voxels/fixels, with tools such as Recobundles, outlier rejection, tractometry and so on. Installation ^^^^^^^^^^^^ To install it on Linux or WSL (Windows), follow these steps in a terminal or refer to this `documentation `__: .. code-block:: bash # Start by installing all the dependencies sudo apt-get install g++ libeigen3-dev zlib1g-dev libqt5opengl5-dev libqt5svg5-dev libgl1-mesa-dev libfftw3-dev libtiff5-dev libpng-dev # Then install MRtrix via Github. Make sure to be in the repository where you want it installed! git clone https://github.com/MRtrix3/mrtrix3.git cd mrtrix3 ./configure ./build ./set_path Open a new terminal and type :bash:`mrview`. This should open a GUI for you. *Note: MacOS users can use* :bash:`brew install mrtrix3` *to install MRtrix.* Useful Commands ^^^^^^^^^^^^^^^ For a quick overview of commands you can look at their `Getting Started `__ section. This `webpage `__ hosts an extensive tutorial of MRtrix3 from raw data to tractography (and more). We recommend trying this tutorial and finding analogous functions in Scilpy to reach the same end goals. :bash:`tckgen`: a tool for tractography, generating streamlines based on the diffusion MRI data. :bash:`dwidenoise`: a tool for removing noise from the diffusion MRI data. :bash:`mrconvert`: a tool for converting between different file formats of MRI data. Changing strides and datatype. This is a useful tool to convert DICOM to NIFTI when other tools fail. :bash:`mrinfo`: a tool for displaying information about an MRI dataset, such as image dimensions, voxel sizes, and data types. :bash:`mrview`: a viewer for visualizing image and tractography file, fast and intuitive for fast sanity check as well as advanced rendering. .. _ref_ants: ANTs ---- ANTs (Advanced Normalization Tools) is a powerful open-source software package for (medical) image analysis registration and segmentation. Extremely useful to create templates or extract cortical thickness. It is widely used in the field of neuroimaging. You can find information on their `Github page `__ or on their new `documentation `__. Installation ^^^^^^^^^^^^ Since the installation is not that easy and it takes a few GB of space, you might want to consider using :ref:`ref_containers` for occasional use. However if you want to install ANTs, follow these steps or visit their `Github page `__: * Create a folder that will contain the ANTs scripts and go in it. For instance: :bash:`mkdir ~/YOUR_SOFTWARES/ANTs; cd ~/YOUR_SOFTWARES/ANTs`. * Download this `file `_ and put it in your ANTs folder. * Run :bash:`bash installANTs.sh`. * Add those two lines to your .bashrc: .. code-block:: bash export ANTSPATH=~/YOUR_SOFTWARES/ANTs/install/bin export PATH=${ANTSPATH}:$PATH Once installed, you should be able to type :bash:`antsRegistration` to see the help display. Useful Commands ^^^^^^^^^^^^^^^ ANTs uses a pretty complex algorithm, so the command line is sometimes hard to understand at first. Visit their `wiki `__ for helpful information. :bash:`antsRegistrationSyN.sh` To compute registration (both linear and nonlinear). The main use is to bring any subject to MNI space or to co-registered different modalities of a single subject. Be careful, this version of the script use the correlation coefficient (CC) as a metric, meaning only correlated image intensites will work (T1w to T1w, T1w to FLAIR, or b0 to FMRI). This script runs in 10-20 minutes. :bash:`antsRegistrationSyNQuick.sh` To compute registration (both linear and nonlinear). This version of the script use the Mutual Information (MI) as a metric, meaning statistical dependencies between image intensites will work (T1w to b0, FLAIR to PET, or T2w to CT). This script is much faster and is often use for to bring the T1w image into the diffusion space or for a quick registration (1 minute, lower quality) between image. :bash:`antsApplyTransforms` To apply any transformations from ANTs to other images. Useful after registration of two images to transform masks and labels. Be sure to apply the transformation in the right order and use the right datatype (ask Francois Rheault about it). :bash:`antsMultivariateTemplateConstruction2.sh` To build templates. Suppose you want to build a FA or T1 template of your aging brain population (or any population). We use ANTS for this. This script is fairly complex, you have to know a lot about the inner working of ANTs to obtain a good results (ask Francois Rheault about it) :bash:`antsBrainExtraction.sh` To perform skull-stripping or brain extraction. This is done with registration and a template. It usually takes 20-30 minutes but can be more robust than FSL bet (we use it only for T1w, FLAIR). The template is available `(here) `__ (use the *t1_template.nii.gz* and *t1_brain_probability_map.nii.gz*) :bash:`N4BiasFieldCorrection` To perform bias correction algorithm on T1w, which evaluate the spatial change in signal and ensure its uniformity. :bash:`antsAtroposN4.sh` To segment WM-GM-CSF and to compute cortical thickness. This is a less common usage in the lab. .. _ref_fsl: FSL --- FSL (FMRIB Software Library) is an open-source software library for neuroimaging analysis. It provides a comprehensive suite of tools for processing, analyzing, and visualizing neuroimaging data (Structural, Functional and Diffusion MRI). It is widely used in academic and clinical research. .. figure:: /images/intro_to_software_fsl.png :scale: 40 % :align: center FSLeyes is used here to visualize fMRI data. Installation ^^^^^^^^^^^^ Visit this `website `__ for download and install instructions as well as a general overview of tools available in the package `(here) `__ You will have to download a Python file install (after accepting a license) and then install FSL (by executing the Python installer). It is common to add these lines to your :bash:`.bashrc` to make FSL easier to use: .. code-block:: bash # export FSLDIR=/PATH/TO/FSL . ${FSLDIR}/etc/fslconf/fsl.sh export PATH=${FSLDIR}/bin:${PATH} Once installed, you should be able to type :bash:`bet` or :bash:`fast` to see the help display. :bash:`fsleyes` will launch the visualization tool. Useful Commands ^^^^^^^^^^^^^^^ Functional MRI """""""""""""" :bash:`feat` is a user-friendly FMRI analysis tool that includes data preprocessing, timeseries analysis, and group analysis using Bayesian techniques. :bash:`melodic` is an FMRI analysis tool that uses Probabilistic Independent Component Analysis (PICA) to automatically estimate the number of signal and noise sources in the data and provide "p-values" for the output spatial maps. Structural MRI """""""""""""" :bash:`bet` is the Brain Extraction Tool, which segments the brain from non-brain in structural and functional data and models skull and scalp surfaces. :bash:`fast` is FMRIB's Automated Segmentation Tool. It provides brain segmentation (into different tissue types) and bias field correction. :bash:`flirt` is FMRIB's Linear Image Registration Tool, which offers linear inter- and intra-modal registration. :bash:`fnirt` is FMRIB's NonLinear Image Registration Tool, which offers linear inter- and intra-modal registration. :bash:`siena` is a structural brain change analysis tool used for estimating brain atrophy. :bash:`susan` is a nonlinear noise reduction tool. Diffusion MRI """"""""""""" :bash:`bedpostx` is a tool in FSL that uses Bayesian estimation with Markov Chain Monte Carlo sampling to model diffusion MRI signal as fiber orientation distributions and estimate diffusion parameters at each voxel for local modeling of diffusion parameters, including estimation of the number and orientation of fiber bundles. :bash:`probtrackx` is a tool in FSL that performs tractography and connectivity-based segmentation using probabilistic tractography. It calculates the probability of connection between pairs of voxels in the brain by simulating diffusion-weighted MRI signal propagation along different possible fiber pathways to investigate the connectivity of different brain regions and segment the brain into functional networks based on connectivity patterns. :bash:`eddy` is a tool that performs eddy current correction and motion correction for diffusion MRI data. :bash:`topup` is a tool that corrects for susceptibility-induced distortions in diffusion MRI data. :bash:`xtract` (cross-species tractography) is a tool that automatically extract a set of tracts in humans and macaques. It can also be used to define one's own tractography protocols where all the user needs to do is to define a set of masks in standard space (e.g. MNI152). **TBSS** is Tract-Based Spatial Statistics, part of FMRIB's Diffusion Toolbox, which offers voxelwise analysis of multi-subject diffusion data. .. _ref_freesurfer: Freesurfer ---------- Freesurfer is an open-source software package for brain surface reconstruction and analysis. It provides a suite of tools for processing, analyzing, and visualizing brain surface data. It is widely used in research and clinical applications, it is often the tool of choice to generate cortical and/or subcortical parcellations. Visit this `website `__ for a general overview of tools available in the package. Installation ^^^^^^^^^^^^ Install instructions for release 7 are available `here `__. In the table shown, pick your OS (verify which Linux distribution) and pick either *deb* (or *pkg* on MacOS) or *tar.gz*. If you picked the package option, you will have to install it using your OS package manager. If you picked the *tar.gz* option, you will have to use the following command: :bash:`tar -zxpf freesurfer-linux-centos7_*.tar.gz` This will extract a folder in the **current** directory, so make sure to navigate to a directory for your software. Then, add these lines to your :bash:`.bashrc`: .. code-block:: bash export FREESURFER_HOME="/PATH/TO/FREESURFER/freesurfer" . ${FREESURFER_HOME}/SetUpFreeSurfer.sh Once installed, you should be able to type :bash:`recon-all` or :bash:`mri_convert` to see the help display. Useful Commands ^^^^^^^^^^^^^^^ Freesurfer is mostly known for its pipeline :bash:`recon-all` that starts from a T1w image and generates cortical parcellation, multiple meshes that represent the cortical surfaces. Freesurfer is much more than that, it contains a variety of tools: - Skull stripping, B1 bias field correction, and gray-white matter segmentation - Reconstruction of cortical surface models (gray-white boundary surface and pial surface) - Labeling of regions on the cortical surface, as well as subcortical brain structures - Nonlinear registration of the cortical surface of an individual with a stereotaxic atlas - Statistical analysis of group morphometry differences This `tutorial `__ provides details on the typical output of their :bash:`recon-all` pipeline (along with FreeView, see below) It also contains the **TRACULA** (TRActs Constrained by UnderLying Anatomy) tool. TRACULA performs the reconstruction of major white-matter pathways from dMRI data. As defined `here `__: *TRACULA uses prior knowledge on the relative positions of white-matter pathways with respect to their surrounding anatomical structures. Whereas the anatomical segmentation/parcellation tools use this type of neighborhood information to classify voxels in the volume or vertices on the surface, TRACULA uses it to produce tractography* streamlines. .. figure:: /images/intro_to_software_freeview.png :scale: 25 % :align: center freeview is FreeSurfer built-in viewer, it supports tractography, meshes and 3D/4D images. It was made to work well with their pipeline outputs (perfect for QC). .. _ref_dmri_explorer: dMRI-explorer ------------- If you want to visualize tensor and multi-tensor images in MRtrix, DIPY and FSL format as well as spherical functions expressed as a series of spherical harmonics coefficients, `dMRI-explorer `_ is another great tool produced in the lab. It allows for real-time diffusion MRI slicing on Linux and Windows using OpenGL 4.6. For installation and usage, a thorough guide is available on the `Github page `__. .. _ref_dicom_converters: DICOM converters ---------------- To convert DICOM data to the NIFTI format our tools understand, we typically use :bash:`dcm2niix` or :bash:`dcm2bids`. Install :bash:`dcm2niix` with :bash:`curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip`, and visit their `Github page `__ for more information. If you want a more complete convertion which follows `BIDS `_, install :bash:`dcm2bids` in a python virtual environment using :bash:`pip install dcm2bids`. .. _ref_mricrogl: MRIcroGL -------- MRIcroGL is an open-source software package for the visualization of MRI data. It provides tools for visualizing MRI data in 2D and 3D. There are a lot of options for shaders, volume rendering, and automatic screenshots for research projects. Visit this website for download and install instructions `(here) `__. You can download precompiled binaries for Linux/Windows/Mac. Their `Github `__ contains everything needed to compile everything from source.