update docs

Author: josephmje

AUTHORS.rst

@@ -5,12 +5,12 @@ Credits
 Development Leads
 -----------------
 
-- Anisha Keshavan <[email protected]> [Corresponding developer]
-- Adam Richie-Halford <[email protected]>
+- _Anisha Keshavan: [email protected] [Corresponding developer]
+- _Adam Richie-Halford: [email protected]>
 
 Contributors
 ------------
 
-- Ariel Rokem <[email protected]>
-- Michael Joseph <[email protected]>
-- Salim Mansour <[email protected]>
+- _Ariel Rokem: [email protected]
+- _Michael Joseph: [email protected]
+- _Salim Mansour: [email protected]

CHANGES.rst

@@ -1,5 +1,18 @@
-0.1.0 (2018-09-06)
-==================
+Upcoming release (TBD)
+======================
 
-* First release on GitHub.
+0.2.0 (August 20, 2019)
+=======================
 
+  * ENH: Add ``collect_participants`` and ``validate_input_dir`` functions (taken from niworkflows)
+  * ENH: Add ``dwidenoise``, ``mrdegibbs``, ``mrresize``, and ``dwibiascorrect`` from Mrtrix3 as preprocessing steps for the dwi images
+  * ENH: Add workflow for using a synthetic b0 as a reverse PE image for topup
+  * ENH: Add workflows for dealing with fieldmap, phasediff and phase1/phase2 scans (taken from sdcflows)
+  * ENH: Switch crash logs from pickle to text files for easier reading by the user
+  * MAINT: Migrate to a setup.cfg style of installation
+  * ENH: Refactor ``run_dmriprep_pe`` workflow into a single subject workflow with separate sub-workflows for dwi and fieldmap pre-processing
+
+0.1.0 (September 6, 2018)
+=========================
+
+  * First release on GitHub.

Makefile

@@ -66,7 +66,7 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 docs: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/dmriprep.rst
+	rm -f docs/dmriprep*.rst
 	rm -f docs/modules.rst
 	sphinx-apidoc -o docs/ dmriprep
 	$(MAKE) -C docs clean
@@ -86,3 +86,9 @@ dist: clean ## builds source and wheel package
 
 install: clean ## install the package to the active Python's site-packages
 	python setup.py install
+
+docker-dev: ## build the development environment
+	docker build -t dmriprep:dev -f docker/Dockerfile docker/.
+
+docker: docker-dev
+	docker build -t dmriprep:prod -f Dockerfile-dmriprep .

README.rst

@@ -52,3 +52,4 @@ Credits
 -------
 
 This package was created with `Cookiecutter <https://github.com/audreyr/cookiecutter>`_ and the `audreyr/cookiecutter-pypackage <https://github.com/audreyr/cookiecutter-pypackage>`_ project template.
+Several pieces of code have been taken from `fmriprep <https://github.com/poldracklab/fmriprep>`_, `niworkflows <https://github.com/poldracklab/niworkflows>`_ and `sdcflows <https://github.com/poldracklab/sdcflows>`_.

dmriprep/workflows/base.py

@@ -17,6 +17,19 @@
 
 
 def init_dmriprep_wf(parameters):
+    """
+    This workflow organizes the execusion of dMRIPrep, with a sub-workflow for
+    each subject.
+
+    .. workflow::
+        :graph2use: orig
+        :simple_form: yes
+
+    wf = init_dmriprep_wf()
+
+    Parameters
+
+    """
     dmriprep_wf = pe.Workflow(name="dmriprep_wf")
     dmriprep_wf.base_dir = parameters.work_dir
 
@@ -31,6 +44,9 @@ def init_dmriprep_wf(parameters):
         single_subject_wf.config["execution"]["crashdump_dir"] = os.path.join(
             parameters.output_dir, "dmriprep", "sub-" + subject_id, "log"
         )
+        single_subject_wf.config["execution"]["remove_unnecessary_outputs"] = False
+        single_subject_wf.config["execution"]["keep_inputs"] = True
+        single_subject_wf.config["execution"]["crashfile_format"] = "txt"
 
         for node in single_subject_wf._get_all_nodes():
             node.config = deepcopy(single_subject_wf.config)
@@ -41,6 +57,25 @@ def init_dmriprep_wf(parameters):
 
 
 def init_single_subject_wf(subject_id, name, parameters):
+    """
+    This workflow organizes the preprocessing pipeline for a single subject.
+    It collects and reports information about the subject, and prepares
+    sub-workflows to perform diffusion preprocessing.
+
+    Diffusion preprocessing is performed using a separate workflow for each
+    individual dwi series.
+
+    .. workflow::
+        :graph2use: orig
+        :simple_form: yes
+
+    wf = init_single_subject_wf()
+
+    Parameters
+
+    Inputs
+
+    """
 
     dwi_files = parameters.layout.get(
         subject=subject_id,

dmriprep/workflows/dwi/base.py

@@ -441,7 +441,7 @@ def _get_wf_name(dwi_fname):
 
     fname = split_filename(dwi_fname)[1]
     fname_nosub = "_".join(fname.split("_")[1:])
-    name = "func_preproc_" + fname_nosub.replace(".", "_").replace(" ", "").replace(
+    name = "dwi_preproc_" + fname_nosub.replace(".", "_").replace(" ", "").replace(
         "-", "_"
     ).replace("_dwi", "_wf")
 

dmriprep/workflows/dwi/prep_dwi.py

@@ -1,18 +1,54 @@
 # -*- coding: utf-8 -*-
 
 """
-Denoising, unringing and resampling of dwi images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Artefact removal and resampling dwi images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: init_prep_dwi_wf
 
 """
 
 from nipype.pipeline import engine as pe
 from nipype.interfaces import mrtrix3, utility as niu
 
 
-def init_prep_dwi_wf(ignore, output_resolution):
+def init_prep_dwi_wf(ignore, output_resolution, name="prep_dwi_wf"):
+    """
+    This workflow performs denoises and unrings the inputs dwi image and optionally
+    resamples the image to the desired output resolution.
+
+    Denoising is done using Mrtrix3 using the MP-PCA algorithm [Veraart2016_].
+    Unringing is done using Mrtrix3 [Kellner2016]_.
+
+    .. workflow::
+        :graph2use: orig
+        :simple_form: yes
+
+        from dmriprep.workflows.dwi import init_prep_dwi_wf
+        wf = init_prep_dwi_wf(ignore=[], output_resolution=(1, 1, 1))
+
+    **Parameters**
+
+        ignore : list
+            List of artefact removal steps to skip (default: None)
+        output_resolution : tuple
+            Tuple defining the new voxel size for the output image in the x, y, and z dimensions
+        name : str
+            Name of workflow (default: ``prep_dwi_wf``)
+
+    **Inputs**
+
+        dwi_file
+            dwi NIfTI file
+
+    **Outputs**
+
+        out_file
+            dwi NIfTI file after artefact removal and resizing
+
+    """
 
-    prep_dwi_wf = pe.Workflow(name="prep_dwi_wf")
+    prep_dwi_wf = pe.Workflow(name=name)
 
     inputnode = pe.Node(niu.IdentityInterface(fields=["dwi_file"]), name="inputnode")
 

docs/changes.rst

@@ -2,4 +2,4 @@
 What's new
 ----------
 
-.. includes:: ../CHANGES.rst
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -36,9 +36,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
-    "sphinx_click.ext",
+    "sphinx.ext.napoleon",  # support for reading numpy and Google style docstrings
+    "sphinx_click.ext",  # click extension
+    "nipype.sphinxext.plot_workflow"  # nipype extension to plot workflows
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/dmriprep.interfaces.rst

@@ -12,6 +12,14 @@ dmriprep.interfaces.fmap module
    :undoc-members:
    :show-inheritance:
 
+dmriprep.interfaces.fsl module
+------------------------------
+
+.. automodule:: dmriprep.interfaces.fsl
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 dmriprep.interfaces.mrtrix3 module
 ----------------------------------
 
@@ -20,6 +28,14 @@ dmriprep.interfaces.mrtrix3 module
    :undoc-members:
    :show-inheritance:
 
+dmriprep.interfaces.reportlets module
+-------------------------------------
+
+.. automodule:: dmriprep.interfaces.reportlets
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 Module contents
 ---------------