From 1c43d0daa73bdc84715132cc9595f78ffd636373 Mon Sep 17 00:00:00 2001 From: oesteban Date: Wed, 24 Apr 2019 12:42:13 -0700 Subject: [PATCH 01/24] ref(cli,workflows): Allow multiple standard spaces This is a large refactor using two major inter-related features: - Uses poldracklab/smriprep#72 and its continuation within poldracklab/smriprep#75 to permit the specification of several spatial normalization targets (close #1558). - Uses the refactor of Reports generation of poldracklab/niworkflows#344, which enables rendering reports with several normalization spaces. Correspondingly, report generation code and config files have been removed. Correspondingly, the new interface for ``--output-spaces`` is also incorporated (close #1588). --- docs/usage.rst | 101 +++++ docs/workflows.rst | 6 +- fmriprep/__about__.py | 4 +- fmriprep/cli/run.py | 499 ++++++++------------- fmriprep/interfaces/reports.py | 45 +- fmriprep/utils/bids.py | 88 ++++ fmriprep/utils/sentry.py | 209 +++++++++ fmriprep/viz/__init__.py | 8 - fmriprep/viz/config.json | 151 ------- fmriprep/viz/report.tpl | 186 -------- fmriprep/viz/reports.py | 366 ---------------- fmriprep/workflows/base.py | 427 ++++++++++-------- fmriprep/workflows/bold/__init__.py | 4 +- fmriprep/workflows/bold/base.py | 547 ++++++++---------------- fmriprep/workflows/bold/confounds.py | 96 ++--- fmriprep/workflows/bold/outputs.py | 226 ++++++++++ fmriprep/workflows/bold/registration.py | 6 +- fmriprep/workflows/bold/resampling.py | 292 +++++++------ fmriprep/workflows/fieldmap/__init__.py | 8 + fmriprep/workflows/fieldmap/base.py | 28 +- fmriprep/workflows/fieldmap/fmap.py | 2 +- fmriprep/workflows/fieldmap/phdiff.py | 3 +- fmriprep/workflows/fieldmap/syn.py | 8 +- fmriprep/workflows/fieldmap/unwarp.py | 12 +- requirements.txt | 4 +- setup.py | 2 - 26 files changed, 1525 insertions(+), 1803 deletions(-) create mode 100644 fmriprep/utils/sentry.py delete mode 100644 fmriprep/viz/__init__.py delete mode 100644 fmriprep/viz/config.json delete mode 100644 fmriprep/viz/report.tpl delete mode 100644 fmriprep/viz/reports.py create mode 100644 fmriprep/workflows/bold/outputs.py diff --git a/docs/usage.rst b/docs/usage.rst index 30fadd453..8dd0f9563 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -37,6 +37,107 @@ Command-Line Arguments :nodefault: :nodefaultconst: +Defining standard and nonstandard spaces where data will be resampled +===================================================================== + +The command line interface of fMRIPrep allows resampling the preprocessed data +onto other output spaces. +That is achieved using the ``--output-spaces`` argument, where standard and +nonstandard spaces can be inserted. + +Standard spaces +--------------- + +When using fMRIPrep in a workflow that will investigate effects that span across +analytical groupings, neuroimagers typically resample their data on to a standard, +stereotactic coordinate system. +The most extended standard space for fMRI analyses is generally referred to MNI. +For instance, to instruct fMRIPrep to use the MNI template brain distributed with +FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym``. +By default, fMRIPrep uses ``MNI152NLin2009cAsym`` as spatial-standardization reference. +Valid template identifiers (``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, etc.) come from +the `TemplateFlow project `__. + +Therefore, fMRIPrep will run nonlinear registration processes against the template +T1w image corresponding to all the standard spaces supplied with the argument +``--output-spaces``. +By default, fMRIPrep will resample the preprocessed data on those spaces (labeling the +corresponding outputs with the `space-` BIDS entity) but keeping +the original resolution of the BOLD data to produce smaller files, more consistent with +the original data gridding. +However, many users will be interested in utilizing a coarse gridding (typically 2mm isotropic) +of the target template. +Such a behavior can be achieved applying modifiers to the template identifier, separated by +a ``:`` character. +For instance, ``--output-spaces MNI152NLin6Asym:res-2 MNI152NLin2009cAsym`` will generate +preprocessed BOLD 4D files on two standard spaces (``MNI152NLin6Asym``, +and ``MNI152NLin2009cAsym``) with the template's 2mm isotropic resolution for +the data on ``MNI152NLin6Asym`` space and the original BOLD resolution +(say, e.g., 2x2x2.5 [mm]) for the case of ``MNI152NLin2009cAsym``. + +Other possible modifiers are, for instance, the ``cohort`` selector. +Although currently there is no template in TemplateFlow with several cohorts, +very soon we will integrate pediatric templates, for which ``cohort`` will +function to select the appropriate age range. +Therefore, in upcoming versions of fMRIPrep, it will be possible to run it with +``--output-spaces MNIPediatricAsym:res-2:cohort-2`` where ``cohort-2`` would select +the template instance for the, say, 24-48 months old range. + +When specifying surface spaces (e.g. ``fsaverage``), the legacy identifiers from +FreeSurfer will be supported (e.g. ``fsaverage5``) although the use of the density +modifier would be preferred (i.e. ``fsaverage:den-10k`` for ``fsaverage5``). + +Custom standard spaces +---------------------- + +Although the functionality is not available yet, the interface of the +``--output-spaces`` permits providing paths to custom templates that +follow TemplateFlow's naming conventions +(e.g. ``/path/to/custom/templates/tpl-MyCustom:res-2``). +Following the example, at least the following files +must be found under under ``/path/to/custom/templates/tpl-MyCustom``: :: + + tpl-MyCustom/ + template_description.json + tpl-MyCustom_res-1_T1w.nii.gz + tpl-MyCustom_res-1_desc-brain_mask.nii.gz + tpl-MyCustom_res-2_T1w.nii.gz + tpl-MyCustom_res-2_desc-brain_mask.nii.gz + +Although a more comprehensive coverage of standard files would be advised. + +Nonstandard spaces +------------------ + +Additionally, ``--output-spaces`` accepts identifiers of spatial references +that do not generate *standardized* coordinate spaces: + + * ``T1w`` or ``anat``: data are resampled into the individual's anatomical + reference generated with the T1w and T2w images available within the + BIDS structure. + * ``fsnative``: similarly to the ``anat`` space for volumetric references, + including the ``fsnative`` space will instruct fMRIPrep to sample the + original BOLD data onto FreeSurfer's reconstructed surfaces for this + individual. + * **Additional nonstandard spaces** that will be supported in the future are + ``run``, ``func``, and ``sbref``. + +Modifiers are not allowed when providing nonstandard spaces. + +Preprocessing blocks depending on standard templates +---------------------------------------------------- + +Some modules of the pipeline (e.g. the ICA-AROMA denoising, the generation of +HCP compatible *grayordinates* files, or the *fieldmap-less* distortion correction) +perform on specific template spaces. +When selecting those modules to be included (using any of the following flags: +``--use-aroma``, ``--cifti-outputs``, ``--use-syn-sdc``) will modify the list of +output spaces to include the space identifiers they require, should the +identifier not be found within the ``--output-spaces`` list already. +In other words, running fMRIPrep with ``--output-spaces MNI152NLin6Asym:res-2 +--use-syn-sdc`` will expand the list of output spaces to be +``MNI152NLin6Asym:res-2 MNI152NLin2009cAsym``. + The docker wrapper CLI ====================== diff --git a/docs/workflows.rst b/docs/workflows.rst index 358b558ff..ff015539c 100644 --- a/docs/workflows.rst +++ b/docs/workflows.rst @@ -472,14 +472,14 @@ Excessive deviation will result in rejecting the BBR refinement and accepting th EPI to MNI transformation ~~~~~~~~~~~~~~~~~~~~~~~~~ -:mod:`fmriprep.workflows.bold.resampling.init_bold_mni_trans_wf` +:mod:`fmriprep.workflows.bold.resampling.init_bold_std_trans_wf` .. workflow:: :graph2use: colored :simple_form: yes - from fmriprep.workflows.bold import init_bold_mni_trans_wf - wf = init_bold_mni_trans_wf( + from fmriprep.workflows.bold import init_bold_std_trans_wf + wf = init_bold_std_trans_wf( template='MNI152NLin2009cAsym', freesurfer=True, mem_gb=1, diff --git a/fmriprep/__about__.py b/fmriprep/__about__.py index fd3d2f9f7..f0a5d46c7 100644 --- a/fmriprep/__about__.py +++ b/fmriprep/__about__.py @@ -105,8 +105,8 @@ LINKS_REQUIRES = [ 'git+https://github.com/poldracklab/niworkflows.git@' - 'b7d111c8fd36a099c74be5e7671677eedb175533#egg=niworkflows', - 'git+https://github.com/poldracklab/smriprep.git@' + 'unstable#egg=niworkflows', + 'git+https://github.com/poldracklab/unstable.git@' '423bcc43ab7300177eb3b98da62817b2cad8eb87#egg=smriprep-0.1.0', ] diff --git a/fmriprep/cli/run.py b/fmriprep/cli/run.py index ec0cdf2c3..ac13ebfd8 100755 --- a/fmriprep/cli/run.py +++ b/fmriprep/cli/run.py @@ -11,19 +11,12 @@ import logging import sys import gc -import re import uuid -import json -import tempfile -import psutil -import hashlib import warnings -import subprocess from argparse import ArgumentParser from argparse import RawTextHelpFormatter from multiprocessing import cpu_count from time import strftime -from glob import glob logging.addLevelName(25, 'IMPORTANT') # Add a new level between INFO and WARNING logging.addLevelName(15, 'VERBOSE') # Add a new level between INFO and DEBUG @@ -45,7 +38,10 @@ def check_deps(workflow): def get_parser(): """Build parser object""" + from smriprep.cli.utils import ParseTemplates + from templateflow.api import templates from ..__about__ import __version__ + from ..workflows.bold.resampling import NONSTANDARD_REFERENCES verstr = 'fmriprep v{}'.format(__version__) @@ -131,43 +127,47 @@ def get_parser(): 'T2*-driven coregistration. When multi-echo data is provided and this ' 'option is not enabled, standard EPI-T1 coregistration is performed ' 'using the middle echo.') - g_conf.add_argument('--bold2t1w-dof', action='store', default=6, choices=[6, 9, 12], type=int, - help='Degrees of freedom when registering BOLD to T1w images. ' - '6 degrees (rotation and translation) are used by default.') g_conf.add_argument( - '--output-space', required=False, action='store', + '--output-spaces', nargs='+', action=ParseTemplates, + help="""\ +Paths or keywords prescribing standard spaces to which normalize the input T1w image \ +and nonstandard spaces in which BOLD runs will be resampled (valid keywords are: \ +%s and paths poing to templates) with modifiers (optional parameters). +Output spaces may be templates with modifiers or dataset-specific references. \ +Templates take the form ``