Merge pull request #1195 from oesteban/docs/preprint-review

[DOC] Additions to include before responding to reviews of the pre-print

Author: oesteban

README.rst

@@ -90,6 +90,30 @@ Principles
    the process and decide which subjects should be kept for the group level
    analysis.
 
+
+Limitations and reasons not to use ``fmriprep``
+-----------------------------------------------
+
+1. Very narrow :abbr:`FoV (field-of-view)` images oftentimes do not contain
+   enough information for standard image registration methods to work correctly.
+   Also, problems may arise when extracting the brain from these data.
+   Supporting these particular images is already a future line of the development
+   road-map.
+2. ``fmriprep`` may also underperform for particular populations (e.g. infants) and
+   non-human brains, although appropriate templates can be provided to overcome the
+   issue.
+3. The "EPInorm" approach is currently not supported, although we plan to implement
+   this feature (see `#857 <https://github.com/poldracklab/fmriprep/issues/857>`_).
+4. If you really want unlimited flexibility (which is obviously a double-edged sword).
+5. If you want students to suffer through implementing each step for didactic purposes,
+   or to learn shell-scripting or Python along the way.
+6. If you are trying to reproduce some *in-house* lab pipeline.
+
+(Reasons 4-6 were kindly provided by S. Nastase in his
+`open review <http://academickarma.org/review/j7d5501n779n>`__
+of our `pre-print <https://www.biorxiv.org/content/early/2018/05/06/306951>`__).
+
+
 Acknowledgements
 ----------------
 

docs/usage.rst

@@ -75,3 +75,20 @@ http://neurostars.org/tags/fmriprep/
 To participate in the ``fmriprep`` development-related discussions please use the
 following mailing list: http://mail.python.org/mailman/listinfo/neuroimaging
 Please add *[fmriprep]* to the subject line when posting on the mailing list.
+
+
+Not running on a local machine? - Data transfer
+===============================================
+
+If you intend to run ``fmriprep`` on a remote system, you will need to
+make your data available within that system first.
+
+For instance, here at the Poldrack Lab we use Stanford's
+:abbr:`HPC (high-performance computing)` system, called Sherlock.
+Sherlock enables `the following data transfer options 
+<https://www.sherlock.stanford.edu/docs/user-guide/storage/data-transfer/>`_.
+
+Alternatively, more comprehensive solutions such as `Datalad
+<http://www.datalad.org/>`_ will handle data transfers with the appropriate
+settings and commands.
+Datalad also performs version control over your data.

docs/workflows.rst

@@ -541,12 +541,23 @@ Calculated confounds include the mean global signal, mean tissue class signal,
 tCompCor, aCompCor, Frame-wise Displacement, 6 motion parameters, DVARS, and, if
 the ``--use-aroma`` flag is enabled, the noise components identified by ICA-AROMA
 (those to be removed by the "aggressive" denoising strategy).
+Particular details about ICA-AROMA are given below.
+
+
+ICA-AROMA
+~~~~~~~~~
+:mod:`fmriprep.workflows.bold.confounds.init_ica_aroma_wf`
+
+When one of the `--output-spaces` selected is in MNI space, ICA-AROMA denoising
+can be automatically appended to the workflow.
 The number of ICA-AROMA components depends on a dimensionality estimate
 made by MELODIC.
 For datasets with a very short TR and a large number of timepoints, this may
 result in an unusually high number of components.
 In such cases, it may be useful to specify the number of components to be
 extracted with ``--aroma-melodic-dimensionality``.
+Further details on the implementation are given within the workflow generation
+function (:mod:`fmriprep.workflows.bold.confounds.init_ica_aroma_wf`).
 
 *Note*: *non*-aggressive AROMA denoising is a fundamentally different procedure
 from its "aggressive" counterpart and cannot be performed only by using a set of noise

fmriprep/interfaces/freesurfer.py

@@ -195,10 +195,10 @@ class PatchedConcatenateLTA(ConcatenateLTA):
     A temporarily patched version of ``fs.ConcatenateLTA`` to recover from
     `this bug <https://www.mail-archive.com/[email protected]/msg55520.html>`_
     in FreeSurfer, that was
-    `fixed here <https://github.com/freesurfer/freesurfer/pull/180>`_.
+    `fixed here <https://github.com/freesurfer/freesurfer/pull/180>`__.
 
     The original FMRIPREP's issue is found
-    `here <https://github.com/poldracklab/fmriprep/issues/768>`_.
+    `here <https://github.com/poldracklab/fmriprep/issues/768>`__.
     """
 
     def _list_outputs(self):

fmriprep/workflows/bold/confounds.py

@@ -364,6 +364,7 @@ def init_carpetplot_wf(mem_gb, metadata, name="bold_carpet_wf"):
 
 def init_ica_aroma_wf(template, metadata, mem_gb, omp_nthreads,
                       name='ica_aroma_wf',
+                      susan_fwhm=6.0,
                       ignore_aroma_err=False,
                       aroma_melodic_dim=None,
                       use_fieldwarp=True):
@@ -373,18 +374,23 @@ def init_ica_aroma_wf(template, metadata, mem_gb, omp_nthreads,
 
     The following steps are performed:
 
-    #. Smooth data using SUSAN
-    #. Run MELODIC outside of ICA-AROMA to generate the report
+    #. Smooth data using FSL `susan`, with a kernel width FWHM=6.0mm.
+    #. Run FSL `melodic` outside of ICA-AROMA to generate the report
     #. Run ICA-AROMA
     #. Aggregate identified motion components (aggressive) to TSV
-    #. Return classified_motion_ICs and melodic_mix for user to complete
-        non-aggressive denoising in T1w space
+    #. Return ``classified_motion_ICs`` and ``melodic_mix`` for user to complete
+       non-aggressive denoising in T1w space
     #. Calculate ICA-AROMA-identified noise components
-        (columns named ``AROMAAggrCompXX``)
+       (columns named ``AROMAAggrCompXX``)
 
     Additionally, non-aggressive denoising is performed on the BOLD series
     resampled into MNI space.
 
+    There is a current discussion on whether other confounds should be extracted
+    before or after denoising `here <http://nbviewer.jupyter.org/github/poldracklab/\
+    fmriprep-notebooks/blob/922e436429b879271fa13e76767a6e73443e74d9/issue-817_\
+    aroma_confounds.ipynb>`__.
+
     .. workflow::
         :graph2use: orig
         :simple_form: yes
@@ -411,6 +417,9 @@ def init_ica_aroma_wf(template, metadata, mem_gb, omp_nthreads,
             Maximum number of threads an individual process may use
         name : str
             Name of workflow (default: ``bold_mni_trans_wf``)
+        susan_fwhm : float
+            Kernel width (FWHM in mm) for the smoothing step with
+            FSL ``susan`` (default: 6.0mm)
         use_fieldwarp : bool
             Include SDC warp in single-shot transform from BOLD to MNI
         ignore_aroma_err : bool
@@ -478,7 +487,7 @@ def _getusans_func(image, thresh):
     getusans = pe.Node(niu.Function(function=_getusans_func, output_names=['usans']),
                        name='getusans', mem_gb=0.01)
 
-    smooth = pe.Node(fsl.SUSAN(fwhm=6.0), name='smooth')
+    smooth = pe.Node(fsl.SUSAN(fwhm=susan_fwhm), name='smooth')
 
     # melodic node
     melodic = pe.Node(fsl.MELODIC(

fmriprep/workflows/fieldmap/fmap.py

@@ -13,7 +13,7 @@
 :abbr:`SE (spiral echo)`), we only need to calculate the corresponding B-Spline
 coefficients to adapt the fieldmap to the TOPUP tool.
 This procedure is described with more detail `here <https://cni.stanford.edu/\
-wiki/GE_Processing#Fieldmaps>`_.
+wiki/GE_Processing#Fieldmaps>`__.
 
 This corresponds to the section 8.9.3 --fieldmap image (and one magnitude image)--
 of the BIDS specification.