Skip to content
This repository has been archived by the owner on Mar 28, 2024. It is now read-only.

bids-apps/FibreDensityAndCrosssection

Repository files navigation

No Maintenance Intended

This BIDS app is not longer maintained.

Description

This BIDS App enables group analysis of diffusion MRI data by performing a Fixel-Based Analysis (FBA) of Fibre Density, Fibre Cross-section and a combined measure (Fibre Density & Cross-section).

The analysis pipeline relies primarily on the MRtrix3 software package.

Documentation

Full documentation for MRtrix3 is available online here. This pipeline performs pre-processing of diffusion MRI data according to the steps outlined here, and fixel-based analysis using the steps listed here.

Error Reporting

For help and support please post a question on the MRtrix3 discussion.

Acknowledgement

When using this pipeline, please include the following paragraph to descibe the method used. Citations can be found in the attached bibtex file.

Pre-processing was performed by first denoising the diffusion-weighted images (Veraart et al. 2016), followed by eddy-current and motion correction (Andersson et al. 2016). Fibre orientation distributions (FOD) were computed using multi-tissue constrained spherical deconvolution (Jeurissen et al. 2014). Simultaneous bias field correction and intensity normalisation (across subjects) was performed as per Raffelt et al. 2017. All subjects were registered to a study-specific FOD template using an iterative update approach (Raffelt et al. 2011, Raffelt et al. 2012b). Three quantitative measures were computed for each white matter fixel: apparent Fibre Density (FD) (Raffelt et al. 2012), Fibre Cross-section (FC)(Raffelt et al. 2017) and also a combined measure Fibre Density and Cross-section (FDC)(Raffelt et al. 2017b).Statistical analysis was performed using connectivity-based fixel enhancement (CFE)(Raffelt et al. 2015). CFE exploits fixel-fixel connectivity information derived from whole-brain fibre tractography streamlines computed on the FOD template (Tournier et al. 2010). Following tractography, SIFT was used to reduce tractogram biases (Smith et al. 2013). We assigned family-wise error corrected p-values to each fixel using permutation testing of the CFE enhanced t-statistics (5000 permutations).

If your BIDS dataset has reverse phase encoded b=0 or DWI image pairs, please also add this sentence to the paragraph above (after the eddy-current correction): Suceptibility-induced distortions were corrected with reverse phase encoded pairs (Andersson et al. 2003).

Instructions

This pipeline requires that data be organized in accordance with the BIDS spec.

To get your container ready to run type the following your terminal:

$ docker pull bids/fibredensityandcrosssection

Before starting, let's check out the help page

$ docker run -ti bids/fibredensityandcrosssection -h

SYNOPSIS

     run.py [ options ] bids_dir output_dir analysis_level

        bids_dir     The directory with the input dataset formatted according to
                     the BIDS standard.

        output_dir   The directory where the output files should be stored. If
                     you are running group level analysis this folder should be
                     prepopulated with the results of the participant level
                     analysis.

        analysis_level Level of the analysis that will be performed. Valid
                     choices are: [participant1, group1, participant2, group2,
                     participant3, group3, participant4, group4].  Multiple
                     participant level analyses can be run independently(in
                     parallel) using the same output_dir.

DESCRIPTION

     Perform group analysis of diffusion MRI data with a Fixel-Based Analysis
     (FBA) of Fibre Density, Fibre Cross-section and a combined measure (Fibre
     Density & Cross-section). The analysis pipeline relies primarily on the
     MRtrix3 software package (www.mrtrix.org).

optional arguments

  --participant_label <space-separated list>
     The label(s) of the participant(s) that should be analyzed. The label
     corresponds to sub-<participant_label> from the BIDS spec (so it does not
     include "sub-"). If this parameter is not provided all subjects should be
     analyzed. Multiple participants can be specified with a space separated
     list.

  --n_cpus INT
     The number of CPU cores available on the compute node. Set to 0 to use the
     maximum number of cores available

Options for this Fibre Density and Cross-section BIDS-App

  -vox_size FLOAT
     define the voxel size (in mm) to be used during the upsampling step
     (participant1 analysis level only)

  -group_subset GROUP_SUBSET
     Define a subset of participants to be used when generating the group-
     average FOD template and response functions. The subset is to be supplied
     as a comma separate list. Note the subset should be representable of your
     entire population and not biased towards one particular group. For example
     in a patient-control comparison, choose equal numbers of patients and
     controls. Used in group1 and group2 analysis levels.

  -num_tracks INT
     define the number of streamlines to be computed when performing
     tractography on the FOD template. (group3 analysis level only)

  -num_tracks_sift INT
     define the number of streamlines to remain after performing SIFT on the
     tractogram(group3 analysis level only)

Standard options

  -continue <TempDir> <LastFile>
     Continue the script from a previous execution; must provide the temporary
     directory path, and the name of the last successfully-generated file

  -force
     Force overwrite of output files if pre-existing

  -help
     Display help information for the script

  -quiet
     Suppress all console output during script execution

  -verbose
     Display additional information and progress for every command invoked

  -debug
     Display additional debugging information over and above the verbose output


AUTHOR
     David Raffelt (david.raffelt@florey.edu.au)

To run the pipeline using docker

This fixel-based analysis pipeline has been broken up into several stages, each defined by the "analysis level" positional argument. Each level is labelled as either participant or group. Participant levels can be run on different subjects independently, while group level analysis is performed on all subjects within the group. The order in which the analysis should be run is participant1, group1, participant2, group2, participant3, group3, particpant4, group4.

In order to share data between our container and the rest of our machine, we need to mount a volume. Docker does this with the -v flag. Docker expects its input formatted as: -v path/to/local/data:/path/in/container.

For example, to run the first particpant level analysis on a single subject use:


docker run -i --rm -v /path/to/local/data:/bids_input -v /path/to/local/output:/output bids/fibredensityandcrosssection /bids_input /output participant1 --participant_label 01

For example, to run the first particpant level analysis on a single subject use: