def init_single_subject_wf(
anat_only,
aroma_melodic_dim,
bold2t1w_dof,
cifti_output,
debug,
dummy_scans,
echo_idx,
err_on_aroma_warn,
fmap_bspline,
fmap_demean,
force_syn,
freesurfer,
hires,
ignore,
layout,
longitudinal,
low_mem,
medial_surface_nan,
name,
omp_nthreads,
output_dir,
reportlets_dir,
regressors_all_comps,
regressors_dvars_th,
regressors_fd_th,
skull_strip_fixed_seed,
skull_strip_template,
spaces,
subject_id,
t2s_coreg,
task_id,
use_aroma,
use_bbr,
use_syn,
):
"""
This workflow organizes the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and functional preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Functional preprocessing is performed using a separate workflow for each
individual BOLD series.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from collections import namedtuple
from niworkflows.utils.spaces import Reference, SpatialReferences
from fmriprep.workflows.base import init_single_subject_wf
BIDSLayout = namedtuple('BIDSLayout', ['root'])
wf = init_single_subject_wf(
anat_only=False,
aroma_melodic_dim=-200,
bold2t1w_dof=9,
cifti_output=False,
debug=False,
dummy_scans=None,
echo_idx=None,
err_on_aroma_warn=False,
fmap_bspline=False,
fmap_demean=True,
force_syn=True,
freesurfer=True,
hires=True,
ignore=[],
layout=BIDSLayout('.'),
longitudinal=False,
low_mem=False,
medial_surface_nan=False,
name='single_subject_wf',
omp_nthreads=1,
output_dir='.',
reportlets_dir='.',
regressors_all_comps=False,
regressors_dvars_th=1.5,
regressors_fd_th=0.5,
skull_strip_fixed_seed=False,
skull_strip_template=Reference('OASIS30ANTs'),
spaces=SpatialReferences(
spaces=['MNI152Lin',
('fsaverage', {'density': '10k'}),
'T1w',
'fsnative'],
checkpoint=True),
subject_id='test',
t2s_coreg=False,
task_id='',
use_aroma=False,
use_bbr=True,
use_syn=True,
)
Parameters
----------
anat_only : bool
Disable functional workflows
aroma_melodic_dim : int
Maximum number of components identified by MELODIC within ICA-AROMA
(default is -200, i.e., no limitation).
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
cifti_output : bool
Generate bold CIFTI file in output spaces
debug : bool
Enable debugging outputs
dummy_scans : int or None
Number of volumes to consider as non steady state
echo_idx : int or None
Index of echo to preprocess in multiecho BOLD series,
or ``None`` to preprocess all
err_on_aroma_warn : bool
Do not fail on ICA-AROMA errors
fmap_bspline : bool
**Experimental**: Fit B-Spline field using least-squares
fmap_demean : bool
Demean voxel-shift map during unwarp
force_syn : bool
**Temporary**: Always run SyN-based SDC
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
ignore : list
Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
layout : BIDSLayout object
BIDS dataset layout
longitudinal : bool
Treat multiple sessions as longitudinal (may increase runtime)
See sub-workflows for specific differences
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
name : str
Name of workflow
omp_nthreads : int
Maximum number of threads an individual process may use
output_dir : str
Directory in which to save derivatives
reportlets_dir : str
Directory in which to save reportlets
regressors_all_comps
Return all CompCor component time series instead of the top fraction
regressors_fd_th
Criterion for flagging framewise displacement outliers
regressors_dvars_th
Criterion for flagging DVARS outliers
skull_strip_fixed_seed : bool
Do not use a random seed for skull-stripping - will ensure
run-to-run replicability when used with --omp-nthreads 1
skull_strip_template : tuple
Name of target template for brain extraction with ANTs' ``antsBrainExtraction``,
and corresponding dictionary of output-space modifiers.
subject_id : str
List of subject labels
t2s_coreg : bool
For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration
spaces : :py:class:`~niworkflows.utils.spaces.SpatialReferences`
A container for storing, organizing, and parsing spatial normalizations. Composed of
:py:class:`~niworkflows.utils.spaces.Reference` objects representing spatial references.
Each ``Reference`` contains a space, which is a string of either TemplateFlow template IDs
(e.g., ``MNI152Lin``, ``MNI152NLin6Asym``, ``MNIPediatricAsym``), nonstandard references
(e.g., ``T1w`` or ``anat``, ``sbref``, ``run``, etc.), or a custom template located in
the TemplateFlow root directory. Each ``Reference`` may also contain a spec, which is a
dictionary with template specifications (e.g., a specification of ``{'resolution': 2}``
would lead to resampling on a 2mm resolution of the space).
task_id : str or None
Task ID of BOLD series to preprocess, or ``None`` to preprocess all
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
use_bbr : bool or None
Enable/disable boundary-based registration refinement.
If ``None``, test BBR result for distortion before accepting.
use_syn : bool
**Experimental**: Enable ANTs SyN-based susceptibility distortion correction (SDC).
If fieldmaps are present and enabled, this is not run, by default.
Inputs
------
subjects_dir : str
FreeSurfer's ``$SUBJECTS_DIR``.
"""
if name in ('single_subject_wf', 'single_subject_fmripreptest_wf'):
# for documentation purposes
subject_data = {
't1w': ['/completely/made/up/path/sub-01_T1w.nii.gz'],
'bold': ['/completely/made/up/path/sub-01_task-nback_bold.nii.gz']
}
else:
subject_data = collect_data(layout, subject_id, task_id, echo_idx)[0]
# Make sure we always go through these two checks
if not anat_only and subject_data['bold'] == []:
raise Exception("No BOLD images found for participant {} and task {}. "
"All workflows require BOLD images.".format(
subject_id, task_id if task_id else '<all>'))
if not subject_data['t1w']:
raise Exception("No T1w images found for participant {}. "
"All workflows require T1w images.".format(subject_id))
workflow = Workflow(name=name)
workflow.__desc__ = """
Results included in this manuscript come from preprocessing
performed using *fMRIPrep* {fmriprep_ver}
(@fmriprep1; @fmriprep2; RRID:SCR_016216),
which is based on *Nipype* {nipype_ver}
(@nipype1; @nipype2; RRID:SCR_002502).
""".format(fmriprep_ver=__version__, nipype_ver=nipype_ver)
workflow.__postdesc__ = """
Many internal operations of *fMRIPrep* use
*Nilearn* {nilearn_ver} [@nilearn, RRID:SCR_001362],
mostly within the functional processing workflow.
For more details of the pipeline, see [the section corresponding
to workflows in *fMRIPrep*'s documentation]\
(https://fmriprep.readthedocs.io/en/latest/workflows.html \
"FMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by fMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
""".format(nilearn_ver=NILEARN_VERSION)
inputnode = pe.Node(niu.IdentityInterface(fields=['subjects_dir']),
name='inputnode')
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data, anat_only=anat_only),
name='bidssrc')
bids_info = pe.Node(BIDSInfo(
bids_dir=layout.root, bids_validate=False), name='bids_info')
summary = pe.Node(SubjectSummary(std_spaces=spaces.get_spaces(nonstandard=False),
nstd_spaces=spaces.get_spaces(standard=False)),
name='summary', run_without_submitting=True)
about = pe.Node(AboutSummary(version=__version__,
command=' '.join(sys.argv)),
name='about', run_without_submitting=True)
ds_report_summary = pe.Node(
DerivativesDataSink(base_directory=reportlets_dir,
desc='summary', keep_dtype=True),
name='ds_report_summary', run_without_submitting=True)
ds_report_about = pe.Node(
DerivativesDataSink(base_directory=reportlets_dir,
desc='about', keep_dtype=True),
name='ds_report_about', run_without_submitting=True)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=layout.root,
debug=debug,
freesurfer=freesurfer,
hires=hires,
longitudinal=longitudinal,
name="anat_preproc_wf",
num_t1w=len(subject_data['t1w']),
omp_nthreads=omp_nthreads,
output_dir=output_dir,
reportlets_dir=reportlets_dir,
spaces=spaces,
skull_strip_fixed_seed=skull_strip_fixed_seed,
skull_strip_template=skull_strip_template,
)
workflow.connect([
(inputnode, anat_preproc_wf, [('subjects_dir', 'inputnode.subjects_dir')]),
(bidssrc, bids_info, [(('t1w', fix_multi_T1w_source_name), 'in_file')]),
(inputnode, summary, [('subjects_dir', 'subjects_dir')]),
(bidssrc, summary, [('t1w', 't1w'),
('t2w', 't2w'),
('bold', 'bold')]),
(bids_info, summary, [('subject', 'subject_id')]),
(bids_info, anat_preproc_wf, [(('subject', _prefix), 'inputnode.subject_id')]),
(bidssrc, anat_preproc_wf, [('t1w', 'inputnode.t1w'),
('t2w', 'inputnode.t2w'),
('roi', 'inputnode.roi'),
('flair', 'inputnode.flair')]),
(bidssrc, ds_report_summary, [(('t1w', fix_multi_T1w_source_name), 'source_file')]),
(summary, ds_report_summary, [('out_report', 'in_file')]),
(bidssrc, ds_report_about, [(('t1w', fix_multi_T1w_source_name), 'source_file')]),
(about, ds_report_about, [('out_report', 'in_file')]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_'):
workflow.get_node(node).interface.out_path_base = 'fmriprep'
if anat_only:
return workflow
for bold_file in subject_data['bold']:
func_preproc_wf = init_func_preproc_wf(
aroma_melodic_dim=aroma_melodic_dim,
bold2t1w_dof=bold2t1w_dof,
bold_file=bold_file,
cifti_output=cifti_output,
debug=debug,
dummy_scans=dummy_scans,
err_on_aroma_warn=err_on_aroma_warn,
fmap_bspline=fmap_bspline,
fmap_demean=fmap_demean,
force_syn=force_syn,
freesurfer=freesurfer,
ignore=ignore,
layout=layout,
low_mem=low_mem,
medial_surface_nan=medial_surface_nan,
num_bold=len(subject_data['bold']),
omp_nthreads=omp_nthreads,
output_dir=output_dir,
reportlets_dir=reportlets_dir,
regressors_all_comps=regressors_all_comps,
regressors_fd_th=regressors_fd_th,
regressors_dvars_th=regressors_dvars_th,
spaces=spaces,
t2s_coreg=t2s_coreg,
use_aroma=use_aroma,
use_bbr=use_bbr,
use_syn=use_syn,
)
workflow.connect([
(anat_preproc_wf, func_preproc_wf,
[(('outputnode.t1w_preproc', _pop), 'inputnode.t1w_preproc'),
('outputnode.t1w_brain', 'inputnode.t1w_brain'),
('outputnode.t1w_mask', 'inputnode.t1w_mask'),
('outputnode.t1w_dseg', 'inputnode.t1w_dseg'),
('outputnode.t1w_aseg', 'inputnode.t1w_aseg'),
('outputnode.t1w_aparc', 'inputnode.t1w_aparc'),
('outputnode.t1w_tpms', 'inputnode.t1w_tpms'),
('outputnode.template', 'inputnode.template'),
('outputnode.anat2std_xfm', 'inputnode.anat2std_xfm'),
('outputnode.std2anat_xfm', 'inputnode.std2anat_xfm'),
('outputnode.joint_template', 'inputnode.joint_template'),
('outputnode.joint_anat2std_xfm', 'inputnode.joint_anat2std_xfm'),
('outputnode.joint_std2anat_xfm', 'inputnode.joint_std2anat_xfm'),
# Undefined if --fs-no-reconall, but this is safe
('outputnode.subjects_dir', 'inputnode.subjects_dir'),
('outputnode.subject_id', 'inputnode.subject_id'),
('outputnode.t1w2fsnative_xfm', 'inputnode.t1w2fsnative_xfm'),
('outputnode.fsnative2t1w_xfm', 'inputnode.fsnative2t1w_xfm')]),
])
return workflow
def init_single_subject_wf(
layout, subject_id, task_id, echo_idx, name, reportlets_dir,
output_dir, ignore, debug, low_mem, anat_only, longitudinal, t2s_coreg,
omp_nthreads, skull_strip_template, skull_strip_fixed_seed, freesurfer,
output_spaces, template, medial_surface_nan, cifti_output, hires,
use_bbr, bold2t1w_dof, fmap_bspline, fmap_demean, use_syn, force_syn,
template_out_grid, use_aroma, aroma_melodic_dim, err_on_aroma_warn):
"""
This workflow organizes the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and functional preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Functional preprocessing is performed using a separate workflow for each
individual BOLD series.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.base import init_single_subject_wf
from collections import namedtuple
BIDSLayout = namedtuple('BIDSLayout', ['root'], defaults='.')
wf = init_single_subject_wf(layout=BIDSLayout(),
subject_id='test',
task_id='',
echo_idx=None,
name='single_subject_wf',
reportlets_dir='.',
output_dir='.',
ignore=[],
debug=False,
low_mem=False,
anat_only=False,
longitudinal=False,
t2s_coreg=False,
omp_nthreads=1,
skull_strip_template='OASIS30ANTs',
skull_strip_fixed_seed=False,
freesurfer=True,
template='MNI152NLin2009cAsym',
output_spaces=['T1w', 'fsnative',
'template', 'fsaverage5'],
medial_surface_nan=False,
cifti_output=False,
hires=True,
use_bbr=True,
bold2t1w_dof=9,
fmap_bspline=False,
fmap_demean=True,
use_syn=True,
force_syn=True,
template_out_grid='native',
use_aroma=False,
aroma_melodic_dim=-200,
err_on_aroma_warn=False)
Parameters
layout : BIDSLayout object
BIDS dataset layout
subject_id : str
List of subject labels
task_id : str or None
Task ID of BOLD series to preprocess, or ``None`` to preprocess all
echo_idx : int or None
Index of echo to preprocess in multiecho BOLD series,
or ``None`` to preprocess all
name : str
Name of workflow
ignore : list
Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
debug : bool
Enable debugging outputs
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
anat_only : bool
Disable functional workflows
longitudinal : bool
Treat multiple sessions as longitudinal (may increase runtime)
See sub-workflows for specific differences
t2s_coreg : bool
For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration
omp_nthreads : int
Maximum number of threads an individual process may use
skull_strip_template : str
Name of ANTs skull-stripping template ('OASIS30ANTs' or 'NKI')
skull_strip_fixed_seed : bool
Do not use a random seed for skull-stripping - will ensure
run-to-run replicability when used with --omp-nthreads 1
reportlets_dir : str
Directory in which to save reportlets
output_dir : str
Directory in which to save derivatives
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
output_spaces : list
List of output spaces functional images are to be resampled to.
Some parts of pipeline will only be instantiated for some output spaces.
Valid spaces:
- T1w
- template
- fsnative
- fsaverage (or other pre-existing FreeSurfer templates)
template : str
Name of template targeted by ``template`` output space
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
cifti_output : bool
Generate bold CIFTI file in output spaces
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
use_bbr : bool or None
Enable/disable boundary-based registration refinement.
If ``None``, test BBR result for distortion before accepting.
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
fmap_bspline : bool
**Experimental**: Fit B-Spline field using least-squares
fmap_demean : bool
Demean voxel-shift map during unwarp
use_syn : bool
**Experimental**: Enable ANTs SyN-based susceptibility distortion correction (SDC).
If fieldmaps are present and enabled, this is not run, by default.
force_syn : bool
**Temporary**: Always run SyN-based SDC
template_out_grid : str
Keyword ('native', '1mm' or '2mm') or path of custom reference
image for normalization
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
err_on_aroma_warn : bool
Do not fail on ICA-AROMA errors
Inputs
subjects_dir
FreeSurfer SUBJECTS_DIR
"""
if name in ('single_subject_wf', 'single_subject_fmripreptest_wf'):
# for documentation purposes
subject_data = {
't1w': ['/completely/made/up/path/sub-01_T1w.nii.gz'],
'bold': ['/completely/made/up/path/sub-01_task-nback_bold.nii.gz']
}
else:
subject_data = collect_data(layout, subject_id, task_id, echo_idx)[0]
# Make sure we always go through these two checks
if not anat_only and subject_data['bold'] == []:
raise Exception("No BOLD images found for participant {} and task {}. "
"All workflows require BOLD images.".format(
subject_id, task_id if task_id else '<all>'))
if not subject_data['t1w']:
raise Exception("No T1w images found for participant {}. "
"All workflows require T1w images.".format(subject_id))
workflow = Workflow(name=name)
workflow.__desc__ = """
Results included in this manuscript come from preprocessing
performed using *fMRIPrep* {fmriprep_ver}
(@fmriprep1; @fmriprep2; RRID:SCR_016216),
which is based on *Nipype* {nipype_ver}
(@nipype1; @nipype2; RRID:SCR_002502).
""".format(fmriprep_ver=__version__, nipype_ver=nipype_ver)
workflow.__postdesc__ = """
Many internal operations of *fMRIPrep* use
*Nilearn* {nilearn_ver} [@nilearn, RRID:SCR_001362],
mostly within the functional processing workflow.
For more details of the pipeline, see [the section corresponding
to workflows in *fMRIPrep*'s documentation]\
(https://fmriprep.readthedocs.io/en/latest/workflows.html \
"FMRIPrep's documentation").
### References
""".format(nilearn_ver=nilearn_ver)
inputnode = pe.Node(niu.IdentityInterface(fields=['subjects_dir']),
name='inputnode')
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only),
name='bidssrc')
bids_info = pe.Node(BIDSInfo(bids_dir=layout.root, bids_validate=False),
name='bids_info')
summary = pe.Node(SubjectSummary(output_spaces=output_spaces,
template=template),
name='summary',
run_without_submitting=True)
about = pe.Node(AboutSummary(version=__version__,
command=' '.join(sys.argv)),
name='about',
run_without_submitting=True)
ds_report_summary = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, suffix='summary'),
name='ds_report_summary',
run_without_submitting=True)
ds_report_about = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, suffix='about'),
name='ds_report_about',
run_without_submitting=True)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=layout.root,
debug=debug,
freesurfer=freesurfer,
fs_spaces=output_spaces,
hires=hires,
longitudinal=longitudinal,
name="anat_preproc_wf",
num_t1w=len(subject_data['t1w']),
omp_nthreads=omp_nthreads,
output_dir=output_dir,
reportlets_dir=reportlets_dir,
skull_strip_fixed_seed=skull_strip_fixed_seed,
skull_strip_template=skull_strip_template,
template=template,
)
workflow.connect([
(inputnode, anat_preproc_wf, [('subjects_dir',
'inputnode.subjects_dir')]),
(bidssrc, bids_info, [(('t1w', fix_multi_T1w_source_name), 'in_file')
]),
(inputnode, summary, [('subjects_dir', 'subjects_dir')]),
(bidssrc, summary, [('t1w', 't1w'), ('t2w', 't2w'), ('bold', 'bold')]),
(bids_info, summary, [('subject', 'subject_id')]),
(bids_info, anat_preproc_wf, [(('subject', _prefix),
'inputnode.subject_id')]),
(bidssrc, anat_preproc_wf, [('t1w', 'inputnode.t1w'),
('t2w', 'inputnode.t2w'),
('roi', 'inputnode.roi'),
('flair', 'inputnode.flair')]),
(bidssrc, ds_report_summary, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(summary, ds_report_summary, [('out_report', 'in_file')]),
(bidssrc, ds_report_about, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(about, ds_report_about, [('out_report', 'in_file')]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_'):
workflow.get_node(node).interface.out_path_base = 'fmriprep'
if anat_only:
return workflow
for bold_file in subject_data['bold']:
func_preproc_wf = init_func_preproc_wf(
bold_file=bold_file,
layout=layout,
ignore=ignore,
freesurfer=freesurfer,
use_bbr=use_bbr,
t2s_coreg=t2s_coreg,
bold2t1w_dof=bold2t1w_dof,
reportlets_dir=reportlets_dir,
output_spaces=output_spaces,
template=template,
medial_surface_nan=medial_surface_nan,
cifti_output=cifti_output,
output_dir=output_dir,
omp_nthreads=omp_nthreads,
low_mem=low_mem,
fmap_bspline=fmap_bspline,
fmap_demean=fmap_demean,
use_syn=use_syn,
force_syn=force_syn,
debug=debug,
template_out_grid=template_out_grid,
use_aroma=use_aroma,
aroma_melodic_dim=aroma_melodic_dim,
err_on_aroma_warn=err_on_aroma_warn,
num_bold=len(subject_data['bold']))
workflow.connect([
(
anat_preproc_wf,
func_preproc_wf,
[
(('outputnode.t1_preproc', _pop), 'inputnode.t1_preproc'),
('outputnode.t1_brain', 'inputnode.t1_brain'),
('outputnode.t1_mask', 'inputnode.t1_mask'),
('outputnode.t1_seg', 'inputnode.t1_seg'),
('outputnode.t1_aseg', 'inputnode.t1_aseg'),
('outputnode.t1_aparc', 'inputnode.t1_aparc'),
('outputnode.t1_tpms', 'inputnode.t1_tpms'),
('outputnode.t1_2_mni_forward_transform',
'inputnode.t1_2_mni_forward_transform'),
('outputnode.t1_2_mni_reverse_transform',
'inputnode.t1_2_mni_reverse_transform'),
# Undefined if --no-freesurfer, but this is safe
('outputnode.subjects_dir', 'inputnode.subjects_dir'),
('outputnode.subject_id', 'inputnode.subject_id'),
('outputnode.t1_2_fsnative_forward_transform',
'inputnode.t1_2_fsnative_forward_transform'),
('outputnode.t1_2_fsnative_reverse_transform',
'inputnode.t1_2_fsnative_reverse_transform')
]),
])
return workflow
def init_single_subject_wf(
anat_only,
debug,
force_syn,
freesurfer,
hires,
ignore,
layout,
longitudinal,
low_mem,
name,
omp_nthreads,
output_dir,
output_spaces,
reportlets_dir,
skull_strip_fixed_seed,
skull_strip_template,
subject_id,
use_syn,
):
"""
Set-up the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and diffusion MRI preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Diffusion MRI preprocessing is performed using a separate workflow for
a full :abbr:`DWI (diffusion weighted imaging)` *entity*.
A DWI *entity* may comprehend one or several runs (for instance, two
opposed :abbr:`PE (phase-encoding)` directions.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from dmriprep.workflows.base import init_single_subject_wf
from collections import namedtuple, OrderedDict
BIDSLayout = namedtuple('BIDSLayout', ['root'])
wf = init_single_subject_wf(
anat_only=False,
debug=False,
force_syn=True,
freesurfer=True,
hires=True,
ignore=[],
layout=BIDSLayout('.'),
longitudinal=False,
low_mem=False,
name='single_subject_wf',
omp_nthreads=1,
output_dir='.',
output_spaces=OrderedDict([
('MNI152Lin', {}), ('fsaverage', {'density': '10k'}),
('T1w', {}), ('fsnative', {})]),
reportlets_dir='.',
skull_strip_fixed_seed=False,
skull_strip_template=('OASIS30ANTs', {}),
subject_id='test',
use_syn=True,
)
Parameters
----------
anat_only : bool
Disable diffusion MRI workflows
debug : bool
Enable debugging outputs
force_syn : bool
**Temporary**: Always run SyN-based SDC
freesurfer : bool
Enable FreeSurfer surface reconstruction (may increase runtime)
hires : bool
Enable sub-millimeter preprocessing in FreeSurfer
ignore : list
Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
layout : BIDSLayout object
BIDS dataset layout
longitudinal : bool
Treat multiple sessions as longitudinal (may increase runtime)
See sub-workflows for specific differences
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
name : str
Name of workflow
omp_nthreads : int
Maximum number of threads an individual process may use
output_dir : str
Directory in which to save derivatives
output_spaces : OrderedDict
Ordered dictionary where keys are TemplateFlow ID strings (e.g., ``MNI152Lin``,
``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, or ``fsLR``) strings designating
nonstandard references (e.g., ``T1w`` or ``anat``, ``sbref``, ``run``, etc.),
or paths pointing to custom templates organized in a TemplateFlow-like structure.
Values of the dictionary aggregate modifiers (e.g., the value for the key ``MNI152Lin``
could be ``{'resolution': 2}`` if one wants the resampling to be done on the 2mm
resolution version of the selected template).
reportlets_dir : str
Directory in which to save reportlets
skull_strip_fixed_seed : bool
Do not use a random seed for skull-stripping - will ensure
run-to-run replicability when used with --omp-nthreads 1
skull_strip_template : tuple
Name of target template for brain extraction with ANTs' ``antsBrainExtraction``,
and corresponding dictionary of output-space modifiers.
subject_id : str
List of subject labels
use_syn : bool
**Experimental**: Enable ANTs SyN-based susceptibility distortion correction (SDC).
If fieldmaps are present and enabled, this is not run, by default.
Inputs
------
subjects_dir : os.pathlike
FreeSurfer's ``$SUBJECTS_DIR``
"""
from ..config import NONSTANDARD_REFERENCES
if name in ('single_subject_wf', 'single_subject_dmripreptest_wf'):
# for documentation purposes
subject_data = {
't1w': ['/completely/made/up/path/sub-01_T1w.nii.gz'],
'dwi': ['/completely/made/up/path/sub-01_dwi.nii.gz']
}
else:
subject_data = collect_data(layout, subject_id)[0]
# Make sure we always go through these two checks
if not anat_only and subject_data['dwi'] == []:
raise Exception("No DWI data found for participant {}. "
"All workflows require DWI images.".format(subject_id))
if not subject_data['t1w']:
raise Exception("No T1w images found for participant {}. "
"All workflows require T1w images.".format(subject_id))
workflow = Workflow(name=name)
workflow.__desc__ = """
Results included in this manuscript come from preprocessing
performed using *dMRIPrep* {dmriprep_ver}
(@dmriprep; RRID:SCR_017412),
which is based on *Nipype* {nipype_ver}
(@nipype1; @nipype2; RRID:SCR_002502).
""".format(dmriprep_ver=__version__, nipype_ver=nipype_ver)
workflow.__postdesc__ = """
For more details of the pipeline, see [the section corresponding
to workflows in *dMRIPrep*'s documentation]\
(https://nipreps.github.io/dmriprep/{dmriprep_ver}/workflows.html \
"dMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by dMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
""".format(dmriprep_ver=Version(__version__).public)
# Filter out standard spaces to a separate dict
std_spaces = OrderedDict([(key, modifiers)
for key, modifiers in output_spaces.items()
if key not in NONSTANDARD_REFERENCES])
inputnode = pe.Node(niu.IdentityInterface(fields=['subjects_dir']),
name='inputnode')
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only),
name='bidssrc')
bids_info = pe.Node(BIDSInfo(bids_dir=layout.root, bids_validate=False),
name='bids_info')
summary = pe.Node(SubjectSummary(
std_spaces=list(std_spaces.keys()),
nstd_spaces=list(
set(NONSTANDARD_REFERENCES).intersection(output_spaces.keys()))),
name='summary',
run_without_submitting=True)
about = pe.Node(AboutSummary(version=__version__,
command=' '.join(sys.argv)),
name='about',
run_without_submitting=True)
ds_report_summary = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='summary', keep_dtype=True),
name='ds_report_summary',
run_without_submitting=True)
ds_report_about = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='about', keep_dtype=True),
name='ds_report_about',
run_without_submitting=True)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=layout.root,
debug=debug,
freesurfer=freesurfer,
hires=hires,
longitudinal=longitudinal,
name="anat_preproc_wf",
num_t1w=len(subject_data['t1w']),
omp_nthreads=omp_nthreads,
output_dir=output_dir,
output_spaces=std_spaces,
reportlets_dir=reportlets_dir,
skull_strip_fixed_seed=skull_strip_fixed_seed,
skull_strip_template=skull_strip_template,
)
workflow.connect([
(inputnode, anat_preproc_wf, [('subjects_dir',
'inputnode.subjects_dir')]),
(bidssrc, bids_info, [(('t1w', fix_multi_T1w_source_name), 'in_file')
]),
(inputnode, summary, [('subjects_dir', 'subjects_dir')]),
(bidssrc, summary, [('t1w', 't1w'), ('t2w', 't2w'), ('dwi', 'dwi')]),
(bids_info, summary, [('subject', 'subject_id')]),
(bids_info, anat_preproc_wf, [(('subject', _prefix),
'inputnode.subject_id')]),
(bidssrc, anat_preproc_wf, [('t1w', 'inputnode.t1w'),
('t2w', 'inputnode.t2w'),
('roi', 'inputnode.roi'),
('flair', 'inputnode.flair')]),
(bidssrc, ds_report_summary, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(summary, ds_report_summary, [('out_report', 'in_file')]),
(bidssrc, ds_report_about, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(about, ds_report_about, [('out_report', 'in_file')]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_'):
workflow.get_node(node).interface.out_path_base = 'dmriprep'
if anat_only:
return workflow
for dwi_file in subject_data['dwi']:
dwi_preproc_wf = init_dwi_preproc_wf(
dwi_file=dwi_file,
debug=debug,
force_syn=force_syn,
ignore=ignore,
layout=layout,
low_mem=low_mem,
num_dwi=len(subject_data['dwi']),
omp_nthreads=omp_nthreads,
output_dir=output_dir,
reportlets_dir=reportlets_dir,
use_syn=use_syn,
)
workflow.connect([
(
anat_preproc_wf,
dwi_preproc_wf,
[
(('outputnode.t1w_preproc', _pop),
'inputnode.t1w_preproc'),
('outputnode.t1w_brain', 'inputnode.t1w_brain'),
('outputnode.t1w_mask', 'inputnode.t1w_mask'),
('outputnode.t1w_dseg', 'inputnode.t1w_dseg'),
('outputnode.t1w_aseg', 'inputnode.t1w_aseg'),
('outputnode.t1w_aparc', 'inputnode.t1w_aparc'),
('outputnode.t1w_tpms', 'inputnode.t1w_tpms'),
('outputnode.template', 'inputnode.template'),
('outputnode.anat2std_xfm', 'inputnode.anat2std_xfm'),
('outputnode.std2anat_xfm', 'inputnode.std2anat_xfm'),
('outputnode.joint_template', 'inputnode.joint_template'),
('outputnode.joint_anat2std_xfm',
'inputnode.joint_anat2std_xfm'),
('outputnode.joint_std2anat_xfm',
'inputnode.joint_std2anat_xfm'),
# Undefined if --fs-no-reconall, but this is safe
('outputnode.subjects_dir', 'inputnode.subjects_dir'),
('outputnode.subject_id', 'inputnode.subject_id'),
('outputnode.t1w2fsnative_xfm',
'inputnode.t1w2fsnative_xfm'),
('outputnode.fsnative2t1w_xfm',
'inputnode.fsnative2t1w_xfm')
]),
])
return workflow
def init_single_subject_wf(subject_id):
"""
Organize the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and functional preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Functional preprocessing is performed using a separate workflow for each
individual BOLD series.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.tests import mock_config
from fmriprep.workflows.base import init_single_subject_wf
with mock_config():
wf = init_single_subject_wf('01')
Parameters
----------
subject_id : :obj:`str`
Subject label for this single-subject workflow.
Inputs
------
subjects_dir : :obj:`str`
FreeSurfer's ``$SUBJECTS_DIR``.
"""
from niworkflows.engine.workflows import LiterateWorkflow as Workflow
from niworkflows.interfaces.bids import BIDSInfo, BIDSDataGrabber
from niworkflows.interfaces.nilearn import NILEARN_VERSION
from niworkflows.utils.bids import collect_data
from niworkflows.utils.misc import fix_multi_T1w_source_name
from niworkflows.utils.spaces import Reference
from smriprep.workflows.anatomical import init_anat_preproc_wf
name = "single_subject_%s_wf" % subject_id
subject_data = collect_data(config.execution.layout,
subject_id,
config.execution.task_id,
config.execution.echo_idx,
bids_filters=config.execution.bids_filters)[0]
if 'flair' in config.workflow.ignore:
subject_data['flair'] = []
if 't2w' in config.workflow.ignore:
subject_data['t2w'] = []
anat_only = config.workflow.anat_only
# Make sure we always go through these two checks
if not anat_only and not subject_data['bold']:
task_id = config.execution.task_id
raise RuntimeError(
"No BOLD images found for participant {} and task {}. "
"All workflows require BOLD images.".format(
subject_id, task_id if task_id else '<all>'))
if not subject_data['t1w']:
raise Exception("No T1w images found for participant {}. "
"All workflows require T1w images.".format(subject_id))
workflow = Workflow(name=name)
workflow.__desc__ = """
Results included in this manuscript come from preprocessing
performed using *fMRIPrep* {fmriprep_ver}
(@fmriprep1; @fmriprep2; RRID:SCR_016216),
which is based on *Nipype* {nipype_ver}
(@nipype1; @nipype2; RRID:SCR_002502).
""".format(fmriprep_ver=config.environment.version,
nipype_ver=config.environment.nipype_version)
workflow.__postdesc__ = """
Many internal operations of *fMRIPrep* use
*Nilearn* {nilearn_ver} [@nilearn, RRID:SCR_001362],
mostly within the functional processing workflow.
For more details of the pipeline, see [the section corresponding
to workflows in *fMRIPrep*'s documentation]\
(https://fmriprep.readthedocs.io/en/latest/workflows.html \
"FMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by fMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
""".format(nilearn_ver=NILEARN_VERSION)
spaces = config.workflow.spaces
reportlets_dir = str(config.execution.work_dir / 'reportlets')
inputnode = pe.Node(niu.IdentityInterface(fields=['subjects_dir']),
name='inputnode')
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only,
subject_id=subject_id),
name='bidssrc')
bids_info = pe.Node(BIDSInfo(bids_dir=config.execution.bids_dir,
bids_validate=False),
name='bids_info')
summary = pe.Node(SubjectSummary(
std_spaces=spaces.get_spaces(nonstandard=False),
nstd_spaces=spaces.get_spaces(standard=False)),
name='summary',
run_without_submitting=True)
about = pe.Node(AboutSummary(version=config.environment.version,
command=' '.join(sys.argv)),
name='about',
run_without_submitting=True)
ds_report_summary = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='summary', keep_dtype=True),
name='ds_report_summary',
run_without_submitting=True)
ds_report_about = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='about', keep_dtype=True),
name='ds_report_about',
run_without_submitting=True)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=str(config.execution.bids_dir),
debug=config.execution.debug is True,
freesurfer=config.workflow.run_reconall,
hires=config.workflow.hires,
longitudinal=config.workflow.longitudinal,
omp_nthreads=config.nipype.omp_nthreads,
output_dir=str(config.execution.output_dir),
reportlets_dir=reportlets_dir,
skull_strip_fixed_seed=config.workflow.skull_strip_fixed_seed,
skull_strip_mode=config.workflow.skull_strip_t1w,
skull_strip_template=Reference.from_string(
config.workflow.skull_strip_template)[0],
spaces=spaces,
t1w=subject_data['t1w'],
)
workflow.connect([
(inputnode, anat_preproc_wf, [('subjects_dir',
'inputnode.subjects_dir')]),
(bidssrc, bids_info, [(('t1w', fix_multi_T1w_source_name), 'in_file')
]),
(inputnode, summary, [('subjects_dir', 'subjects_dir')]),
(bidssrc, summary, [('t1w', 't1w'), ('t2w', 't2w'), ('bold', 'bold')]),
(bids_info, summary, [('subject', 'subject_id')]),
(bids_info, anat_preproc_wf, [(('subject', _prefix),
'inputnode.subject_id')]),
(bidssrc, anat_preproc_wf, [('t1w', 'inputnode.t1w'),
('t2w', 'inputnode.t2w'),
('roi', 'inputnode.roi'),
('flair', 'inputnode.flair')]),
(bidssrc, ds_report_summary, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(summary, ds_report_summary, [('out_report', 'in_file')]),
(bidssrc, ds_report_about, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(about, ds_report_about, [('out_report', 'in_file')]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_'):
workflow.get_node(node).interface.out_path_base = 'fmriprep'
if anat_only:
return workflow
# Append the functional section to the existing anatomical exerpt
# That way we do not need to stream down the number of bold datasets
anat_preproc_wf.__postdesc__ = (anat_preproc_wf.__postdesc__ or '') + """
Functional data preprocessing
: For each of the {num_bold} BOLD runs found per subject (across all
tasks and sessions), the following preprocessing was performed.
""".format(num_bold=len(subject_data['bold']))
for bold_file in subject_data['bold']:
func_preproc_wf = init_func_preproc_wf(bold_file)
workflow.connect([
(
anat_preproc_wf,
func_preproc_wf,
[
('outputnode.t1w_preproc', 'inputnode.t1w_preproc'),
('outputnode.t1w_mask', 'inputnode.t1w_mask'),
('outputnode.t1w_dseg', 'inputnode.t1w_dseg'),
('outputnode.t1w_aseg', 'inputnode.t1w_aseg'),
('outputnode.t1w_aparc', 'inputnode.t1w_aparc'),
('outputnode.t1w_tpms', 'inputnode.t1w_tpms'),
('outputnode.template', 'inputnode.template'),
('outputnode.anat2std_xfm', 'inputnode.anat2std_xfm'),
('outputnode.std2anat_xfm', 'inputnode.std2anat_xfm'),
# Undefined if --fs-no-reconall, but this is safe
('outputnode.subjects_dir', 'inputnode.subjects_dir'),
('outputnode.subject_id', 'inputnode.subject_id'),
('outputnode.t1w2fsnative_xfm',
'inputnode.t1w2fsnative_xfm'),
('outputnode.fsnative2t1w_xfm',
'inputnode.fsnative2t1w_xfm')
]),
])
return workflow
def init_single_subject_wf(subject_id):
"""
Set-up the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and diffusion MRI preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Diffusion MRI preprocessing is performed using a separate workflow for
a full :abbr:`DWI (diffusion weighted imaging)` *entity*.
A DWI *entity* may comprehend one or several runs (for instance, two
opposed :abbr:`PE (phase-encoding)` directions.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from dmriprep.config.testing import mock_config
from dmriprep.workflows.base import init_single_subject_wf
with mock_config():
wf = init_single_subject_wf("THP0005")
Parameters
----------
subject_id : str
List of subject labels
Inputs
------
subjects_dir : os.pathlike
FreeSurfer's ``$SUBJECTS_DIR``
"""
from ..utils.misc import sub_prefix as _prefix
name = f"single_subject_{subject_id}_wf"
subject_data = collect_data(config.execution.layout, subject_id)[0]
if "flair" in config.workflow.ignore:
subject_data["flair"] = []
if "t2w" in config.workflow.ignore:
subject_data["t2w"] = []
anat_only = config.workflow.anat_only
# Make sure we always go through these two checks
if not anat_only and not subject_data["dwi"]:
raise Exception(f"No DWI data found for participant {subject_id}. "
"All workflows require DWI images.")
if not subject_data["t1w"]:
raise Exception(f"No T1w images found for participant {subject_id}. "
"All workflows require T1w images.")
workflow = Workflow(name=name)
workflow.__desc__ = f"""
Results included in this manuscript come from preprocessing
performed using *dMRIPrep* {config.environment.version}
(@dmriprep; RRID:SCR_017412),
which is based on *Nipype* {config.environment.nipype_version}
(@nipype1; @nipype2; RRID:SCR_002502).
"""
workflow.__postdesc__ = """
For more details of the pipeline, see [the section corresponding
to workflows in *dMRIPrep*'s documentation]\
(https://nipreps.github.io/dmriprep/master/workflows.html \
"dMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by dMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
"""
spaces = config.workflow.spaces
output_dir = config.execution.output_dir
fsinputnode = pe.Node(niu.IdentityInterface(fields=["subjects_dir"]),
name="fsinputnode")
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only),
name="bidssrc")
bids_info = pe.Node(
BIDSInfo(bids_dir=config.execution.bids_dir, bids_validate=False),
name="bids_info",
)
summary = pe.Node(
SubjectSummary(
std_spaces=spaces.get_spaces(nonstandard=False),
nstd_spaces=spaces.get_spaces(standard=False),
),
name="summary",
run_without_submitting=True,
)
about = pe.Node(
AboutSummary(version=config.environment.version,
command=" ".join(sys.argv)),
name="about",
run_without_submitting=True,
)
ds_report_summary = pe.Node(
DerivativesDataSink(base_directory=str(output_dir),
desc="summary",
datatype="figures"),
name="ds_report_summary",
run_without_submitting=True,
)
ds_report_about = pe.Node(
DerivativesDataSink(base_directory=str(output_dir),
desc="about",
datatype="figures"),
name="ds_report_about",
run_without_submitting=True,
)
anat_derivatives = config.execution.anat_derivatives
if anat_derivatives:
from smriprep.utils.bids import collect_derivatives
std_spaces = spaces.get_spaces(nonstandard=False, dim=(3, ))
anat_derivatives = collect_derivatives(
anat_derivatives.absolute(),
subject_id,
std_spaces,
config.workflow.run_reconall,
)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=str(config.execution.bids_dir),
debug=config.execution.debug is True,
existing_derivatives=anat_derivatives,
freesurfer=config.workflow.run_reconall,
hires=config.workflow.hires,
longitudinal=config.workflow.longitudinal,
omp_nthreads=config.nipype.omp_nthreads,
output_dir=str(output_dir),
skull_strip_fixed_seed=config.workflow.skull_strip_fixed_seed,
skull_strip_mode="force",
skull_strip_template=Reference.from_string(
config.workflow.skull_strip_template)[0],
spaces=spaces,
t1w=subject_data["t1w"],
)
anat_preproc_wf.__desc__ = f"\n\n{anat_preproc_wf.__desc__}"
# fmt:off
workflow.connect([
(fsinputnode, anat_preproc_wf, [("subjects_dir",
"inputnode.subjects_dir")]),
(bidssrc, bids_info, [(("t1w", fix_multi_T1w_source_name), "in_file")
]),
(fsinputnode, summary, [("subjects_dir", "subjects_dir")]),
(bidssrc, summary, [("t1w", "t1w"), ("t2w", "t2w"), ("dwi", "dwi")]),
(bids_info, summary, [("subject", "subject_id")]),
(bids_info, anat_preproc_wf, [(("subject", _prefix),
"inputnode.subject_id")]),
(bidssrc, anat_preproc_wf, [
("t1w", "inputnode.t1w"),
("t2w", "inputnode.t2w"),
("roi", "inputnode.roi"),
("flair", "inputnode.flair"),
]),
(bidssrc, ds_report_summary, [
(("t1w", fix_multi_T1w_source_name), "source_file"),
]),
(summary, ds_report_summary, [("out_report", "in_file")]),
(bidssrc, ds_report_about, [(("t1w", fix_multi_T1w_source_name),
"source_file")]),
(about, ds_report_about, [("out_report", "in_file")]),
])
# fmt:off
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split(".")[-1].startswith("ds_"):
workflow.get_node(node).interface.out_path_base = "dmriprep"
if anat_only:
return workflow
from .dwi.base import init_dwi_preproc_wf
# Append the dMRI section to the existing anatomical excerpt
# That way we do not need to stream down the number of DWI datasets
anat_preproc_wf.__postdesc__ = f"""\
{anat_preproc_wf.__postdesc__ or ''}
Diffusion data preprocessing
: For each of the {len(subject_data["dwi"])} DWI scans found per subject
(across all sessions), the gradient table was vetted and converted into the *RASb*
format (i.e., given in RAS+ scanner coordinates, normalized b-vectors and scaled b-values),
and a *b=0* average for reference to the subsequent steps of preprocessing was calculated.
"""
# SDC Step 0: Determine whether fieldmaps can/should be estimated
fmap_estimators = None
if "fieldmap" not in config.workflow.ignore:
from sdcflows import fieldmaps as fm
from sdcflows.utils.wrangler import find_estimators
from sdcflows.workflows.base import init_fmap_preproc_wf
# SDC Step 1: Run basic heuristics to identify available data for fieldmap estimation
fmap_estimators = find_estimators(
layout=config.execution.layout,
subject=subject_id,
fmapless=False,
)
# Add fieldmap-less estimators
if not fmap_estimators and config.workflow.use_syn:
# estimators = [fm.FieldmapEstimation()]
raise NotImplementedError
# Nuts and bolts: initialize individual run's pipeline
dwi_preproc_list = []
for dwi_file in subject_data["dwi"]:
dwi_preproc_wf = init_dwi_preproc_wf(
dwi_file,
has_fieldmap=bool(fmap_estimators),
)
# fmt: off
workflow.connect([
(
anat_preproc_wf,
dwi_preproc_wf,
[
("outputnode.t1w_preproc", "inputnode.t1w_preproc"),
("outputnode.t1w_mask", "inputnode.t1w_mask"),
("outputnode.t1w_dseg", "inputnode.t1w_dseg"),
("outputnode.t1w_aseg", "inputnode.t1w_aseg"),
("outputnode.t1w_aparc", "inputnode.t1w_aparc"),
("outputnode.t1w_tpms", "inputnode.t1w_tpms"),
("outputnode.template", "inputnode.template"),
("outputnode.anat2std_xfm", "inputnode.anat2std_xfm"),
("outputnode.std2anat_xfm", "inputnode.std2anat_xfm"),
# Undefined if --fs-no-reconall, but this is safe
("outputnode.subjects_dir", "inputnode.subjects_dir"),
("outputnode.t1w2fsnative_xfm",
"inputnode.t1w2fsnative_xfm"),
("outputnode.fsnative2t1w_xfm",
"inputnode.fsnative2t1w_xfm"),
]),
(bids_info, dwi_preproc_wf, [("subject", "inputnode.subject_id")]),
])
# fmt: on
# Keep a handle to each workflow
dwi_preproc_list.append(dwi_preproc_wf)
if not fmap_estimators:
return workflow
# SDC Step 2: Manually add further estimators (e.g., fieldmap-less)
fmap_wf = init_fmap_preproc_wf(
debug=config.execution.debug,
estimators=fmap_estimators,
omp_nthreads=config.nipype.omp_nthreads,
output_dir=str(output_dir),
subject=subject_id,
)
fmap_wf.__desc__ = f"""
*B<sub>0</sub>* fieldmap data preprocessing
: A total of {len(fmap_estimators)} fieldmaps were found available within the input
BIDS structure for this particular subject.
"""
# TODO: Requires nipreps/sdcflows#147
for dwi_preproc_wf in dwi_preproc_list:
# fmt: off
workflow.connect([
(fmap_wf, dwi_preproc_wf, [
("outputnode.fmap", "inputnode.fmap"),
("outputnode.fmap_ref", "inputnode.fmap_ref"),
("outputnode.fmap_coeff", "inputnode.fmap_coeff"),
("outputnode.fmap_mask", "inputnode.fmap_mask"),
("outputnode.fmap_id", "inputnode.fmap_id"),
]),
])
# fmt: on
# Overwrite ``out_path_base`` of sdcflows's DataSinks
for node in fmap_wf.list_node_names():
if node.split(".")[-1].startswith("ds_"):
fmap_wf.get_node(node).interface.out_path_base = "dmriprep"
# Step 3: Manually connect PEPOLAR
for estimator in fmap_estimators:
if estimator.method != fm.EstimatorType.PEPOLAR:
continue
suffices = set(s.suffix for s in estimator.sources)
if sorted(suffices) == ["epi"]:
getattr(fmap_wf.inputs, f"in_{estimator.bids_id}").in_data = [
str(s.path) for s in estimator.sources
]
getattr(fmap_wf.inputs, f"in_{estimator.bids_id}").metadata = [
s.metadata for s in estimator.sources
]
else:
raise NotImplementedError
# from niworkflows.interfaces.utility import KeySelect
# est_id = estimator.bids_id
# estim_select = pe.MapNode(
# KeySelect(fields=["metadata", "dwi_reference", "dwi_mask", "gradients_rasb",]),
# name=f"fmap_select_{est_id}",
# run_without_submitting=True,
# iterfields=["key"]
# )
# estim_select.inputs.key = [
# str(s.path) for s in estimator.sources if s.suffix in ("epi", "dwi", "sbref")
# ]
# # fmt:off
# workflow.connect([
# (referencenode, estim_select, [("dwi_file", "keys"),
# ("metadata", "metadata"),
# ("dwi_reference", "dwi_reference"),
# ("gradients_rasb", "gradients_rasb")]),
# ])
# # fmt:on
return workflow
def init_single_subject_wf(subject_id):
"""
Set-up the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and diffusion MRI preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Diffusion MRI preprocessing is performed using a separate workflow for
a full :abbr:`DWI (diffusion weighted imaging)` *entity*.
A DWI *entity* may comprehend one or several runs (for instance, two
opposed :abbr:`PE (phase-encoding)` directions.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from dmriprep.config.testing import mock_config
from dmriprep.workflows.base import init_single_subject_wf
with mock_config():
wf = init_single_subject_wf('THP0005')
Parameters
----------
subject_id : str
List of subject labels
Inputs
------
subjects_dir : os.pathlike
FreeSurfer's ``$SUBJECTS_DIR``
"""
name = "single_subject_%s_wf" % subject_id
subject_data = collect_data(config.execution.layout, subject_id)[0]
if 'flair' in config.workflow.ignore:
subject_data['flair'] = []
if 't2w' in config.workflow.ignore:
subject_data['t2w'] = []
anat_only = config.workflow.anat_only
# Make sure we always go through these two checks
if not anat_only and not subject_data['dwi']:
raise Exception(f"No DWI data found for participant {subject_id}. "
"All workflows require DWI images.")
if not subject_data['t1w']:
raise Exception(f"No T1w images found for participant {subject_id}. "
"All workflows require T1w images.")
workflow = Workflow(name=name)
workflow.__desc__ = f"""
Results included in this manuscript come from preprocessing
performed using *dMRIPrep* {config.environment.version}
(@dmriprep; RRID:SCR_017412),
which is based on *Nipype* {config.environment.nipype_version}
(@nipype1; @nipype2; RRID:SCR_002502).
"""
workflow.__postdesc__ = """
For more details of the pipeline, see [the section corresponding
to workflows in *dMRIPrep*'s documentation]\
(https://nipreps.github.io/dmriprep/master/workflows.html \
"dMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by dMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
"""
spaces = config.workflow.spaces
reportlets_dir = str(config.execution.work_dir / 'reportlets')
inputnode = pe.Node(niu.IdentityInterface(fields=['subjects_dir']),
name='inputnode')
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only),
name='bidssrc')
bids_info = pe.Node(BIDSInfo(bids_dir=config.execution.bids_dir,
bids_validate=False),
name='bids_info')
summary = pe.Node(SubjectSummary(
std_spaces=spaces.get_spaces(nonstandard=False),
nstd_spaces=spaces.get_spaces(standard=False)),
name='summary',
run_without_submitting=True)
about = pe.Node(AboutSummary(version=config.environment.version,
command=' '.join(sys.argv)),
name='about',
run_without_submitting=True)
ds_report_summary = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='summary', keep_dtype=True),
name='ds_report_summary',
run_without_submitting=True)
ds_report_about = pe.Node(DerivativesDataSink(
base_directory=reportlets_dir, desc='about', keep_dtype=True),
name='ds_report_about',
run_without_submitting=True)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=str(config.execution.bids_dir),
debug=config.execution.debug is True,
freesurfer=config.workflow.run_reconall,
hires=config.workflow.hires,
longitudinal=config.workflow.longitudinal,
omp_nthreads=config.nipype.omp_nthreads,
output_dir=str(config.execution.output_dir),
reportlets_dir=reportlets_dir,
skull_strip_fixed_seed=config.workflow.skull_strip_fixed_seed,
skull_strip_mode='force',
skull_strip_template=Reference.from_string(
config.workflow.skull_strip_template)[0],
spaces=spaces,
t1w=subject_data['t1w'],
)
workflow.connect([
(inputnode, anat_preproc_wf, [('subjects_dir',
'inputnode.subjects_dir')]),
(bidssrc, bids_info, [(('t1w', fix_multi_T1w_source_name), 'in_file')
]),
(inputnode, summary, [('subjects_dir', 'subjects_dir')]),
(bidssrc, summary, [('t1w', 't1w'), ('t2w', 't2w'), ('dwi', 'dwi')]),
(bids_info, summary, [('subject', 'subject_id')]),
(bids_info, anat_preproc_wf, [(('subject', _prefix),
'inputnode.subject_id')]),
(bidssrc, anat_preproc_wf, [('t1w', 'inputnode.t1w'),
('t2w', 'inputnode.t2w'),
('roi', 'inputnode.roi'),
('flair', 'inputnode.flair')]),
(bidssrc, ds_report_summary, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(summary, ds_report_summary, [('out_report', 'in_file')]),
(bidssrc, ds_report_about, [(('t1w', fix_multi_T1w_source_name),
'source_file')]),
(about, ds_report_about, [('out_report', 'in_file')]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_'):
workflow.get_node(node).interface.out_path_base = 'dmriprep'
if anat_only:
return workflow
# Append the dMRI section to the existing anatomical excerpt
# That way we do not need to stream down the number of bold datasets
anat_preproc_wf.__postdesc__ = (anat_preproc_wf.__postdesc__ or '') + f"""
Diffusion data preprocessing
: For each of the {len(subject_data["dwi"])} dwi scans found per subject
(across all sessions), the following preprocessing was performed."""
for dwi_file in subject_data['dwi']:
dwi_preproc_wf = init_dwi_preproc_wf(dwi_file)
workflow.connect([
(
anat_preproc_wf,
dwi_preproc_wf,
[
(('outputnode.t1w_preproc', _pop),
'inputnode.t1w_preproc'),
('outputnode.t1w_mask', 'inputnode.t1w_mask'),
('outputnode.t1w_dseg', 'inputnode.t1w_dseg'),
('outputnode.t1w_aseg', 'inputnode.t1w_aseg'),
('outputnode.t1w_aparc', 'inputnode.t1w_aparc'),
('outputnode.t1w_tpms', 'inputnode.t1w_tpms'),
('outputnode.template', 'inputnode.template'),
('outputnode.anat2std_xfm', 'inputnode.anat2std_xfm'),
('outputnode.std2anat_xfm', 'inputnode.std2anat_xfm'),
# Undefined if --fs-no-reconall, but this is safe
('outputnode.subjects_dir', 'inputnode.subjects_dir'),
('outputnode.subject_id', 'inputnode.subject_id'),
('outputnode.t1w2fsnative_xfm',
'inputnode.t1w2fsnative_xfm'),
('outputnode.fsnative2t1w_xfm',
'inputnode.fsnative2t1w_xfm')
]),
])
return workflow
def init_single_subject_wf(subject_id):
"""
Set-up the preprocessing pipeline for a single subject.
It collects and reports information about the subject, and prepares
sub-workflows to perform anatomical and diffusion MRI preprocessing.
Anatomical preprocessing is performed in a single workflow, regardless of
the number of sessions.
Diffusion MRI preprocessing is performed using a separate workflow for
a full :abbr:`DWI (diffusion weighted imaging)` *entity*.
A DWI *entity* may comprehend one or several runs (for instance, two
opposed :abbr:`PE (phase-encoding)` directions.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from dmriprep.config.testing import mock_config
from dmriprep.workflows.base import init_single_subject_wf
with mock_config():
wf = init_single_subject_wf("THP0005")
Parameters
----------
subject_id : str
List of subject labels
Inputs
------
subjects_dir : os.pathlike
FreeSurfer's ``$SUBJECTS_DIR``
"""
name = f"single_subject_{subject_id}_wf"
subject_data = collect_data(config.execution.layout, subject_id)[0]
if "flair" in config.workflow.ignore:
subject_data["flair"] = []
if "t2w" in config.workflow.ignore:
subject_data["t2w"] = []
anat_only = config.workflow.anat_only
# Make sure we always go through these two checks
if not anat_only and not subject_data["dwi"]:
raise Exception(f"No DWI data found for participant {subject_id}. "
"All workflows require DWI images.")
if not subject_data["t1w"]:
raise Exception(f"No T1w images found for participant {subject_id}. "
"All workflows require T1w images.")
workflow = Workflow(name=name)
workflow.__desc__ = f"""
Results included in this manuscript come from preprocessing
performed using *dMRIPrep* {config.environment.version}
(@dmriprep; RRID:SCR_017412),
which is based on *Nipype* {config.environment.nipype_version}
(@nipype1; @nipype2; RRID:SCR_002502).
"""
workflow.__postdesc__ = """
For more details of the pipeline, see [the section corresponding
to workflows in *dMRIPrep*'s documentation]\
(https://nipreps.github.io/dmriprep/master/workflows.html \
"dMRIPrep's documentation").
### Copyright Waiver
The above boilerplate text was automatically generated by dMRIPrep
with the express intention that users should copy and paste this
text into their manuscripts *unchanged*.
It is released under the [CC0]\
(https://creativecommons.org/publicdomain/zero/1.0/) license.
### References
"""
spaces = config.workflow.spaces
output_dir = config.execution.output_dir
fsinputnode = pe.Node(niu.IdentityInterface(fields=["subjects_dir"]),
name="fsinputnode")
bidssrc = pe.Node(BIDSDataGrabber(subject_data=subject_data,
anat_only=anat_only),
name="bidssrc")
bids_info = pe.Node(BIDSInfo(bids_dir=config.execution.bids_dir,
bids_validate=False),
name="bids_info")
summary = pe.Node(SubjectSummary(
std_spaces=spaces.get_spaces(nonstandard=False),
nstd_spaces=spaces.get_spaces(standard=False)),
name="summary",
run_without_submitting=True)
about = pe.Node(AboutSummary(version=config.environment.version,
command=" ".join(sys.argv)),
name="about",
run_without_submitting=True)
ds_report_summary = pe.Node(DerivativesDataSink(
base_directory=str(output_dir), desc="summary", datatype="figures"),
name="ds_report_summary",
run_without_submitting=True)
ds_report_about = pe.Node(DerivativesDataSink(
base_directory=str(output_dir), desc="about", datatype="figures"),
name="ds_report_about",
run_without_submitting=True)
anat_derivatives = config.execution.anat_derivatives
if anat_derivatives:
from smriprep.utils.bids import collect_derivatives
std_spaces = spaces.get_spaces(nonstandard=False, dim=(3, ))
anat_derivatives = collect_derivatives(
anat_derivatives.absolute(),
subject_id,
std_spaces,
config.workflow.run_reconall,
)
# Preprocessing of T1w (includes registration to MNI)
anat_preproc_wf = init_anat_preproc_wf(
bids_root=str(config.execution.bids_dir),
debug=config.execution.debug is True,
existing_derivatives=anat_derivatives,
freesurfer=config.workflow.run_reconall,
hires=config.workflow.hires,
longitudinal=config.workflow.longitudinal,
omp_nthreads=config.nipype.omp_nthreads,
output_dir=str(output_dir),
skull_strip_fixed_seed=config.workflow.skull_strip_fixed_seed,
skull_strip_mode="force",
skull_strip_template=Reference.from_string(
config.workflow.skull_strip_template)[0],
spaces=spaces,
t1w=subject_data["t1w"],
)
workflow.connect([
(fsinputnode, anat_preproc_wf, [("subjects_dir",
"inputnode.subjects_dir")]),
(bidssrc, bids_info, [(("t1w", fix_multi_T1w_source_name), "in_file")
]),
(fsinputnode, summary, [("subjects_dir", "subjects_dir")]),
(bidssrc, summary, [("t1w", "t1w"), ("t2w", "t2w"), ("dwi", "dwi")]),
(bids_info, summary, [("subject", "subject_id")]),
(bids_info, anat_preproc_wf, [(("subject", _prefix),
"inputnode.subject_id")]),
(bidssrc, anat_preproc_wf, [("t1w", "inputnode.t1w"),
("t2w", "inputnode.t2w"),
("roi", "inputnode.roi"),
("flair", "inputnode.flair")]),
(bidssrc, ds_report_summary, [(("t1w", fix_multi_T1w_source_name),
"source_file")]),
(summary, ds_report_summary, [("out_report", "in_file")]),
(bidssrc, ds_report_about, [(("t1w", fix_multi_T1w_source_name),
"source_file")]),
(about, ds_report_about, [("out_report", "in_file")]),
])
# Overwrite ``out_path_base`` of smriprep's DataSinks
for node in workflow.list_node_names():
if node.split(".")[-1].startswith("ds_"):
workflow.get_node(node).interface.out_path_base = "dmriprep"
if anat_only:
return workflow
# Append the dMRI section to the existing anatomical excerpt
# That way we do not need to stream down the number of bold datasets
anat_preproc_wf.__postdesc__ = (anat_preproc_wf.__postdesc__ or "") + f"""
Diffusion data preprocessing
: For each of the {len(subject_data["dwi"])} DWI scans found per subject
(across all sessions), the gradient table was vetted and converted into the *RASb*
format (i.e., given in RAS+ scanner coordinates, normalized b-vectors and scaled b-values),
and a *b=0* average for reference to the subsequent steps of preprocessing was calculated.
"""
layout = config.execution.layout
dwi_data = tuple([(dwi, layout.get_metadata(dwi), layout.get_bvec(dwi),
layout.get_bval(dwi)) for dwi in subject_data["dwi"]])
inputnode = pe.Node(niu.IdentityInterface(fields=["dwi_data"]),
name="inputnode")
inputnode.iterables = [("dwi_data", dwi_data)]
referencenode = pe.JoinNode(niu.IdentityInterface(fields=[
"dwi_file", "metadata", "dwi_reference", "dwi_mask", "gradients_rasb"
]),
name="referencenode",
joinsource="inputnode",
run_without_submitting=True)
split_info = pe.Node(niu.Function(
function=_unpack,
output_names=["dwi_file", "metadata", "bvec", "bval"]),
name="split_info",
run_without_submitting=True)
early_b0ref_wf = init_early_b0ref_wf()
workflow.connect([
(inputnode, split_info, [("dwi_data", "in_tuple")]),
(split_info, early_b0ref_wf, [("dwi_file", "inputnode.dwi_file"),
("bvec", "inputnode.in_bvec"),
("bval", "inputnode.in_bval")]),
(split_info, referencenode, [("dwi_file", "dwi_file"),
("metadata", "metadata")]),
(early_b0ref_wf, referencenode, [
("outputnode.dwi_reference", "dwi_reference"),
("outputnode.dwi_mask", "dwi_mask"),
("outputnode.gradients_rasb", "gradients_rasb"),
]),
])
fmap_estimation_wf = init_fmap_estimation_wf(subject_data["dwi"],
debug=config.execution.debug)
workflow.connect([
(referencenode, fmap_estimation_wf,
[("dwi_reference", "inputnode.dwi_reference"),
("dwi_mask", "inputnode.dwi_mask")]),
])
return workflow
