Skip to content

How to use

Jump to bottom
Liu Mengxing edited this page Dec 3, 2022 · 5 revisions

How to use RTP-pipeline

Input files

The input files need to be sorted in independent folders. We recommend that you create a basedir directory and store all subject information there. Inside basedir, create the input and output folders.

mkdir /Users/myusername/testFolder
export basedir=/Users/myusername/testFolder
cd $basedir
mkdir input
mkdir output

Inside the input folder, each file type will have an independent folder name. Below, the explanation of each file type. Important: the folder names need to be exactly the same as below.

If you are using Flywheel, there will be a GUI in the web browser and no need to create a folder structure.

anatomical

Create the folder (mkdir $basedir/input/anatomical) and paste the file inside.

t1w.nii.gz file coming from rtp-preproc output.

bval

Create the folder (mkdir $basedir/input/bval) and paste the file inside.

dwi.bval file coming from rtp-preproc output.

bvec

Create the folder (mkdir $basedir/input/bvec) and paste the file inside.

dwi.bvec file coming from rtp-preproc output.

dwi

Create the folder (mkdir $basedir/input/dwi) and paste the file inside.

dwi.nii.gz file coming from rtp-preproc output.

fs

Create the folder (mkdir $basedir/input/fs) and paste the file inside.

fs.zip file coming from anatroi container output. It can be created/extended manually.

tractparams

Create the folder (mkdir $basedir/input/tractparams) and paste the file inside.

Create a comma separated values called tract_params.csv. Instructions in how to create/edit, here.

Config file

If you are using Flywheel, there is no config file, the values are introduced in the GUI. The description of the fields here will be based on the information field in the GUI, but there might be some more information here.

If you are using a container, you will need to provide a config.json file to the docker container. Create a file locally, for example: vim $basedir/yourLocalConfigFile.json or using your favorite text editor.

You can copy and paste this config file:

{
    "config": {
        "fiberWeighting": 1,
        "numberOfNodes": 100,
        "outname": "afq_output",
        "phaseEncodeDir": 2,
        "ET_angleValues": " 45, 45, 25, 25, 25,  5,  5",
        "ET_maxlength":   "100,150,100,150,200,150,200",
        "ET_minlength": 20,
        "ET_numberFibers": 1000000,
        "ET_track_stepSizeMm": 999,
        "track_faMaskThresh": 0.2,
        "track_faFodThresh": 0.05,
        "life_discretization": 360,
        "life_num_iterations": 10,
        "life_runLife": true,
        "life_saveOutput": false,
        "life_test": false,
        "life_writePDB": false,
        "mrtrix_mrTrixAlgo": "iFOD2",
        "mrtrix_autolmax": true,
        "mrtrix_lmax": 6,
        "mrtrix_useACT": false
    }
}

This is the detailed explanation of each variable:

  • "numberOfNodes":

    • "description": "AFQ: The number of nodes to represent each fiber."
    • "default": 100
    • "type": "integer"

  • "fiberWeighting":

    • "description": "RTP: Set the amount of weighting that will be applied when calculating tract profiles. 0 means that each fiber contributes equally. 1 means that we apply gaussian weighting where each fibers contribution to the measurement at a node is weighted by its gaussian distance from the tract core. Values greater than 1 mean that the core of the tract is weighted more heavily and fibers further from the core are weighted less heavily (faster fall off than a gaussian). See ComputeTractProperties."
    • "default": 1
    • "type": "integer"

  • "track_faFodThresh":

    • "description": "MRTRIX: Stopping criteria when tracking, FA for DTI and FOD for CSD. Mrtrix uses defaults depending on the algo and depending on the algo these number will refer to FA or FOD. If 999 use the defaults, otherwise use the value here. See mrTrix docs for defaults"
    • "default": 999
    • "type": "number"

  • "track_faMaskThresh":

    • "description": "MRTRIX: FA mask threshold from which to initialize tracking. It is used to create the wmMask that is used to seed the whole brain connectome in mrTrix"
    • "default": 0.3
    • "type": "number" *"mrtrix_mrTrixAlgo":
    • "description": "MRTRIX: Tracking algorithm for mrTrix's tckgen. Options are: FACT, iFOD1, iFOD2, NullDits1/NullDist2, SD_STREAM, SpeedTest, Tensor_Det, Tensor_prob. Only iFOD2 and iFOD1 tested in this version, this note will be removed once we check all options are working properly. DEFAULT='iFOD2'"
    • "default": "iFOD2"
    • "type": "string"

  • "mrtrix_useACT":

    • "description": "MRTRIX: Use ACT for tracking. DEFAULT=False"
    • "default": false
    • "type": "boolean"

  • "mrtrix_autolmax":

    • "description": "MRTRIX: Calculate lmax automatically from number of directions. DEFAULT=True"
    • "default": false
    • "type": "boolean"

  • "mrtrix_lmax":

    • "description": "MRTRIX: specify lmax for CSD. Only used if mrtrix_autolmax==0. DEFAULT=6"
    • "default": 6
    • "type": "integer"

  • "life_runLife":

    • "description": "LiFE: Run LiFE algorithm. DEFAULT=true"
    • "default": true
    • "type": "boolean"

  • "life_saveOutput":

    • "description": "LiFE: Save outputs from LiFE algorithm. DEFAULT=true"
    • "default": false "type": "boolean"

  • "life_discretization": {

    • "description": "LiFE: Discretization parameter (this parameter defines the resolution of the Phi tensor in describing the orientation of the fascicles in the connectome (number of orientations encoded in Phi, more specifically the size of Phi in mode 1) DEFAULT=360"
    • "default": 360
    • "type": "number"

  • "life_num_iterations":

    • "description": "LiFE: Number of iterations for LiFE algorithm. DEFAULT=10"
    • "default": 10
    • "type": "number"

  • "life_test":

    • "description": "LiFE: Run LiFE in test mode. DEFAULT=False"
    • "default": false
    • "type": "boolean"

  • "life_writePDB":

    • "description": "LiFE: Write fibers out in PDB. This is a legacy format for the program Quench. DEFAULT=False"
    • "default": false
    • "type": "boolean"

  • "ET_numberFibers":

    • "description": "ET: Number of fibers to generate in each tractotram. As many tractograms as specified with ET_maxlength and ET_angleValues number of pairs will be generated and concatenated. DEFAULT=200000"
    • "default": 200000
    • "type": "number"

  • "ET_minlength":

    • "description": "ET: Minimum fiber length (in mm). This value will be used for mrTrix regardless of ET. If 999, the default from mrTrix will be used (see mrTrix documentation). DEFAULT=999"
    • "default": 999
    • "type": "number"

  • "ET_maxlength":

    • "description": "ET: Maximum fiber length (in mm) used in the whole brain tractrogram tracking. IMPORTANT: it requires the same amount of values as ET_angleValues. Each ET_maxlength value will be matched in position to every ET_angleValues. DEFAULT=100,150,100,150,200,150,200"
    • "default": "100,150,100,150,200,150,200"
    • "type": "string"

  • "ET_angleValues":

    • "description": "ET: Angle cutoff values to use during ET tracking (comma-separated list). Using one value is the equivalent of not using ET. IMPORTANT: there need to be the same amount of ET_maxlength values than ET_angleValues. DEFAULT='45, 45, 25, 25, 25, 5, 5'"
    • "default": "45, 45, 25, 25, 25, 5, 5"
    • "type": "string"

  • "ET_track_stepSizeMm":

    • "description": "ET: track stepSizeMm. DEFAULT=999"
    • "default": 999
    • "type": "number"

How to run

Once you have the folder structure with all the correct files and you have created your config file, you can execute the Docker container with the following command:

docker run -ti --rm \
           -v $basedir/input:/flywheel/v0/input:ro  \
           -v $basedir/output:/flywheel/v0/output  \
           -v $basedir/yourLocalConfigFile.json:/flywheel/v0/config.json \
           garikoitz/rtp-pipeline:4.2.6

or in singularity

singularity run -e --no-home \
    --bind /scratch:/scratch \
    --bind </path/to/input/>:/flywheel/v0/input/:ro \
    --bind </path/for/output/>:/flywheel/v0/output \
    --bind </path/for/example_config.json>:/flywheel/v0/config.json \
    rtp-pipeline_<version>.sif

Output files

There will be a big .zip file with all the outputs, and a bunch of other files:

  • RTP_Output_afq_(datestamp).zip: the whole output from the pipeline, zipped.
  • afq_(datestamp).mat: the classical afq Matlab struct.
  • .tck files: tracts to be visualized with mrTrix's mrView.
  • .obj files: the same tracts, but in obj format. Can be visualized in the browser (for example, directly in Flywheel's output folder) or in macos's explorer.
  • .mif file with the FoDs used in the whole brain tractogram tracking.
  • .nii.gz files (some selected ones):
    • b0
    • fa
    • brainMask
    • wmMask
    • tensors
Clone this wiki locally