Merge tag '20.2.0rc1' into halfpipe

20.2.0rc1 With this third minor release series of 2020, the first *fMRIPrep LTS* (*long-term support*) is finally here! This release contains a number of bug-fixes and enhancements mostly related to easing the maintenance, anticipating patch-release breaking changes to ensure a longstanding LTS, and addressing some run-to-run repeatability problems of the CompCor implementation. .. admonition:: Long-Term Support (LTS) *fMRIPrep* 20.2 LTS introduces the `long-term support program <https://www.nipreps.org/devs/releases/#long-term-support-series>`__. This LTS version will be kindly steered and maintained by the group of Dr. Basile Pinsard and Prof. Pierre Bellec at `CRIUGM <http://www.criugm.qc.ca/>`__, (Université de Montréal). The LTS is planned for a window of 4 years of support (i.e., until September 2024). .. caution:: As with all minor version increments, working directories from previous versions **should not be reused**. Thank you for using *fMRIPrep*! If you encounter any issues with this release, please let us know by posting an issue on our GitHub page! A full list of changes can be found below. * FIX: Get missing ``probseg`` file from MNI152NLin2009cAsym (nipreps#2271) * FIX: Restore ``--ignore t2w/flair`` options (nipreps#2260) * FIX: Revise the reproducibility of *CompCor* masks (nipreps#2130) * FIX: Simplify transform aggregation in resampling, pass identity transforms for multi-echo cases (nipreps#2239) * FIX: Skip the T1w check if ``--anat-derivatives`` is provided. (nipreps#2201) * FIX: Storing ``--bids-filters`` within config file (nipreps#2177) * FIX: Revise multi-echo reference generation, permitting using SBRefs too (nipreps#1803) * FIX: *FreeSurfer* license manipulation & canary * ENH: Output CompCor masks if ``--debug compcor`` is passed (nipreps#2248) * ENH: Conform to BIDS Derivatives as of BIDS 1.4.0 (nipreps#2223) * ENH: Reuse config (nipreps#2240) * ENH: Save BOLD-anatomical transforms to derivatives folder (nipreps#2233) * ENH: Leverage BIDSLayout's ``database_path`` (nipreps#2203) * ENH: Add ``--no-tty`` option to ``fmriprep-docker.py`` (nipreps#2204) * ENH: Report number of echoes in BOLD summary. (nipreps#2184) * ENH: Ensure *NiPype* telemetry is just pinged once (nipreps#2168) * DOC: Add FAQ entry for using pre-indexed layouts (nipreps#2256) * DOC: Update reference in "Refinement of Brain Mask" description (nipreps#2215) * DOC: List *TemplateFlow* templates that need to be prefetched (nipreps#2196) * DOC: Update references to https://github.com/nipreps (nipreps#2191) * DOC: Pin *NiPype* with new Sphinx extension syntax (nipreps#2092) * MAINT: Track nipreps#2269 and nipreps#2269, bug-fixes on the 20.1.x series * MAINT: Remove derivatives from layout index ignores (nipreps#2258) * MAINT: Track nipreps#2252 from 20.1.x series (nipreps#2253) * MAINT: Silence *PyBIDS* warning by setting extension mode (nipreps#2250) * MAINT: Drop CircleCI docs build (nipreps#2247) * MAINT: Pin latest *NiPreps* (nipreps#2244) * MAINT: Update ``setup.cfg`` (flake8 and pytest) (nipreps#2183) * MAINT: Delete release-drafter (nipreps#2169) * MAINT: Track bug-fix release on the 20.1.x series (nipreps#2165) * MAINT: Remove auto-comment bot (nipreps#2166) * MAINT: Improve the questions on the bug-report template (nipreps#2158) .. admonition:: Author list for papers based on *fMRIPrep* 20.2 LTS series As described in the `Contributor Guidelines <https://www.nipreps.org/community/CONTRIBUTING/#recognizing-contributions>`__, anyone listed as developer or contributor may write and submit manuscripts about *fMRIPrep*. To do so, please move the author(s) name(s) to the front of the following list: Markiewicz, Christopher J. \ :sup:`1`\ ; Goncalves, Mathias \ :sup:`1`\ ; DuPre, Elizabeth \ :sup:`2`\ ; Kent, James D. \ :sup:`3`\ ; Salo, Taylor \ :sup:`4`\ ; Ciric, Rastko \ :sup:`1`\ ; Pinsard, Basile \ :sup:`5`\ ; Finc, Karolina \ :sup:`6`\ ; de la Vega, Alejandro \ :sup:`7`\ ; Feingold, Franklin \ :sup:`1`\ ; Tooley, Ursula A. \ :sup:`8`\ ; Benson, Noah C. \ :sup:`9`\ ; Urchs, Sebastian \ :sup:`2`\ ; Blair, Ross W. \ :sup:`1`\ ; Erramuzpe, Asier \ :sup:`10`\ ; Lurie, Daniel J. \ :sup:`11`\ ; Heinsfeld, Anibal S. \ :sup:`12`\ ; Jacoby, Nir \ :sup:`13`\ ; Jamison, Keith W. \ :sup:`14`\ ; Frederick, Blaise B. \ :sup:`15, 16`\ ; Valabregue, Romain \ :sup:`17`\ ; Sneve, Markus H. \ :sup:`18`\ ; Liem, Franz \ :sup:`19`\ ; Adebimpe, Azeez \ :sup:`20`\ ; Velasco, Pablo \ :sup:`21`\ ; Wexler, Joseph B. \ :sup:`1`\ ; Groen, Iris I. A. \ :sup:`22`\ ; Ma, Feilong \ :sup:`23`\ ; Amlien, Inge K. \ :sup:`18`\ ; Bellec, Pierre \ :sup:`5`\ ; Cieslak, Matthew \ :sup:`20`\ ; Devenyi, Grabriel A. \ :sup:`24`\ ; Ghosh, Satrajit S. \ :sup:`25, 26`\ ; Gomez, Daniel E. P. \ :sup:`27`\ ; Halchenko, Yaroslav O. \ :sup:`23`\ ; Isik, Ayse Ilkay \ :sup:`28`\ ; Moodie, Craig A. \ :sup:`1`\ ; Naveau, Mikaël \ :sup:`29`\ ; Rivera-Dompenciel, Adriana \ :sup:`3`\ ; Satterthwaite, Theodore D. \ :sup:`20`\ ; Sitek, Kevin R. \ :sup:`30`\ ; Stojić, Hrvoje \ :sup:`31`\ ; Thompson, William H. \ :sup:`1`\ ; Wright, Jessey \ :sup:`1`\ ; Ye, Zhifang \ :sup:`32`\ ; Gorgolewski, Krzysztof J. \ :sup:`1`\ ; Poldrack, Russell A. \ :sup:`1`\ ; Esteban, Oscar \ :sup:`33`\ . Affiliations: 1. Department of Psychology, Stanford University 2. Montreal Neurological Institute, McGill University 3. Neuroscience Program, University of Iowa 4. Department of Psychology, Florida International University 5. SIMEXP Lab, CRIUGM, University of Montréal, Montréal, Canada 6. Centre for Modern Interdisciplinary Technologies, Nicolaus Copernicus University in Toruń 7. University of Texas at Austin 8. Department of Neuroscience, University of Pennsylvania, PA, USA 9. Department of Psychology, New York University 10. Computational Neuroimaging Lab, BioCruces Health Research Institute 11. Department of Psychology, University of California, Berkeley 12. Child Mind Institute 13. Department of Psychology, Columbia University 14. Department of Radiology, Weill Cornell Medicine 15. McLean Hospital Brain Imaging Center, MA, USA 16. Consolidated Department of Psychiatry, Harvard Medical School, MA, USA 17. CENIR, INSERM U1127, CNRS UMR 7225, UPMC Univ Paris 06 UMR S 1127, Institut du Cerveau et de la Moelle épinière, ICM, F-75013, Paris, France 18. Center for Lifespan Changes in Brain and Cognition, University of Oslo 19. URPP Dynamics of Healthy Aging, University of Zurich 20. Perelman School of Medicine, University of Pennsylvania, PA, USA 21. Center for Brain Imaging, New York University 22. Department of Psychology, New York University, NY, USA 23. Dartmouth College: Hanover, NH, United States 24. Department of Psychiatry, McGill University 25. McGovern Institute for Brain Research, MIT, MA, USA 26. Department of Otolaryngology, Harvard Medical School, MA, USA 27. Donders Institute for Brain, Cognition and Behaviour, Radboud University Nijmegen 28. Max Planck Institute for Empirical Aesthetics 29. Cyceron, UMS 3408 (CNRS - UCBN), France 30. Speech & Hearing Bioscience & Technology Program, Harvard University 31. Max Planck UCL Centre for Computational Psychiatry and Ageing Research, University College London 32. State Key Laboratory of Cognitive Neuroscience and Learning, Beijing Normal University 33. Department of Radiology, CHUV, Université de Lausanne
HippocampusGirl · Sep 16, 2020 · 8a1ae2f · 8a1ae2f
2 parents 5177ff5 + 518c774
commit 8a1ae2f
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 16 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -29,26 +29,31 @@ by posting an issue on our GitHub page!
 
 A full list of changes can be found below.
 
-* FIX: Revise the reproducibility of CompCor masks (#2130)
+* FIX: Get missing ``probseg`` file from MNI152NLin2009cAsym (#2271)
+* FIX: Restore ``--ignore t2w/flair`` options (#2260)
+* FIX: Revise the reproducibility of *CompCor* masks (#2130)
 * FIX: Simplify transform aggregation in resampling, pass identity transforms for multi-echo cases (#2239)
 * FIX: Skip the T1w check if ``--anat-derivatives`` is provided. (#2201)
 * FIX: Storing ``--bids-filters`` within config file (#2177)
 * FIX: Revise multi-echo reference generation, permitting using SBRefs too (#1803)
-* FIX: FreeSurfer license manipulation & canary
+* FIX: *FreeSurfer* license manipulation & canary
 * ENH: Output CompCor masks if ``--debug compcor`` is passed (#2248)
 * ENH: Conform to BIDS Derivatives as of BIDS 1.4.0 (#2223)
 * ENH: Reuse config (#2240)
 * ENH: Save BOLD-anatomical transforms to derivatives folder (#2233)
 * ENH: Leverage BIDSLayout's ``database_path`` (#2203)
 * ENH: Add ``--no-tty`` option to ``fmriprep-docker.py`` (#2204)
 * ENH: Report number of echoes in BOLD summary. (#2184)
-* ENH: Ensure NiPype telemetry is just pinged once (#2168)
+* ENH: Ensure *NiPype* telemetry is just pinged once (#2168)
+* DOC: Add FAQ entry for using pre-indexed layouts (#2256)
 * DOC: Update reference in "Refinement of Brain Mask" description (#2215)
 * DOC: List *TemplateFlow* templates that need to be prefetched (#2196)
 * DOC: Update references to https://github.com/nipreps (#2191)
-* DOC: Pin NiPype with new Sphinx extension syntax (#2092)
+* DOC: Pin *NiPype* with new Sphinx extension syntax (#2092)
+* MAINT: Track #2269 and #2269, bug-fixes on the 20.1.x series
+* MAINT: Remove derivatives from layout index ignores (#2258)
 * MAINT: Track #2252 from 20.1.x series (#2253)
-* MAINT: Silence PyBIDS warning by setting extension mode (#2250)
+* MAINT: Silence *PyBIDS* warning by setting extension mode (#2250)
 * MAINT: Drop CircleCI docs build (#2247)
 * MAINT: Pin latest *NiPreps* (#2244)
 * MAINT: Update ``setup.cfg`` (flake8 and pytest) (#2183)
@@ -103,13 +108,21 @@ A full list of changes can be found below.
       32. State Key Laboratory of Cognitive Neuroscience and Learning, Beijing Normal University
       33. Department of Radiology, CHUV, Université de Lausanne
 
+20.1.3 (September 15, 2020)
+===========================
+Bug-fix release in the 20.1.x series.
+
+* FIX: Dependency conflict between *NiWorkflows* and *TemplateFlow* (#2269)
+* FIX: More targetted *TemplateFlow* queries to work with all later releases (#2268)
+* MAINT: Update dependency pinnings including ``niworkflows~=1.2.9`` and three minimal bug-fixes.
+
 20.1.2 (September 04, 2020)
 ===========================
 Bug-fix release in the 20.1.x series.
 
-  * FIX: Revise confounds in confounds-correlation plots (#2252)
-  * FIX: Coerce license path to pathlike (#2180)
-  * DOC: Update new sMRIPrep location (#2211)
+* FIX: Revise confounds in confounds-correlation plots (#2252)
+* FIX: Coerce license path to pathlike (#2180)
+* DOC: Update new sMRIPrep location (#2211)
 
 20.1.1 (June 04, 2020)
 ======================

diff --git a/Dockerfile b/Dockerfile
@@ -165,12 +165,14 @@ RUN python -c "from matplotlib import font_manager" && \
 COPY setup.cfg fmriprep-setup.cfg
 RUN pip install --no-cache-dir "$( grep templateflow fmriprep-setup.cfg | xargs )" && \
     python -c "from templateflow import api as tfapi; \
-               tfapi.get('MNI152NLin6Asym', atlas=None, resolution=[1, 2], \
-                         desc=None, extension=['.nii', '.nii.gz']); \
-               tfapi.get('MNI152NLin6Asym', atlas=None, resolution=[1, 2], \
-                         desc='brain', extension=['.nii', '.nii.gz']); \
-               tfapi.get('MNI152NLin2009cAsym', atlas=None, extension=['.nii', '.nii.gz']); \
-               tfapi.get('OASIS30ANTs', extension=['.nii', '.nii.gz']); \
+               tfapi.get('MNI152NLin6Asym', resolution=(1, 2), suffix='T1w', desc=None); \
+               tfapi.get('MNI152NLin6Asym', resolution=(1, 2), desc='brain', suffix='mask'); \
+               tfapi.get('MNI152NLin2009cAsym', resolution=(1, 2), suffix='T1w', desc=None); \
+               tfapi.get('MNI152NLin2009cAsym', resolution=(1, 2), desc='brain', suffix='mask'); \
+               tfapi.get('MNI152NLin2009cAsym', resolution=1, desc='carpet', suffix='dseg'); \
+               tfapi.get('MNI152NLin2009cAsym', resolution=1, label='brain', suffix='probseg'); \
+               tfapi.get('MNI152NLin2009cAsym', resolution=2, desc='fMRIPrep', suffix='boldref'); \
+               tfapi.get('OASIS30ANTs'); \
                tfapi.get('fsaverage', density='164k', desc='std', suffix='sphere'); \
                tfapi.get('fsaverage', density='164k', desc='vaavg', suffix='midthickness'); \
                tfapi.get('fsLR', density='32k'); \

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -292,3 +292,26 @@ Some examples follow:
     Please check the `link
     <https://neurostars.org/t/fmriprep-how-to-reuse-longitudinal-and-pre-run-freesurfer/4585/15>`__
     for further information on this approach.
+
+
+How to decrease *fMRIPrep* runtime when working with large datasets?
+--------------------------------------------------------------------
+*fMRIPrep* leverages PyBIDS to produce a layout, which indexes the input BIDS dataset and facilitates file queries.
+Depending on the amount of files and metadata within the BIDS dataset, this process can be time-intensive.
+As of the 20.2.0 release, *fMRIPrep* supports the ``--bids-database-dir <database_dir>`` option,
+which can be used to pass in an already indexed BIDS layout.
+
+The default *fMRIPrep* layout can be generated by running the following shell command (requires PyBIDS 0.12.1 or greater)::
+
+  pybids layout <bids_root> <database_dir> --no-validate
+
+where ``<bids_root>`` indicates the root path of the BIDS dataset, and ``<database_dir>``
+is the path where the pre-indexed layout is created - which is then passed into *fMRIPrep*.
+
+By using the ``--force-index`` and ``--ignore`` options,
+finer control can be achieved of what files are visible to fMRIPrep.
+
+Note that any discrepancies between the pre-indexed database and
+the BIDS dataset complicate the provenance of fMRIPrep derivatives.
+If `--bids-database-dir` is used, the referenced directory should be
+preserved for the sake of reporting and reproducibility.
diff --git a/docs/workflows.rst b/docs/workflows.rst
@@ -209,6 +209,10 @@ If T1w voxel sizes are less than 1mm in all dimensions (rounding to nearest
 .1mm), `submillimeter reconstruction`_ is used, unless disabled with
 ``--no-submm-recon``.
 
+If T2w or FLAIR images are available, and you do not want them included in
+FreeSurfer reconstruction, use ``--ignore t2w`` or ``--ignore flair``,
+respectively.
+
 ``lh.midthickness`` and ``rh.midthickness`` surfaces are created in the subject
 ``surf/`` directory, corresponding to the surface half-way between the gray/white
 boundary and the pial surface.

diff --git a/fmriprep/cli/parser.py b/fmriprep/cli/parser.py
@@ -242,7 +242,7 @@ def _bids_filter(value):
         action="store",
         nargs="+",
         default=[],
-        choices=["fieldmaps", "slicetiming", "sbref"],
+        choices=["fieldmaps", "slicetiming", "sbref", "t2w", "flair"],
         help="ignore selected aspects of the input dataset to disable corresponding "
         "parts of the workflow (a space delimited list)",
     )

diff --git a/fmriprep/config.py b/fmriprep/config.py
@@ -445,7 +445,6 @@ def init(cls):
                     "stimuli",
                     "sourcedata",
                     "models",
-                    "derivatives",
                     re.compile(r"^\."),
                 ),
             )