updated docs

Author: josephmje

CONTRIBUTING.rst

@@ -4,6 +4,74 @@
 Contributing
 ============
 
+.. code-block:: console
+
+    dmriprep
+    ├── CHANGES.rst
+    ├── CONTRIBUTING.rst
+    ├── dmriprep
+    │   ├── __about__.py
+    │   ├── cli.py
+    │   ├── data
+    │   │   ├── boilerplate.bib
+    |   |   ├── eddy_parameters
+    │   │   └── ENIGMA_targets
+    │   ├── due.py
+    │   ├── __init__.py
+    │   ├── interfaces
+    │   │   ├── fmap.py
+    │   │   ├── __init__.py
+    │   │   └── reportlets.py
+    │   ├── qc.py
+    │   ├── utils
+    │   │   ├── bids.py
+    │   │   ├── hemisphere.py
+    │   │   └── __init__.py
+    │   ├── _version.py
+    │   ├── viz
+    │   │   ├── __init__.py
+    │   │   └── utils.py
+    │   └── workflows
+    │       ├── anatomical.py
+    │       ├── base.py
+    │       ├── dwi
+    │       │   ├── __init__.py
+    │       │   ├── artifacts.py
+    │       │   ├── base.py
+    │       │   ├── eddy.py
+    │       │   ├── outputs.py
+    │       │   ├── qc.py
+    │       │   ├── tensor.py
+    │       │   └── util.py
+    │       ├── fieldmap
+    │       │   ├── __init__.py
+    │       │   ├── ants.py
+    │       │   ├── base.py
+    │       │   ├── brainsuite.py
+    │       │   ├── fmap.py
+    │       │   ├── pepolar.py
+    │       │   ├── phasediff.py
+    │       │   └── synb0.py
+    │       └── __init__.py
+    ├── Dockerfile
+    ├── docs
+    ├── LICENSE
+    ├── long_description.rst
+    ├── Makefile
+    ├── MANIFEST.in
+    ├── pyproject.toml
+    ├── README.rst
+    ├── REFERENCES.rst
+    ├── setup.cfg
+    ├── setup.py
+    ├── tests
+    │   ├── __init__.py
+    │   ├── test_dmriprep.py
+    │   └── test_utils.py
+    ├── tox.ini
+    ├── update_changes.sh
+    └── versioneer.py
+
 We love contributions! dmriprep is open source, built on open source,
 and we'd love to have you hang out in our community.
 

dmriprep/workflows/anatomical.py

@@ -14,7 +14,7 @@
 from niworkflows.anat.ants import init_brain_extraction_wf
 
 
-def init_anat_preproc_wf()
+def init_anat_preproc_wf():
     """
     """
 

dmriprep/workflows/dwi/util.py

@@ -22,7 +22,7 @@ def init_dwi_concat_wf(ref_file):
         :simple_form: yes
 
         from dmriprep.workflows.dwi import init_dwi_concat_wf
-        wf = init_dwi_artifacts_wf(ref_file='/madeup/path/sub-01_dwi.nii.gz')
+        wf = init_dwi_concat_wf(ref_file='/madeup/path/sub-01_dwi.nii.gz')
 
     **Parameters**
 

dmriprep/workflows/fieldmap/__init__.py

@@ -4,3 +4,4 @@
 from .pepolar import init_pepolar_wf
 from .fmap import init_fmap_wf
 from .phasediff import init_phase_wf, init_phdiff_wf
+from .brainsuite import init_brainsuite_wf

dmriprep/workflows/fieldmap/brainsuite.py

@@ -11,7 +11,8 @@
 from nipype.pipeline import engine as pe
 from nipype.interfaces import brainsuite, utility as niu
 
-def init_fmap_wf():
+
+def init_brainsuite_wf():
 
     wf = pe.Workflow(name='brainsuite_wf')
 
@@ -21,7 +22,9 @@ def init_fmap_wf():
                 'T1w',
                 'T1w_mask',
                 'dwi_file',
-                'dwi_mask']),
+                'dwi_mask',
+                'bvec_file',
+                'bval_file']),
         name='inputnode')
 
     outputnode = pe.Node(
@@ -30,16 +33,14 @@ def init_fmap_wf():
 
     bias_corr = pe.Node(brainsuite.Bfc(minBias=0.5, maxBias=1.5), name='bias_corr')
 
+    # nipype spec doesn't have an output definition yet!
     bdp = pe.Node(brainsuite.BDP(), name='bdp')
 
-    wf.connect([])
-
-# bfc -i $indir2/brain.nii.gz -o T1.bfc.nii.gz
-
-# /KIMEL/tigrlab/quarantine/brainsuite/18a/build/bdp/bdp.sh \
-#   T1.bfc.nii.gz \
-#   --t1-mask $indir2/brainmaskautobet_mask.nii.gz \
-#   --nii $indir1/data.nii.gz \
-#   --dwi-mask $indir1/nodif_brain_mask.nii.gz \
-#   -b $indir1/bval.txt \
-#   -g $indir1/eddy_bvecs.txt
+    wf.connect([
+        (inputnode, bias_corr, [('T1w', 'inputMRIFile')]),
+        (bias_corr, bdp, [('outputMRIVolume', 'bfcFile'),
+                          ('T1w_mask', 't1Mask'),
+                          ('dwi_file', 'inputDiffusionData'),
+                          ('dwi_mask', 'dwiMask'),
+                          ('bvec_file', 'BVecBValPair')])
+    ])

docs/dmriprep.workflows.fieldmap.rst

@@ -4,6 +4,14 @@ dmriprep.workflows.fieldmap package
 Submodules
 ----------
 
+dmriprep.workflows.fieldmap.ants module
+---------------------------------------
+
+.. automodule:: dmriprep.workflows.fieldmap.ants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 dmriprep.workflows.fieldmap.base module
 ---------------------------------------
 

docs/workflows.rst

@@ -48,9 +48,6 @@ DWI preprocessing
     :graph2use: orig
     :simple_form: yes
 
-    from collections import namedtuple
-    from dmriprep.workflows.dwi import init_dwi_preproc_wf
-    BIDSLayout = namedtuple('BIDSLayout', ['root'])
     from collections import namedtuple
     from dmriprep.workflows.dwi import init_dwi_preproc_wf
     BIDSLayout = namedtuple('BIDSLayout', ['root'])
@@ -69,3 +66,77 @@ DWI preprocessing
     )
 
 Preprocessing of DWI files is split into multiple sub-workflows described below.
+
+Concatenating Scans
+^^^^^^^^^^^^^^^^^^^
+:mod:`dmriprep.workflows.dwi.util.init_dwi_concat_wf`
+
+By default, each scan in the ``dwi`` folder will get preprocessed separately. However,
+there are some cases where multiple scans should be concatenated before head motion,
+eddy current distortion and susceptibility distortion correction (eg. single-shell
+or multi-shell scan acquired in separate runs).
+
+.. code-block:: console
+
+    bids
+    └── sub-01
+      └── dwi
+          ├── sub-01_acq-multishelldir30b1000_dwi.nii.gz
+          ├── sub-01_acq-multishelldir30b3000_dwi.nii.gz
+          ├── sub-01_acq-multishelldir30b4500_dwi.nii.gz
+          └── sub-01_acq-singleshelldir60b1000_dwi.nii.gz
+
+In the above example, the multi-shell scans should be concatenated and the single-shell
+scan should be left alone. This is done
+
+``--concat_dwis multishelldir30b1000 multishelldir30b3000 multishelldir30b4500``
+
+
+.. workflow::
+    :graph2use: orig
+    :simple_form: yes
+
+    from dmriprep.workflows.dwi import init_dwi_concat_wf
+    wf = init_dwi_concat_wf(ref_file='/madeup/path/sub-01_dwi.nii.gz')
+
+Artifact Removal
+^^^^^^^^^^^^^^^^
+:mod:`dmriprep.workflows.dwi.artifacts.init_dwi_artifacts_wf`
+
+.. workflow::
+    :graph2use: orig
+    :simple_form: yes
+
+    from dmriprep.workflows.dwi import init_dwi_artifacts_wf
+    wf = init_dwi_artifacts_wf(ignore=[], output_resolution=(1, 1, 1))
+
+
+Susceptibility Distortion Correction (SDC)
+------------------------------------------
+
+Introduction
+^^^^^^^^^^^^
+
+Correction Methods
+^^^^^^^^^^^^^^^^^^
+
+1. topup
+2. fieldmap
+3. phasediff
+4. phase1/phase2
+5. nonlinear registration
+    - ants
+    - brainsuite
+6. synthetic b0
+
+The synb0 method is based off of this `paper <https://www.sciencedirect.com/science/article/abs/pii/S0730725X18306179/>`_. It offers an alternative method of SDC by using deep learning on an anatomical image (T1).
+You can use it in this pipeline by generating the synb0s for the subject(s) and passing the bids-like directory containing them to the --synb0_dir parameter. To find out how to generate the synb0s, you can visit our `forked repo <https://github.com/TIGRLab/Synb0-DISCO>`_.
+Once you have a directory of synb0s (recommended to place as derivatives of bids folder, ex. bids/derivatives/synb0/sub-XX), then you are ready to run the pipeline using them! Just run dmripreproc as you usually would, with bids_dir and output_dir, but now add "--synb0_dir <your_synb0_directory>" to your command.
+The synb0 acqp for topup and eddy will be automatically generated in the pipeline in the following format:
+
+..code-block:: console
+
+    0 -1 0 <total_readout_time>
+    0 1 0 0
+
+If you want to overwrite the total_readout_time with one of your own, simply add ``--total_readout <new_trt_time>`` to your command.