Merge pull request #66 from pnlbwh/add-synb0

Add synb0

docs/Pipeline_Branches.md

@@ -0,0 +1,49 @@
+There are many tasks in our Luigi pipeline defined in [different modules](../workflows):
+
+* struct_pipe.py
+* dwi_pipe.py
+* fs2dwi_pipe.py
+
+Some of them can be run standalone. Others require a task to be run beforehand. Such various routes are outlined below:
+
+---
+
+#### T1 + T2 templates
+
+    StructMask, Freesurfer
+
+#### dwi + T2 templates
+
+    EddyEpi, Ukf, Wma800
+
+Provided that `Freesurfer` task was run:
+
+    EddyEpi, Ukf, Fs2Dwi, Wmql, Wmqlqc, TractMeasures
+
+---
+
+#### Only T1 template
+
+    StructMask, Freesurfer
+
+#### dwi+T1 template
+
+    SynB0, Ukf, Wma800
+
+#### ap_pa_template
+
+    TopupEddy, Ukf, Wma800
+
+---
+
+#### Only dwi template
+
+    DwiAlign, GibbsUn, CnnMask, PnlEddy, FslEddy, Ukf, Wma800
+
+Provided that `Freesurfer` task was run:
+
+    DwiAlign, GibbsUn, CnnMask, PnlEddy, FslEddy, Ukf, Fs2Dwi, Wmql, Wmqlqc, TractMeasures
+
+Provided that `GibbsUn` task was run:
+
+    HcpPipe, Ukf, Wma800

docs/TUTORIAL.md

@@ -23,7 +23,9 @@ Table of Contents
       * [Correct eddy and epi](#correct-eddy-and-epi)
          * [EddyEpi](#eddyepi)
             * [FslEddy and PnlEddy](#fsleddy-and-pnleddy)
+         * [SynB0](#synb0)
          * [TopupEddy](#topupeddy)
+         * [HcpPipe](#hcppipe)
       * [UKFTractography](#ukftractography)
       * [Wma800](#wma800)
    * [Fs2Dwi pipeline](#fs2dwi-pipeline)
@@ -384,7 +386,9 @@ Different methods for eddy and epi corrections are described below:
 
 * PnlEddy + PnlEpi (EddyEpi)
 * FslEddy + PnlEpi (EddyEpi)
+* SynB0
 * TopupEddy
+* HcpPipe
 
 
 ### EddyEpi
@@ -459,6 +463,47 @@ The mask and baseline image provided to `FslEddy` are approximated as eddy corre
 be fed into later task FslEddyEpi.
 
 
+### SynB0
+
+When an axial T2w image is absent and there is only AP or PA acquisition, we make use of [Synb0-DISCO](https://github.com/MASILab/Synb0-DISCO)
+program to perform EPI distortion correction. The Synb0-DISCO program is a replacement of topup. It creates a distortion corrected B0 from a single
+AP or PA acquisition. It also provides the usual topup correction parameters that are used to perform eddy correction later.
+However, Synb0-DISCO requires a T1w image.
+
+![](https://github.com/pnlbwh/luigi-pnlpipe/blob/0d2229e1f27fcc6b02825e9a147c0146924eae43/docs/SynB0-Wma800.png)
+
+
+The configuration file used for `SynB0` task is same as the above [dwi_pipe_params.cfg](../params/dwi_pipe_params.cfg). Specifically, `SynB0` requires
+the following parameters definition:
+
+```cfg
+## [SynB0] ##
+acqp: /path/to/acqp.txt
+index: /path/to/index.txt
+```
+
+Where `acqp.txt` just:
+
+```
+0 1 0 0.05
+0 1 0 0
+```
+
+Run it:
+
+```bash
+export LUIGI_CONFIG_PATH=/path/to/dwi_pipe_params.cfg
+
+exec/ExecuteTask --task SynB0 \
+--bids-data-dir /data/pnl/Collaborators/EDCRP/1110/1110_ses-002_T1_nii/rawdata/ \
+-c ne00181 -s 002 \
+--dwi-template sub-*/ses-*/dwi/*_dwi.nii.gz \
+--t1-template sub-*/ses-*/anat/*_T1w.nii.gz
+```
+
+Note that, `SynB0` task is run in coordination with [_synb0_eddy.sh](_synb0_eddy.sh) .
+
+
 ### TopupEddy
 
 When two opposing acquisitions--AP and PA are available such as in Human Connectom Project (HCP), 
@@ -506,6 +551,22 @@ for corrected data is determined as follows:
     *_dir-214_*
 
 
+### HcpPipe
+
+This task supersedes *TopupEddy* task. The *HcpPipe* way of processing opposing pair of DWIs is inherited 
+from [Washington-University/HCPpipelines](https://github.com/Washington-University/HCPpipelines).
+PNL introduced some improvements in that pipeline including:
+
+  * Use [CNN brain masking](https://github.com/pnlbwh/CNN-Diffusion-MRIBrain-Segmentation) program to generate topup mask
+  * Replace outliers (`--repol` flag) for >500 b-shells
+
+Since external processing is involved in this task, it is run via a [separate script](https://github.com/pnlbwh/luigi-pnlpipe/blob/b311000073047b40db9b7b8c1752cdbba883aa6c/workflows/hcp_pnl_topup.lsf) in three steps:
+
+  * Gibbs unringing of opposing pair of DWIs via Luigi
+  * HCP pipeline via shell scripts
+  * Creation of soft links in `sub-*/ses-*/dwi/` directory according to BIDS convention via Luigi
+
+This *HcpPipe* task has been used to process *HCP-EP* data.
 
 
 ## UKFTractography