def init_bbreg_wf(use_bbr, bold2t1w_dof, omp_nthreads, name='bbreg_wf'):
"""
This workflow uses FreeSurfer's ``bbregister`` to register a BOLD image to
a T1-weighted structural image.
It is a counterpart to :py:func:`~fmriprep.workflows.util.init_fsl_bbr_wf`,
which performs the same task using FSL's FLIRT with a BBR cost function.
The ``use_bbr`` option permits a high degree of control over registration.
If ``False``, standard, affine coregistration will be performed using
FreeSurfer's ``mri_coreg`` tool.
If ``True``, ``bbregister`` will be seeded with the initial transform found
by ``mri_coreg`` (equivalent to running ``bbregister --init-coreg``).
If ``None``, after ``bbregister`` is run, the resulting affine transform
will be compared to the initial transform found by ``mri_coreg``.
Excessive deviation will result in rejecting the BBR refinement and
accepting the original, affine registration.
.. workflow ::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold.registration import init_bbreg_wf
wf = init_bbreg_wf(use_bbr=True, bold2t1w_dof=9, omp_nthreads=1)
Parameters
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
name : str, optional
Workflow name (default: bbreg_wf)
Inputs
in_file
Reference BOLD image to be registered
t1_2_fsnative_reverse_transform
FSL-style affine matrix translating from FreeSurfer T1.mgz to T1w
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID (must have folder in SUBJECTS_DIR)
t1_brain
Unused (see :py:func:`~fmriprep.workflows.util.init_fsl_bbr_wf`)
t1_seg
Unused (see :py:func:`~fmriprep.workflows.util.init_fsl_bbr_wf`)
Outputs
itk_bold_to_t1
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
itk_t1_to_bold
Affine transform from T1 space to BOLD space (ITK format)
out_report
Reportlet for assessing registration quality
fallback
Boolean indicating whether BBR was rejected (mri_coreg registration returned)
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface([
'in_file',
't1_2_fsnative_reverse_transform', 'subjects_dir', 'subject_id', # BBRegister
't1_seg', 't1_brain']), # FLIRT BBR
name='inputnode')
outputnode = pe.Node(
niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'out_report', 'fallback']),
name='outputnode')
mri_coreg = pe.Node(
MRICoregRPT(dof=bold2t1w_dof, sep=[4], ftol=0.0001, linmintol=0.01,
generate_report=not use_bbr),
name='mri_coreg', n_procs=omp_nthreads, mem_gb=5)
lta_concat = pe.Node(ConcatenateLTA(out_file='out.lta'), name='lta_concat')
# XXX LTA-FSL-ITK may ultimately be able to be replaced with a straightforward
# LTA-ITK transform, but right now the translation parameters are off.
lta2fsl_fwd = pe.Node(fs.utils.LTAConvert(out_fsl=True), name='lta2fsl_fwd')
lta2fsl_inv = pe.Node(fs.utils.LTAConvert(out_fsl=True, invert=True), name='lta2fsl_inv')
fsl2itk_fwd = pe.Node(c3.C3dAffineTool(fsl2ras=True, itk_transform=True),
name='fsl2itk_fwd', mem_gb=DEFAULT_MEMORY_MIN_GB)
fsl2itk_inv = pe.Node(c3.C3dAffineTool(fsl2ras=True, itk_transform=True),
name='fsl2itk_inv', mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, mri_coreg, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id'),
('in_file', 'source_file')]),
# Output ITK transforms
(inputnode, lta_concat, [('t1_2_fsnative_reverse_transform', 'in_lta2')]),
(lta_concat, lta2fsl_fwd, [('out_file', 'in_lta')]),
(lta_concat, lta2fsl_inv, [('out_file', 'in_lta')]),
(inputnode, fsl2itk_fwd, [('t1_brain', 'reference_file'),
('in_file', 'source_file')]),
(inputnode, fsl2itk_inv, [('in_file', 'reference_file'),
('t1_brain', 'source_file')]),
(lta2fsl_fwd, fsl2itk_fwd, [('out_fsl', 'transform_file')]),
(lta2fsl_inv, fsl2itk_inv, [('out_fsl', 'transform_file')]),
(fsl2itk_fwd, outputnode, [('itk_transform', 'itk_bold_to_t1')]),
(fsl2itk_inv, outputnode, [('itk_transform', 'itk_t1_to_bold')]),
])
# Short-circuit workflow building, use initial registration
if use_bbr is False:
workflow.connect([
(mri_coreg, outputnode, [('out_report', 'out_report')]),
(mri_coreg, lta_concat, [('out_lta_file', 'in_lta1')])])
outputnode.inputs.fallback = True
return workflow
bbregister = pe.Node(
BBRegisterRPT(dof=bold2t1w_dof, contrast_type='t2', registered_file=True,
out_lta_file=True, generate_report=True),
name='bbregister', mem_gb=12)
workflow.connect([
(inputnode, bbregister, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id'),
('in_file', 'source_file')]),
(mri_coreg, bbregister, [('out_lta_file', 'init_reg_file')]),
])
# Short-circuit workflow building, use boundary-based registration
if use_bbr is True:
workflow.connect([
(bbregister, outputnode, [('out_report', 'out_report')]),
(bbregister, lta_concat, [('out_lta_file', 'in_lta1')])])
outputnode.inputs.fallback = False
return workflow
transforms = pe.Node(niu.Merge(2), run_without_submitting=True, name='transforms')
reports = pe.Node(niu.Merge(2), run_without_submitting=True, name='reports')
lta_ras2ras = pe.MapNode(fs.utils.LTAConvert(out_lta=True), iterfield=['in_lta'],
name='lta_ras2ras', mem_gb=2)
compare_transforms = pe.Node(niu.Function(function=compare_xforms), name='compare_transforms')
select_transform = pe.Node(niu.Select(), run_without_submitting=True, name='select_transform')
select_report = pe.Node(niu.Select(), run_without_submitting=True, name='select_report')
workflow.connect([
(bbregister, transforms, [('out_lta_file', 'in1')]),
(mri_coreg, transforms, [('out_lta_file', 'in2')]),
# Normalize LTA transforms to RAS2RAS (inputs are VOX2VOX) and compare
(transforms, lta_ras2ras, [('out', 'in_lta')]),
(lta_ras2ras, compare_transforms, [('out_lta', 'lta_list')]),
(compare_transforms, outputnode, [('out', 'fallback')]),
# Select output transform
(transforms, select_transform, [('out', 'inlist')]),
(compare_transforms, select_transform, [('out', 'index')]),
(select_transform, lta_concat, [('out', 'in_lta1')]),
# Select output report
(bbregister, reports, [('out_report', 'in1')]),
(mri_coreg, reports, [('out_report', 'in2')]),
(reports, select_report, [('out', 'inlist')]),
(compare_transforms, select_report, [('out', 'index')]),
(select_report, outputnode, [('out', 'out_report')]),
])
return workflow
def init_fsl_bbr_wf(use_bbr, bold2t1w_dof, name='fsl_bbr_wf'):
"""
This workflow uses FSL FLIRT to register a BOLD image to a T1-weighted
structural image, using a boundary-based registration (BBR) cost function.
It is a counterpart to :py:func:`~fmriprep.workflows.bold.registration.init_bbreg_wf`,
which performs the same task using FreeSurfer's ``bbregister``.
The ``use_bbr`` option permits a high degree of control over registration.
If ``False``, standard, rigid coregistration will be performed by FLIRT.
If ``True``, FLIRT-BBR will be seeded with the initial transform found by
the rigid coregistration.
If ``None``, after FLIRT-BBR is run, the resulting affine transform
will be compared to the initial transform found by FLIRT.
Excessive deviation will result in rejecting the BBR refinement and
accepting the original, affine registration.
.. workflow ::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold.registration import init_fsl_bbr_wf
wf = init_fsl_bbr_wf(use_bbr=True, bold2t1w_dof=9)
Parameters
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
name : str, optional
Workflow name (default: fsl_bbr_wf)
Inputs
in_file
Reference BOLD image to be registered
t1_brain
Skull-stripped T1-weighted structural image
t1_seg
FAST segmentation of ``t1_brain``
t1_2_fsnative_reverse_transform
Unused (see :py:func:`~fmriprep.workflows.util.init_bbreg_wf`)
subjects_dir
Unused (see :py:func:`~fmriprep.workflows.util.init_bbreg_wf`)
subject_id
Unused (see :py:func:`~fmriprep.workflows.util.init_bbreg_wf`)
Outputs
itk_bold_to_t1
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
itk_t1_to_bold
Affine transform from T1 space to BOLD space (ITK format)
out_report
Reportlet for assessing registration quality
fallback
Boolean indicating whether BBR was rejected (rigid FLIRT registration returned)
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface([
'in_file',
't1_2_fsnative_reverse_transform', 'subjects_dir', 'subject_id', # BBRegister
't1_seg', 't1_brain']), # FLIRT BBR
name='inputnode')
outputnode = pe.Node(
niu.IdentityInterface(['itk_bold_to_t1', 'itk_t1_to_bold', 'out_report', 'fallback']),
name='outputnode')
wm_mask = pe.Node(niu.Function(function=extract_wm), name='wm_mask')
flt_bbr_init = pe.Node(FLIRTRPT(dof=6, generate_report=not use_bbr), name='flt_bbr_init')
invt_bbr = pe.Node(fsl.ConvertXFM(invert_xfm=True), name='invt_bbr',
mem_gb=DEFAULT_MEMORY_MIN_GB)
# BOLD to T1 transform matrix is from fsl, using c3 tools to convert to
# something ANTs will like.
fsl2itk_fwd = pe.Node(c3.C3dAffineTool(fsl2ras=True, itk_transform=True),
name='fsl2itk_fwd', mem_gb=DEFAULT_MEMORY_MIN_GB)
fsl2itk_inv = pe.Node(c3.C3dAffineTool(fsl2ras=True, itk_transform=True),
name='fsl2itk_inv', mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, flt_bbr_init, [('in_file', 'in_file'),
('t1_brain', 'reference')]),
(inputnode, fsl2itk_fwd, [('t1_brain', 'reference_file'),
('in_file', 'source_file')]),
(inputnode, fsl2itk_inv, [('in_file', 'reference_file'),
('t1_brain', 'source_file')]),
(invt_bbr, fsl2itk_inv, [('out_file', 'transform_file')]),
(fsl2itk_fwd, outputnode, [('itk_transform', 'itk_bold_to_t1')]),
(fsl2itk_inv, outputnode, [('itk_transform', 'itk_t1_to_bold')]),
])
# Short-circuit workflow building, use rigid registration
if use_bbr is False:
workflow.connect([
(flt_bbr_init, invt_bbr, [('out_matrix_file', 'in_file')]),
(flt_bbr_init, fsl2itk_fwd, [('out_matrix_file', 'transform_file')]),
(flt_bbr_init, outputnode, [('out_report', 'out_report')]),
])
outputnode.inputs.fallback = True
return workflow
flt_bbr = pe.Node(
FLIRTRPT(cost_func='bbr', dof=bold2t1w_dof, generate_report=True,
schedule=op.join(os.getenv('FSLDIR'), 'etc/flirtsch/bbr.sch')),
name='flt_bbr')
workflow.connect([
(inputnode, wm_mask, [('t1_seg', 'in_seg')]),
(inputnode, flt_bbr, [('in_file', 'in_file'),
('t1_brain', 'reference')]),
(flt_bbr_init, flt_bbr, [('out_matrix_file', 'in_matrix_file')]),
(wm_mask, flt_bbr, [('out', 'wm_seg')]),
])
# Short-circuit workflow building, use boundary-based registration
if use_bbr is True:
workflow.connect([
(flt_bbr, invt_bbr, [('out_matrix_file', 'in_file')]),
(flt_bbr, fsl2itk_fwd, [('out_matrix_file', 'transform_file')]),
(flt_bbr, outputnode, [('out_report', 'out_report')]),
])
outputnode.inputs.fallback = False
return workflow
transforms = pe.Node(niu.Merge(2), run_without_submitting=True, name='transforms')
reports = pe.Node(niu.Merge(2), run_without_submitting=True, name='reports')
compare_transforms = pe.Node(niu.Function(function=compare_xforms), name='compare_transforms')
select_transform = pe.Node(niu.Select(), run_without_submitting=True, name='select_transform')
select_report = pe.Node(niu.Select(), run_without_submitting=True, name='select_report')
fsl_to_lta = pe.MapNode(fs.utils.LTAConvert(out_lta=True), iterfield=['in_fsl'],
name='fsl_to_lta')
workflow.connect([
(flt_bbr, transforms, [('out_matrix_file', 'in1')]),
(flt_bbr_init, transforms, [('out_matrix_file', 'in2')]),
# Convert FSL transforms to LTA (RAS2RAS) transforms and compare
(inputnode, fsl_to_lta, [('in_file', 'source_file'),
('t1_brain', 'target_file')]),
(transforms, fsl_to_lta, [('out', 'in_fsl')]),
(fsl_to_lta, compare_transforms, [('out_lta', 'lta_list')]),
(compare_transforms, outputnode, [('out', 'fallback')]),
# Select output transform
(transforms, select_transform, [('out', 'inlist')]),
(compare_transforms, select_transform, [('out', 'index')]),
(select_transform, invt_bbr, [('out', 'in_file')]),
(select_transform, fsl2itk_fwd, [('out', 'transform_file')]),
(flt_bbr, reports, [('out_report', 'in1')]),
(flt_bbr_init, reports, [('out_report', 'in2')]),
(reports, select_report, [('out', 'inlist')]),
(compare_transforms, select_report, [('out', 'index')]),
(select_report, outputnode, [('out', 'out_report')]),
])
return workflow
def init_func_preproc_wf(bold_file,
ignore,
freesurfer,
use_bbr,
t2s_coreg,
bold2t1w_dof,
reportlets_dir,
output_spaces,
template,
output_dir,
omp_nthreads,
fmap_bspline,
fmap_demean,
use_syn,
force_syn,
use_aroma,
ignore_aroma_err,
medial_surface_nan,
debug,
low_mem,
output_grid_ref,
layout=None):
"""
This workflow controls the functional preprocessing stages of FMRIPREP.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold import init_func_preproc_wf
wf = init_func_preproc_wf('/completely/made/up/path/sub-01_task-nback_bold.nii.gz',
omp_nthreads=1,
ignore=[],
freesurfer=True,
reportlets_dir='.',
output_dir='.',
template='MNI152NLin2009cAsym',
output_spaces=['T1w', 'fsnative',
'template', 'fsaverage5'],
debug=False,
use_bbr=True,
t2s_coreg=False,
bold2t1w_dof=9,
fmap_bspline=True,
fmap_demean=True,
use_syn=True,
force_syn=True,
low_mem=False,
output_grid_ref=None,
medial_surface_nan=False,
use_aroma=False,
ignore_aroma_err=False)
**Parameters**
bold_file : str
BOLD series NIfTI file
ignore : list
Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
freesurfer : bool
Enable FreeSurfer functional registration (bbregister) and resampling
BOLD series to FreeSurfer surface meshes.
use_bbr : bool or None
Enable/disable boundary-based registration refinement.
If ``None``, test BBR result for distortion before accepting.
t2s_coreg : bool
Use multiple BOLD echos to create T2*-map for T2*-driven coregistration
bold2t1w_dof : 6, 9 or 12
Degrees-of-freedom for BOLD-T1w registration
reportlets_dir : str
Directory in which to save reportlets
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
output_dir : str
Directory in which to save derivatives
omp_nthreads : int
Maximum number of threads an individual process may use
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
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
debug : bool
Enable debugging outputs
low_mem : bool
Write uncompressed .nii files in some cases to reduce memory usage
output_grid_ref : str or None
Path of custom reference image for normalization
layout : BIDSLayout
BIDSLayout structure to enable metadata retrieval
**Inputs**
bold_file
BOLD series NIfTI file
t1_preproc
Bias-corrected structural template image
t1_brain
Skull-stripped ``t1_preproc``
t1_mask
Mask of the skull-stripped template image
t1_seg
Segmentation of preprocessed structural image, including
gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)
t1_tpms
List of tissue probability maps in T1w space
t1_2_mni_forward_transform
ANTs-compatible affine-and-warp transform file
t1_2_mni_reverse_transform
ANTs-compatible affine-and-warp transform file (inverse)
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_forward_transform
LTA-style affine matrix translating from T1w to FreeSurfer-conformed subject space
t1_2_fsnative_reverse_transform
LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
**Outputs**
bold_t1
BOLD series, resampled to T1w space
bold_mask_t1
BOLD series mask in T1w space
bold_mni
BOLD series, resampled to template space
bold_mask_mni
BOLD series mask in template space
confounds
TSV of confounds
surfaces
BOLD series, resampled to FreeSurfer surfaces
aroma_noise_ics
Noise components identified by ICA-AROMA
melodic_mix
FSL MELODIC mixing matrix
**Subworkflows**
* :py:func:`~fmriprep.workflows.bold.util.init_bold_reference_wf`
* :py:func:`~fmriprep.workflows.bold.stc.init_bold_stc_wf`
* :py:func:`~fmriprep.workflows.bold.hmc.init_bold_hmc_wf`
* :py:func:`~fmriprep.workflows.bold.t2s.init_bold_t2s_wf`
* :py:func:`~fmriprep.workflows.bold.registration.init_bold_reg_wf`
* :py:func:`~fmriprep.workflows.bold.confounds.init_bold_confounds_wf`
* :py:func:`~fmriprep.workflows.bold.confounds.init_ica_aroma_wf`
* :py:func:`~fmriprep.workflows.bold.resampling.init_bold_mni_trans_wf`
* :py:func:`~fmriprep.workflows.bold.resampling.init_bold_preproc_trans_wf`
* :py:func:`~fmriprep.workflows.bold.resampling.init_bold_surf_wf`
* :py:func:`~fmriprep.workflows.fieldmap.pepolar.init_pepolar_unwarp_wf`
* :py:func:`~fmriprep.workflows.fieldmap.init_fmap_estimator_wf`
* :py:func:`~fmriprep.workflows.fieldmap.init_sdc_unwarp_wf`
* :py:func:`~fmriprep.workflows.fieldmap.init_nonlinear_sdc_wf`
"""
ref_file = bold_file
mem_gb = {'filesize': 1, 'resampled': 1, 'largemem': 1}
bold_tlen = 10
multiecho = isinstance(bold_file, list)
if multiecho:
tes = [layout.get_metadata(echo)['EchoTime'] for echo in bold_file]
ref_file = dict(zip(tes, bold_file))[min(tes)]
if os.path.isfile(ref_file):
bold_tlen, mem_gb = _create_mem_gb(ref_file)
wf_name = _get_wf_name(ref_file)
LOGGER.log(
25, ('Creating bold processing workflow for "%s" (%.2f GB / %d TRs). '
'Memory resampled/largemem=%.2f/%.2f GB.'), ref_file,
mem_gb['filesize'], bold_tlen, mem_gb['resampled'], mem_gb['largemem'])
# For doc building purposes
if layout is None or bold_file == 'bold_preprocesing':
LOGGER.log(25, 'No valid layout: building empty workflow.')
metadata = {
'RepetitionTime': 2.0,
'SliceTiming': [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9],
'PhaseEncodingDirection': 'j',
}
fmaps = [{
'type':
'phasediff',
'phasediff':
'sub-03/ses-2/fmap/sub-03_ses-2_run-1_phasediff.nii.gz',
'magnitude1':
'sub-03/ses-2/fmap/sub-03_ses-2_run-1_magnitude1.nii.gz',
'magnitude2':
'sub-03/ses-2/fmap/sub-03_ses-2_run-1_magnitude2.nii.gz',
}]
run_stc = True
multiecho = False
else:
metadata = layout.get_metadata(ref_file)
# Find fieldmaps. Options: (phase1|phase2|phasediff|epi|fieldmap|syn)
fmaps = []
if 'fieldmaps' not in ignore:
fmaps = layout.get_fieldmap(ref_file, return_list=True)
for fmap in fmaps:
fmap['metadata'] = layout.get_metadata(fmap[fmap['type']])
# Run SyN if forced or in the absence of fieldmap correction
if force_syn or (use_syn and not fmaps):
fmaps.append({'type': 'syn'})
# Short circuits: (True and True and (False or 'TooShort')) == 'TooShort'
run_stc = ("SliceTiming" in metadata and 'slicetiming' not in ignore
and (_get_series_len(bold_file) > 4 or "TooShort"))
# Use T2* as target for ME-EPI in co-registration
if t2s_coreg and not multiecho:
LOGGER.warning(
"No multiecho BOLD images found for T2* coregistration. "
"Using standard EPI-T1 coregistration.")
t2s_coreg = False
# Build workflow
workflow = pe.Workflow(name=wf_name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'bold_file', 'subjects_dir', 'subject_id', 't1_preproc', 't1_brain',
't1_mask', 't1_seg', 't1_tpms', 't1_aseg', 't1_aparc',
't1_2_mni_forward_transform', 't1_2_mni_reverse_transform',
't1_2_fsnative_forward_transform', 't1_2_fsnative_reverse_transform'
]),
name='inputnode')
inputnode.inputs.bold_file = bold_file
outputnode = pe.Node(niu.IdentityInterface(fields=[
'bold_t1', 'bold_mask_t1', 'bold_aseg_t1', 'bold_aparc_t1', 'bold_mni',
'bold_mask_mni', 'confounds', 'surfaces', 't2s_map', 'aroma_noise_ics',
'melodic_mix', 'nonaggr_denoised_file'
]),
name='outputnode')
# BOLD buffer: an identity used as a pointer to either the original BOLD
# or the STC'ed one for further use.
boldbuffer = pe.Node(niu.IdentityInterface(fields=['bold_file']),
name='boldbuffer')
summary = pe.Node(FunctionalSummary(
output_spaces=output_spaces,
slice_timing=run_stc,
registration='FreeSurfer' if freesurfer else 'FSL',
registration_dof=bold2t1w_dof,
pe_direction=metadata.get("PhaseEncodingDirection")),
name='summary',
mem_gb=DEFAULT_MEMORY_MIN_GB,
run_without_submitting=True)
func_reports_wf = init_func_reports_wf(reportlets_dir=reportlets_dir,
freesurfer=freesurfer,
use_aroma=use_aroma,
use_syn=use_syn,
t2s_coreg=t2s_coreg)
func_derivatives_wf = init_func_derivatives_wf(output_dir=output_dir,
output_spaces=output_spaces,
template=template,
freesurfer=freesurfer,
use_aroma=use_aroma)
workflow.connect([
(inputnode, func_reports_wf, [('bold_file', 'inputnode.source_file')]),
(inputnode, func_derivatives_wf, [('bold_file',
'inputnode.source_file')]),
(outputnode, func_derivatives_wf, [
('bold_t1', 'inputnode.bold_t1'),
('bold_aseg_t1', 'inputnode.bold_aseg_t1'),
('bold_aparc_t1', 'inputnode.bold_aparc_t1'),
('bold_mask_t1', 'inputnode.bold_mask_t1'),
('bold_mni', 'inputnode.bold_mni'),
('bold_mask_mni', 'inputnode.bold_mask_mni'),
('confounds', 'inputnode.confounds'),
('surfaces', 'inputnode.surfaces'),
('aroma_noise_ics', 'inputnode.aroma_noise_ics'),
('melodic_mix', 'inputnode.melodic_mix'),
('nonaggr_denoised_file', 'inputnode.nonaggr_denoised_file'),
]),
])
# The first reference uses T2 contrast enhancement
bold_reference_wf = init_bold_reference_wf(omp_nthreads=omp_nthreads,
enhance_t2=True)
# Top-level BOLD splitter
bold_split = pe.Node(FSLSplit(dimension='t'),
name='bold_split',
mem_gb=mem_gb['filesize'] * 3)
# HMC on the BOLD
bold_hmc_wf = init_bold_hmc_wf(name='bold_hmc_wf',
mem_gb=mem_gb['filesize'],
omp_nthreads=omp_nthreads)
# mean BOLD registration to T1w
bold_reg_wf = init_bold_reg_wf(name='bold_reg_wf',
freesurfer=freesurfer,
use_bbr=use_bbr,
bold2t1w_dof=bold2t1w_dof,
mem_gb=mem_gb['resampled'],
omp_nthreads=omp_nthreads,
use_compression=False,
use_fieldwarp=(fmaps is not None
or use_syn))
# get confounds
bold_confounds_wf = init_bold_confs_wf(mem_gb=mem_gb['largemem'],
metadata=metadata,
name='bold_confounds_wf')
bold_confounds_wf.get_node('inputnode').inputs.t1_transform_flags = [False]
# Apply transforms in 1 shot
# Only use uncompressed output if AROMA is to be run
bold_bold_trans_wf = init_bold_preproc_trans_wf(
mem_gb=mem_gb['resampled'],
omp_nthreads=omp_nthreads,
use_compression=not low_mem,
use_fieldwarp=(fmaps is not None or use_syn),
name='bold_bold_trans_wf')
# SLICE-TIME CORRECTION (or bypass) #############################################
if run_stc is True: # bool('TooShort') == True, so check True explicitly
bold_stc_wf = init_bold_stc_wf(name='bold_stc_wf', metadata=metadata)
workflow.connect([
(bold_stc_wf, boldbuffer, [('outputnode.stc_file', 'bold_file')]),
(bold_reference_wf, bold_stc_wf,
[('outputnode.bold_file', 'inputnode.bold_file'),
('outputnode.skip_vols', 'inputnode.skip_vols')]),
])
else: # bypass STC from original BOLD to the splitter through boldbuffer
workflow.connect([
(bold_reference_wf, boldbuffer, [('outputnode.bold_file',
'bold_file')]),
])
# SDC (SUSCEPTIBILITY DISTORTION CORRECTION) or bypass ##########################
bold_sdc_wf = init_sdc_wf(fmaps,
metadata,
omp_nthreads=omp_nthreads,
debug=debug,
fmap_demean=fmap_demean,
fmap_bspline=fmap_bspline)
bold_sdc_wf.inputs.inputnode.template = template
if not fmaps:
LOGGER.warning('SDC: no fieldmaps found or they were ignored (%s).',
ref_file)
elif fmaps[0]['type'] == 'syn':
LOGGER.warning(
'SDC: no fieldmaps found or they were ignored. '
'Using EXPERIMENTAL "fieldmap-less SyN" correction '
'for dataset %s.', ref_file)
else:
LOGGER.log(
25, 'SDC: fieldmap estimation of type "%s" intended for %s found.',
fmaps[0]['type'], ref_file)
# MAIN WORKFLOW STRUCTURE #######################################################
workflow.connect([
# BOLD buffer has slice-time corrected if it was run, original otherwise
(boldbuffer, bold_split, [('bold_file', 'in_file')]),
# Generate early reference
(inputnode, bold_reference_wf, [('bold_file', 'inputnode.bold_file')]),
(bold_reference_wf, func_reports_wf,
[('outputnode.validation_report', 'inputnode.validation_report')]),
# EPI-T1 registration workflow
(
inputnode,
bold_reg_wf,
[
('bold_file', 'inputnode.name_source'),
('t1_preproc', 'inputnode.t1_preproc'),
('t1_brain', 'inputnode.t1_brain'),
('t1_mask', 'inputnode.t1_mask'),
('t1_seg', 'inputnode.t1_seg'),
('t1_aseg', 'inputnode.t1_aseg'),
('t1_aparc', 'inputnode.t1_aparc'),
# Undefined if --no-freesurfer, but this is safe
('subjects_dir', 'inputnode.subjects_dir'),
('subject_id', 'inputnode.subject_id'),
('t1_2_fsnative_reverse_transform',
'inputnode.t1_2_fsnative_reverse_transform')
]),
(bold_split, bold_reg_wf, [('out_files', 'inputnode.bold_split')]),
(bold_hmc_wf, bold_reg_wf, [('outputnode.xforms',
'inputnode.hmc_xforms')]),
(bold_reg_wf, func_reports_wf, [
('outputnode.out_report', 'inputnode.bold_reg_report'),
('outputnode.fallback', 'inputnode.bold_reg_fallback'),
]),
(bold_reg_wf, outputnode, [('outputnode.bold_t1', 'bold_t1'),
('outputnode.bold_aseg_t1', 'bold_aseg_t1'),
('outputnode.bold_aparc_t1',
'bold_aparc_t1')]),
(bold_reg_wf, summary, [('outputnode.fallback', 'fallback')]),
# SDC (or pass-through workflow)
(inputnode, bold_sdc_wf, [('t1_brain', 'inputnode.t1_brain'),
('t1_2_mni_reverse_transform',
'inputnode.t1_2_mni_reverse_transform')]),
(bold_reference_wf, bold_sdc_wf,
[('outputnode.ref_image', 'inputnode.bold_ref'),
('outputnode.ref_image_brain', 'inputnode.bold_ref_brain'),
('outputnode.bold_mask', 'inputnode.bold_mask')]),
(bold_sdc_wf, bold_reg_wf,
[('outputnode.bold_ref_brain', 'inputnode.ref_bold_brain'),
('outputnode.bold_mask', 'inputnode.ref_bold_mask'),
('outputnode.out_warp', 'inputnode.fieldwarp')]),
(bold_sdc_wf, bold_bold_trans_wf,
[('outputnode.out_warp', 'inputnode.fieldwarp'),
('outputnode.bold_mask', 'inputnode.bold_mask')]),
(bold_sdc_wf, summary, [('outputnode.method', 'distortion_correction')
]),
# Connect bold_confounds_wf
(inputnode, bold_confounds_wf, [('t1_tpms', 'inputnode.t1_tpms'),
('t1_mask', 'inputnode.t1_mask')]),
(bold_hmc_wf, bold_confounds_wf, [('outputnode.movpar_file',
'inputnode.movpar_file')]),
(bold_reg_wf, bold_confounds_wf, [('outputnode.itk_t1_to_bold',
'inputnode.t1_bold_xform')]),
(bold_confounds_wf, func_reports_wf, [('outputnode.rois_report',
'inputnode.bold_rois_report')]),
(bold_confounds_wf, outputnode, [
('outputnode.confounds_file', 'confounds'),
]),
# Connect bold_bold_trans_wf
(inputnode, bold_bold_trans_wf, [('bold_file', 'inputnode.name_source')
]),
(bold_split, bold_bold_trans_wf, [('out_files', 'inputnode.bold_split')
]),
(bold_hmc_wf, bold_bold_trans_wf, [('outputnode.xforms',
'inputnode.hmc_xforms')]),
(bold_bold_trans_wf, bold_confounds_wf,
[('outputnode.bold', 'inputnode.bold'),
('outputnode.bold_mask', 'inputnode.bold_mask')]),
# Summary
(outputnode, summary, [('confounds', 'confounds_file')]),
(summary, func_reports_wf, [('out_report', 'inputnode.summary_report')
]),
])
if fmaps:
from ..fieldmap.unwarp import init_fmap_unwarp_report_wf
sdc_type = fmaps[0]['type']
# Report on BOLD correction
fmap_unwarp_report_wf = init_fmap_unwarp_report_wf(suffix='sdc_%s' %
sdc_type)
workflow.connect([
(inputnode, fmap_unwarp_report_wf, [('t1_seg', 'inputnode.in_seg')
]),
(bold_reference_wf, fmap_unwarp_report_wf,
[('outputnode.ref_image', 'inputnode.in_pre')]),
(bold_reg_wf, fmap_unwarp_report_wf, [('outputnode.itk_t1_to_bold',
'inputnode.in_xfm')]),
(bold_sdc_wf, fmap_unwarp_report_wf, [('outputnode.bold_ref',
'inputnode.in_post')]),
])
if force_syn and sdc_type != 'syn':
syn_unwarp_report_wf = init_fmap_unwarp_report_wf(
suffix='forcedsyn', name='syn_unwarp_report_wf')
workflow.connect([
(inputnode, syn_unwarp_report_wf, [('t1_seg',
'inputnode.in_seg')]),
(bold_reference_wf, syn_unwarp_report_wf,
[('outputnode.ref_image', 'inputnode.in_pre')]),
(bold_reg_wf, syn_unwarp_report_wf,
[('outputnode.itk_t1_to_bold', 'inputnode.in_xfm')]),
(bold_sdc_wf, syn_unwarp_report_wf,
[('outputnode.syn_bold_ref', 'inputnode.in_post')]),
])
# Fill-in datasinks of reportlets seen so far
for node in workflow.list_node_names():
if node.split('.')[-1].startswith('ds_report'):
workflow.get_node(node).inputs.base_directory = reportlets_dir
workflow.get_node(node).inputs.source_file = bold_file
# if multiecho data, select first echo for hmc correction
if multiecho:
inputnode.iterables = ('bold_file', bold_file)
me_first_echo = pe.JoinNode(interface=FirstEcho(te_list=tes),
joinfield=['in_files', 'ref_imgs'],
joinsource='inputnode',
name='me_first_echo')
workflow.connect([(bold_reference_wf, me_first_echo,
[('outputnode.bold_file', 'in_files'),
('outputnode.raw_ref_image', 'ref_imgs')]),
(me_first_echo, bold_hmc_wf,
[('first_image', 'inputnode.bold_file'),
('first_ref_image', 'inputnode.raw_ref_image')])])
if t2s_coreg:
# use a joinNode to gather all preprocessed echos
join_split_echos = pe.JoinNode(
niu.IdentityInterface(fields=['echo_files']),
joinsource='inputnode',
joinfield='echo_files',
name='join_split_echos')
# create a T2* map
bold_t2s_wf = init_bold_t2s_wf(echo_times=tes,
name='bold_t2s_wf',
mem_gb=mem_gb['filesize'],
omp_nthreads=omp_nthreads)
subset_reg_reports = pe.JoinNode(niu.Select(index=0),
name='subset_reg_reports',
joinsource=inputnode,
joinfield=['inlist'])
subset_reg_fallbacks = pe.JoinNode(niu.Select(index=0),
name='subset_reg_fallbacks',
joinsource=inputnode,
joinfield=['inlist'])
first_echo = pe.Node(niu.IdentityInterface(fields=['first_echo']),
name='first_echo')
first_echo.inputs.first_echo = ref_file
# remove duplicate registration reports
workflow.disconnect([
(bold_reg_wf, func_reports_wf,
[('outputnode.out_report', 'inputnode.bold_reg_report'),
('outputnode.fallback', 'inputnode.bold_reg_fallback')]),
(bold_sdc_wf, bold_reg_wf,
[('outputnode.out_warp', 'inputnode.fieldwarp'),
('outputnode.bold_ref_brain', 'inputnode.ref_bold_brain'),
('outputnode.bold_mask', 'inputnode.ref_bold_mask')]),
])
workflow.connect([
(first_echo, func_reports_wf, [('first_echo',
'inputnode.first_echo')]),
(bold_split, join_split_echos, [('out_files', 'echo_files')]),
(join_split_echos, bold_t2s_wf, [('echo_files',
'inputnode.echo_split')]),
(bold_hmc_wf, bold_t2s_wf, [('outputnode.xforms',
'inputnode.hmc_xforms')]),
(bold_t2s_wf, bold_reg_wf,
[('outputnode.t2s_map', 'inputnode.ref_bold_brain'),
('outputnode.oc_mask', 'inputnode.ref_bold_mask')]),
(bold_reg_wf, subset_reg_reports, [('outputnode.out_report',
'inlist')]),
(bold_reg_wf, subset_reg_fallbacks, [('outputnode.fallback',
'inlist')]),
(subset_reg_reports, func_reports_wf,
[('out', 'inputnode.bold_reg_report')]),
(subset_reg_fallbacks, func_reports_wf,
[('out', 'inputnode.bold_reg_fallback')]),
])
else:
workflow.connect([(bold_reference_wf, bold_hmc_wf, [
('outputnode.raw_ref_image', 'inputnode.raw_ref_image'),
('outputnode.bold_file', 'inputnode.bold_file')
])])
# Map final BOLD mask into T1w space (if required)
if 'T1w' in output_spaces:
from niworkflows.interfaces.fixes import (FixHeaderApplyTransforms as
ApplyTransforms)
boldmask_to_t1w = pe.Node(ApplyTransforms(interpolation='MultiLabel',
float=True),
name='boldmask_to_t1w',
mem_gb=0.1)
workflow.connect([
(bold_bold_trans_wf, boldmask_to_t1w, [('outputnode.bold_mask',
'input_image')]),
(bold_reg_wf, boldmask_to_t1w,
[('outputnode.bold_mask_t1', 'reference_image'),
('outputnode.itk_bold_to_t1', 'transforms')]),
(boldmask_to_t1w, outputnode, [('output_image', 'bold_mask_t1')]),
])
if 'template' in output_spaces:
# Apply transforms in 1 shot
# Only use uncompressed output if AROMA is to be run
bold_mni_trans_wf = init_bold_mni_trans_wf(
template=template,
mem_gb=mem_gb['resampled'],
omp_nthreads=omp_nthreads,
output_grid_ref=output_grid_ref,
use_compression=not (low_mem and use_aroma),
use_fieldwarp=fmaps is not None,
name='bold_mni_trans_wf')
workflow.connect([
(inputnode, bold_mni_trans_wf,
[('bold_file', 'inputnode.name_source'),
('t1_2_mni_forward_transform',
'inputnode.t1_2_mni_forward_transform')]),
(bold_split, bold_mni_trans_wf, [('out_files',
'inputnode.bold_split')]),
(bold_hmc_wf, bold_mni_trans_wf, [('outputnode.xforms',
'inputnode.hmc_xforms')]),
(bold_reg_wf, bold_mni_trans_wf, [('outputnode.itk_bold_to_t1',
'inputnode.itk_bold_to_t1')]),
(bold_bold_trans_wf, bold_mni_trans_wf, [('outputnode.bold_mask',
'inputnode.bold_mask')]),
(bold_sdc_wf, bold_mni_trans_wf, [('outputnode.out_warp',
'inputnode.fieldwarp')]),
(bold_mni_trans_wf, outputnode,
[('outputnode.bold_mni', 'bold_mni'),
('outputnode.bold_mask_mni', 'bold_mask_mni')]),
])
if use_aroma: # ICA-AROMA workflow
"""
ica_aroma_report
Reportlet visualizing MELODIC ICs, with ICA-AROMA signal/noise labels
aroma_noise_ics
CSV of noise components identified by ICA-AROMA
melodic_mix
FSL MELODIC mixing matrix
nonaggr_denoised_file
BOLD series with non-aggressive ICA-AROMA denoising applied
"""
from .confounds import init_ica_aroma_wf
from ...interfaces import JoinTSVColumns
ica_aroma_wf = init_ica_aroma_wf(name='ica_aroma_wf',
ignore_aroma_err=ignore_aroma_err)
join = pe.Node(JoinTSVColumns(), name='aroma_confounds')
workflow.disconnect([
(bold_confounds_wf, outputnode, [
('outputnode.confounds_file', 'confounds'),
]),
])
workflow.connect([
(bold_hmc_wf, ica_aroma_wf, [('outputnode.movpar_file',
'inputnode.movpar_file')]),
(bold_mni_trans_wf, ica_aroma_wf,
[('outputnode.bold_mask_mni', 'inputnode.bold_mask_mni'),
('outputnode.bold_mni', 'inputnode.bold_mni')]),
(bold_confounds_wf, join, [('outputnode.confounds_file',
'in_file')]),
(ica_aroma_wf, join, [('outputnode.aroma_confounds',
'join_file')]),
(ica_aroma_wf, outputnode,
[('outputnode.aroma_noise_ics', 'aroma_noise_ics'),
('outputnode.melodic_mix', 'melodic_mix'),
('outputnode.nonaggr_denoised_file', 'nonaggr_denoised_file')
]),
(join, outputnode, [('out_file', 'confounds')]),
(ica_aroma_wf, func_reports_wf,
[('outputnode.out_report', 'inputnode.ica_aroma_report')]),
])
# SURFACES ##################################################################################
if freesurfer and any(space.startswith('fs') for space in output_spaces):
LOGGER.log(25, 'Creating BOLD surface-sampling workflow.')
bold_surf_wf = init_bold_surf_wf(mem_gb=mem_gb['resampled'],
output_spaces=output_spaces,
medial_surface_nan=medial_surface_nan,
name='bold_surf_wf')
workflow.connect([
(inputnode, bold_surf_wf,
[('t1_preproc', 'inputnode.t1_preproc'),
('subjects_dir', 'inputnode.subjects_dir'),
('subject_id', 'inputnode.subject_id'),
('t1_2_fsnative_forward_transform',
'inputnode.t1_2_fsnative_forward_transform')]),
(bold_reg_wf, bold_surf_wf, [('outputnode.bold_t1',
'inputnode.source_file')]),
(bold_surf_wf, outputnode, [('outputnode.surfaces', 'surfaces')]),
])
# REPORTING ############################################################
bold_bold_report_wf = init_bold_preproc_report_wf(
mem_gb=mem_gb['resampled'], reportlets_dir=reportlets_dir)
workflow.connect([
(inputnode, bold_bold_report_wf,
[('bold_file', 'inputnode.name_source'),
('bold_file', 'inputnode.in_pre')]), # This should be after STC
(bold_bold_trans_wf, bold_bold_report_wf, [('outputnode.bold',
'inputnode.in_post')]),
])
return workflow