def init_gifti_surface_wf(name='gifti_surface_wf'):
"""
Extract surfaces from FreeSurfer derivatives folder and
re-center GIFTI coordinates to align to native T1 space
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(['subjects_dir', 'subject_id']), name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(['surfaces']), name='outputnode')
get_surfaces = pe.Node(nio.FreeSurferSource(), name='get_surfaces')
midthickness = pe.MapNode(
MakeMidthickness(thickness=True, distance=0.5, out_name='midthickness'),
iterfield='in_file',
name='midthickness')
save_midthickness = pe.Node(nio.DataSink(parameterization=False),
name='save_midthickness')
surface_list = pe.Node(niu.Merge(4, ravel_inputs=True),
name='surface_list', run_without_submitting=True)
fs_2_gii = pe.MapNode(fs.MRIsConvert(out_datatype='gii'),
iterfield='in_file', name='fs_2_gii')
fix_surfs = pe.MapNode(NormalizeSurf(), iterfield='in_file', name='fix_surfs')
workflow.connect([
(inputnode, get_surfaces, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id')]),
(inputnode, save_midthickness, [('subjects_dir', 'base_directory'),
('subject_id', 'container')]),
# Generate midthickness surfaces and save to FreeSurfer derivatives
(get_surfaces, midthickness, [('smoothwm', 'in_file'),
('graymid', 'graymid')]),
(midthickness, save_midthickness, [('out_file', 'surf.@graymid')]),
# Produce valid GIFTI surface files (dense mesh)
(get_surfaces, surface_list, [('smoothwm', 'in1'),
('pial', 'in2'),
('inflated', 'in3')]),
(save_midthickness, surface_list, [('out_file', 'in4')]),
(surface_list, fs_2_gii, [('out', 'in_file')]),
(fs_2_gii, fix_surfs, [('converted', 'in_file')]),
(fix_surfs, outputnode, [('out_file', 'surfaces')]),
])
return workflow
def init_bold_surf_wf(mem_gb,
output_spaces,
medial_surface_nan,
name='bold_surf_wf'):
"""
This workflow samples functional images to FreeSurfer surfaces
For each vertex, the cortical ribbon is sampled at six points (spaced 20% of thickness apart)
and averaged.
Outputs are in GIFTI format.
.. workflow::
:graph2use: colored
:simple_form: yes
from fmriprep.workflows.bold import init_bold_surf_wf
wf = init_bold_surf_wf(mem_gb=0.1,
output_spaces=['T1w', 'fsnative',
'template', 'fsaverage5'],
medial_surface_nan=False)
**Parameters**
output_spaces : list
List of output spaces functional images are to be resampled to
Target spaces beginning with ``fs`` will be selected for resampling,
such as ``fsaverage`` or related template spaces
If the list contains ``fsnative``, images will be resampled to the
individual subject's native surface
medial_surface_nan : bool
Replace medial wall values with NaNs on functional GIFTI files
**Inputs**
source_file
Motion-corrected BOLD series in T1 space
t1_preproc
Bias-corrected structural template image
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
**Outputs**
surfaces
BOLD series, resampled to FreeSurfer surfaces
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'source_file', 't1_preproc', 'subject_id', 'subjects_dir',
't1_2_fsnative_forward_transform'
]),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=['surfaces']),
name='outputnode')
spaces = [space for space in output_spaces if space.startswith('fs')]
def select_target(subject_id, space):
""" Given a source subject ID and a target space, get the target subject ID """
return subject_id if space == 'fsnative' else space
targets = pe.MapNode(niu.Function(function=select_target),
iterfield=['space'],
name='targets',
mem_gb=DEFAULT_MEMORY_MIN_GB)
targets.inputs.space = spaces
# Rename the source file to the output space to simplify naming later
rename_src = pe.MapNode(niu.Rename(format_string='%(subject)s',
keep_ext=True),
iterfield='subject',
name='rename_src',
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
rename_src.inputs.subject = spaces
resampling_xfm = pe.Node(fs.utils.LTAConvert(in_lta='identity.nofile',
out_lta=True),
name='resampling_xfm')
set_xfm_source = pe.Node(ConcatenateLTA(out_type='RAS2RAS'),
name='set_xfm_source')
sampler = pe.MapNode(fs.SampleToSurface(sampling_method='average',
sampling_range=(0, 1, 0.2),
sampling_units='frac',
interp_method='trilinear',
cortex_mask=True,
override_reg_subj=True,
out_type='gii'),
iterfield=['source_file', 'target_subject'],
iterables=('hemi', ['lh', 'rh']),
name='sampler',
mem_gb=mem_gb * 3)
medial_nans = pe.MapNode(MedialNaNs(),
iterfield=['in_file', 'target_subject'],
name='medial_nans',
mem_gb=DEFAULT_MEMORY_MIN_GB)
merger = pe.JoinNode(niu.Merge(1, ravel_inputs=True),
name='merger',
joinsource='sampler',
joinfield=['in1'],
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
update_metadata = pe.MapNode(GiftiSetAnatomicalStructure(),
iterfield='in_file',
name='update_metadata',
mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, targets, [('subject_id', 'subject_id')]),
(inputnode, rename_src, [('source_file', 'in_file')]),
(inputnode, resampling_xfm, [('source_file', 'source_file'),
('t1_preproc', 'target_file')]),
(inputnode, set_xfm_source, [('t1_2_fsnative_forward_transform',
'in_lta2')]),
(resampling_xfm, set_xfm_source, [('out_lta', 'in_lta1')]),
(inputnode, sampler, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id')]),
(set_xfm_source, sampler, [('out_file', 'reg_file')]),
(targets, sampler, [('out', 'target_subject')]),
(rename_src, sampler, [('out_file', 'source_file')]),
(merger, update_metadata, [('out', 'in_file')]),
(update_metadata, outputnode, [('out_file', 'surfaces')]),
])
if medial_surface_nan:
workflow.connect([
(inputnode, medial_nans, [('subjects_dir', 'subjects_dir')]),
(sampler, medial_nans, [('out_file', 'in_file')]),
(targets, medial_nans, [('out', 'target_subject')]),
(medial_nans, merger, [('out', 'in1')]),
])
else:
workflow.connect(sampler, 'out_file', merger, 'in1')
return workflow
def init_bold_preproc_trans_wf(mem_gb,
omp_nthreads,
name='bold_preproc_trans_wf',
use_compression=True,
use_fieldwarp=False,
split_file=False,
interpolation='LanczosWindowedSinc'):
"""
This workflow resamples the input fMRI in its native (original)
space in a "single shot" from the original BOLD series.
.. workflow::
:graph2use: colored
:simple_form: yes
from fmriprep.workflows.bold import init_bold_preproc_trans_wf
wf = init_bold_preproc_trans_wf(mem_gb=3, omp_nthreads=1)
**Parameters**
mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: ``bold_mni_trans_wf``)
use_compression : bool
Save registered BOLD series as ``.nii.gz``
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to MNI
split_file : bool
Whether the input file should be splitted (it is a 4D file)
or it is a list of 3D files (default ``False``, do not split)
interpolation : str
Interpolation type to be used by ANTs' ``applyTransforms``
(default ``'LanczosWindowedSinc'``)
**Inputs**
bold_file
Individual 3D volumes, not motion corrected
bold_mask
Skull-stripping mask of reference image
name_source
BOLD series NIfTI file
Used to recover original information lost during processing
hmc_xforms
List of affine transforms aligning each volume to ``ref_image`` in ITK format
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
**Outputs**
bold
BOLD series, resampled in native space, including all preprocessing
bold_mask
BOLD series mask calculated with the new time-series
bold_ref
BOLD reference image: an average-like 3D image of the time-series
bold_ref_brain
Same as ``bold_ref``, but once the brain mask has been applied
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'name_source', 'bold_file', 'bold_mask', 'hmc_xforms', 'fieldwarp'
]),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(
fields=['bold', 'bold_mask', 'bold_ref', 'bold_ref_brain']),
name='outputnode')
bold_transform = pe.Node(MultiApplyTransforms(interpolation=interpolation,
float=True,
copy_dtype=True),
name='bold_transform',
mem_gb=mem_gb * 3 * omp_nthreads,
n_procs=omp_nthreads)
merge = pe.Node(Merge(compress=use_compression),
name='merge',
mem_gb=mem_gb * 3)
# Generate a new BOLD reference
bold_reference_wf = init_bold_reference_wf(omp_nthreads=omp_nthreads)
workflow.connect([
(inputnode, merge, [('name_source', 'header_source')]),
(bold_transform, merge, [('out_files', 'in_files')]),
(merge, bold_reference_wf, [('out_file', 'inputnode.bold_file')]),
(merge, outputnode, [('out_file', 'bold')]),
(bold_reference_wf, outputnode,
[('outputnode.ref_image', 'bold_ref'),
('outputnode.ref_image_brain', 'bold_ref_brain'),
('outputnode.bold_mask', 'bold_mask')]),
])
# Input file is not splitted
if split_file:
bold_split = pe.Node(FSLSplit(dimension='t'),
name='bold_split',
mem_gb=mem_gb * 3)
workflow.connect([(inputnode, bold_split, [('bold_file', 'in_file')]),
(bold_split, bold_transform, [
('out_files', 'input_image'),
(('out_files', _first), 'reference_image'),
])])
else:
workflow.connect([
(inputnode, bold_transform, [('bold_file', 'input_image'),
(('bold_file', _first),
'reference_image')]),
])
if use_fieldwarp:
merge_xforms = pe.Node(niu.Merge(2),
name='merge_xforms',
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, merge_xforms, [('fieldwarp', 'in1'),
('hmc_xforms', 'in2')]),
(merge_xforms, bold_transform, [('out', 'transforms')]),
])
else:
def _aslist(val):
return [val]
workflow.connect([
(inputnode, bold_transform, [(('hmc_xforms', _aslist),
'transforms')]),
])
# Code ready to generate a pre/post processing report
# 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
def init_bold_mni_trans_wf(template,
mem_gb,
omp_nthreads,
name='bold_mni_trans_wf',
template_out_grid='2mm',
use_compression=True,
use_fieldwarp=False):
"""
This workflow samples functional images to the MNI template in a "single shot"
from the original BOLD series.
.. workflow::
:graph2use: colored
:simple_form: yes
from fmriprep.workflows.bold import init_bold_mni_trans_wf
wf = init_bold_mni_trans_wf(template='MNI152NLin2009cAsym',
mem_gb=3,
omp_nthreads=1,
template_out_grid='native')
**Parameters**
template : str
Name of template targeted by ``template`` output space
mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: ``bold_mni_trans_wf``)
template_out_grid : str
Keyword ('native', '1mm' or '2mm') or path of custom reference
image for normalization.
use_compression : bool
Save registered BOLD series as ``.nii.gz``
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to MNI
**Inputs**
itk_bold_to_t1
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
t1_2_mni_forward_transform
ANTs-compatible affine-and-warp transform file
bold_split
Individual 3D volumes, not motion corrected
bold_mask
Skull-stripping mask of reference image
name_source
BOLD series NIfTI file
Used to recover original information lost during processing
hmc_xforms
List of affine transforms aligning each volume to ``ref_image`` in ITK format
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
**Outputs**
bold_mni
BOLD series, resampled to template space
bold_mask_mni
BOLD series mask in template space
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'itk_bold_to_t1', 't1_2_mni_forward_transform', 'name_source',
'bold_split', 'bold_mask', 'hmc_xforms', 'fieldwarp'
]),
name='inputnode')
outputnode = pe.Node(
niu.IdentityInterface(fields=['bold_mni', 'bold_mask_mni']),
name='outputnode')
def _aslist(in_value):
if isinstance(in_value, list):
return in_value
return [in_value]
gen_ref = pe.Node(GenerateSamplingReference(), name='gen_ref',
mem_gb=0.3) # 256x256x256 * 64 / 8 ~ 150MB)
template_str = nid.TEMPLATE_MAP[template]
gen_ref.inputs.fixed_image = op.join(nid.get_dataset(template_str),
'1mm_T1.nii.gz')
mask_mni_tfm = pe.Node(ApplyTransforms(interpolation='MultiLabel',
float=True),
name='mask_mni_tfm',
mem_gb=1)
# Write corrected file in the designated output dir
mask_merge_tfms = pe.Node(niu.Merge(2),
name='mask_merge_tfms',
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
nxforms = 4 if use_fieldwarp else 3
merge_xforms = pe.Node(niu.Merge(nxforms),
name='merge_xforms',
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([(inputnode, merge_xforms, [('hmc_xforms',
'in%d' % nxforms)])])
if use_fieldwarp:
workflow.connect([(inputnode, merge_xforms, [('fieldwarp', 'in3')])])
workflow.connect([
(inputnode, gen_ref, [(('bold_split', _first), 'moving_image')]),
(inputnode, mask_merge_tfms, [('t1_2_mni_forward_transform', 'in1'),
(('itk_bold_to_t1', _aslist), 'in2')]),
(mask_merge_tfms, mask_mni_tfm, [('out', 'transforms')]),
(mask_mni_tfm, outputnode, [('output_image', 'bold_mask_mni')]),
(inputnode, mask_mni_tfm, [('bold_mask', 'input_image')])
])
bold_to_mni_transform = pe.Node(MultiApplyTransforms(
interpolation="LanczosWindowedSinc", float=True, copy_dtype=True),
name='bold_to_mni_transform',
mem_gb=mem_gb * 3 * omp_nthreads,
n_procs=omp_nthreads)
merge = pe.Node(Merge(compress=use_compression),
name='merge',
mem_gb=mem_gb * 3)
workflow.connect([
(inputnode, merge_xforms, [('t1_2_mni_forward_transform', 'in1'),
(('itk_bold_to_t1', _aslist), 'in2')]),
(merge_xforms, bold_to_mni_transform, [('out', 'transforms')]),
(inputnode, merge, [('name_source', 'header_source')]),
(inputnode, bold_to_mni_transform, [('bold_split', 'input_image')]),
(bold_to_mni_transform, merge, [('out_files', 'in_files')]),
(merge, outputnode, [('out_file', 'bold_mni')]),
])
if template_out_grid == 'native':
workflow.connect([
(gen_ref, mask_mni_tfm, [('out_file', 'reference_image')]),
(gen_ref, bold_to_mni_transform, [('out_file', 'reference_image')
]),
])
elif template_out_grid == '1mm' or template_out_grid == '2mm':
mask_mni_tfm.inputs.reference_image = op.join(
nid.get_dataset(template_str),
'%s_brainmask.nii.gz' % template_out_grid)
bold_to_mni_transform.inputs.reference_image = op.join(
nid.get_dataset(template_str), '%s_T1.nii.gz' % template_out_grid)
else:
mask_mni_tfm.inputs.reference_image = template_out_grid
bold_to_mni_transform.inputs.reference_image = template_out_grid
return workflow
def init_gifti_surface_wf(name='gifti_surface_wf'):
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(['subjects_dir', 'subject_id']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(['surfaces']),
name='outputnode')
get_surfaces = pe.Node(nio.FreeSurferSource(), name='get_surfaces')
midthickness = pe.MapNode(MakeMidthickness(thickness=True,
distance=0.5,
out_name='midthickness'),
iterfield='in_file',
name='midthickness')
save_midthickness = pe.Node(nio.DataSink(parameterization=False),
name='save_midthickness')
surface_list = pe.Node(niu.Merge(4, ravel_inputs=True),
name='surface_list',
run_without_submitting=True)
fs_2_gii = pe.MapNode(fs.MRIsConvert(out_datatype='gii'),
iterfield='in_file',
name='fs_2_gii')
def normalize_surfs(in_file):
""" Re-center GIFTI coordinates to fit align to native T1 space
For midthickness surfaces, add MidThickness metadata
Coordinate update based on:
https://github.com/Washington-University/workbench/blob/1b79e56/src/Algorithms/AlgorithmSurfaceApplyAffine.cxx#L73-L91
and
https://github.com/Washington-University/Pipelines/blob/ae69b9a/PostFreeSurfer/scripts/FreeSurfer2CaretConvertAndRegisterNonlinear.sh#L147
"""
import os
import numpy as np
import nibabel as nib
img = nib.load(in_file)
pointset = img.get_arrays_from_intent('NIFTI_INTENT_POINTSET')[0]
coords = pointset.data
c_ras_keys = ('VolGeomC_R', 'VolGeomC_A', 'VolGeomC_S')
ras = np.array([float(pointset.metadata[key]) for key in c_ras_keys])
# Apply C_RAS translation to coordinates
pointset.data = (coords + ras).astype(coords.dtype)
secondary = nib.gifti.GiftiNVPairs('AnatomicalStructureSecondary',
'MidThickness')
geom_type = nib.gifti.GiftiNVPairs('GeometricType', 'Anatomical')
has_ass = has_geo = False
for nvpair in pointset.meta.data:
# Remove C_RAS translation from metadata to avoid double-dipping in FreeSurfer
if nvpair.name in c_ras_keys:
nvpair.value = '0.000000'
# Check for missing metadata
elif nvpair.name == secondary.name:
has_ass = True
elif nvpair.name == geom_type.name:
has_geo = True
fname = os.path.basename(in_file)
# Update metadata for MidThickness/graymid surfaces
if 'midthickness' in fname.lower() or 'graymid' in fname.lower():
if not has_ass:
pointset.meta.data.insert(1, secondary)
if not has_geo:
pointset.meta.data.insert(2, geom_type)
img.to_filename(fname)
return os.path.abspath(fname)
fix_surfs = pe.MapNode(niu.Function(function=normalize_surfs),
iterfield='in_file',
name='fix_surfs')
workflow.connect([
(inputnode, get_surfaces, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id')]),
(inputnode, save_midthickness, [('subjects_dir', 'base_directory'),
('subject_id', 'container')]),
# Generate midthickness surfaces and save to FreeSurfer derivatives
(get_surfaces, midthickness, [('smoothwm', 'in_file'),
('graymid', 'graymid')]),
(midthickness, save_midthickness, [('out_file', 'surf.@graymid')]),
# Produce valid GIFTI surface files (dense mesh)
(get_surfaces, surface_list, [('smoothwm', 'in1'), ('pial', 'in2'),
('inflated', 'in3')]),
(save_midthickness, surface_list, [('out_file', 'in4')]),
(surface_list, fs_2_gii, [('out', 'in_file')]),
(fs_2_gii, fix_surfs, [('converted', 'in_file')]),
(fix_surfs, outputnode, [('out', 'surfaces')]),
])
return workflow
def init_gifti_surface_wf(name='gifti_surface_wf'):
r"""
This workflow prepares GIFTI surfaces from a FreeSurfer subjects directory
If midthickness (or graymid) surfaces do not exist, they are generated and
saved to the subject directory as ``lh/rh.midthickness``.
These, along with the gray/white matter boundary (``lh/rh.smoothwm``), pial
sufaces (``lh/rh.pial``) and inflated surfaces (``lh/rh.inflated``) are
converted to GIFTI files.
Additionally, the vertex coordinates are :py:class:`recentered
<fmriprep.interfaces.NormalizeSurf>` to align with native T1w space.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.anatomical import init_gifti_surface_wf
wf = init_gifti_surface_wf()
**Inputs**
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
**Outputs**
surfaces
GIFTI surfaces for gray/white matter boundary, pial surface,
midthickness (or graymid) surface, and inflated surfaces
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(['subjects_dir', 'subject_id']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(['surfaces']),
name='outputnode')
get_surfaces = pe.Node(nio.FreeSurferSource(), name='get_surfaces')
midthickness = pe.MapNode(MakeMidthickness(thickness=True,
distance=0.5,
out_name='midthickness'),
iterfield='in_file',
name='midthickness')
save_midthickness = pe.Node(nio.DataSink(parameterization=False),
name='save_midthickness')
surface_list = pe.Node(niu.Merge(4, ravel_inputs=True),
name='surface_list',
run_without_submitting=True)
fs_2_gii = pe.MapNode(fs.MRIsConvert(out_datatype='gii'),
iterfield='in_file',
name='fs_2_gii')
fix_surfs = pe.MapNode(NormalizeSurf(),
iterfield='in_file',
name='fix_surfs')
workflow.connect([
(inputnode, get_surfaces, [('subjects_dir', 'subjects_dir'),
('subject_id', 'subject_id')]),
(inputnode, save_midthickness, [('subjects_dir', 'base_directory'),
('subject_id', 'container')]),
# Generate midthickness surfaces and save to FreeSurfer derivatives
(get_surfaces, midthickness, [('smoothwm', 'in_file'),
('graymid', 'graymid')]),
(midthickness, save_midthickness, [('out_file', 'surf.@graymid')]),
# Produce valid GIFTI surface files (dense mesh)
(get_surfaces, surface_list, [('smoothwm', 'in1'), ('pial', 'in2'),
('inflated', 'in3')]),
(save_midthickness, surface_list, [('out_file', 'in4')]),
(surface_list, fs_2_gii, [('out', 'in_file')]),
(fs_2_gii, fix_surfs, [('converted', 'in_file')]),
(fix_surfs, outputnode, [('out_file', 'surfaces')]),
])
return workflow
def individual_reports(settings, name='ReportsWorkflow'):
"""
Encapsulates nodes writing plots
.. workflow::
from mriqc.workflows.functional import individual_reports
wf = individual_reports(settings={'output_dir': 'out'})
"""
from ..interfaces import PlotMosaic, PlotSpikes
from ..reports import individual_html
verbose = settings.get('verbose_reports', False)
biggest_file_gb = settings.get("biggest_file_size_gb", 1)
pages = 5
extra_pages = 0
if verbose:
extra_pages = 4
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'in_iqms', 'in_ras', 'hmc_epi', 'epi_mean', 'brainmask', 'hmc_fd',
'fd_thres', 'epi_parc', 'in_dvars', 'in_stddev', 'outliers',
'in_spikes', 'in_fft', 'mni_report', 'ica_report'
]),
name='inputnode')
# Set FD threshold
inputnode.inputs.fd_thres = settings.get('fd_thres', 0.2)
spmask = pe.Node(niu.Function(input_names=['in_file', 'in_mask'],
output_names=['out_file', 'out_plot'],
function=spikes_mask),
name='SpikesMask',
mem_gb=biggest_file_gb * 3.5)
spikes_bg = pe.Node(Spikes(no_zscore=True, detrend=False),
name='SpikesFinderBgMask',
mem_gb=biggest_file_gb * 2.5)
bigplot = pe.Node(FMRISummary(),
name='BigPlot',
mem_gb=biggest_file_gb * 3.5)
workflow.connect([
(inputnode, spikes_bg, [('in_ras', 'in_file')]),
(inputnode, spmask, [('in_ras', 'in_file')]),
(inputnode, bigplot, [('hmc_epi', 'in_func'), ('brainmask', 'in_mask'),
('hmc_fd', 'fd'), ('fd_thres', 'fd_thres'),
('in_dvars', 'dvars'), ('epi_parc', 'in_segm'),
('outliers', 'outliers')]),
(spikes_bg, bigplot, [('out_tsz', 'in_spikes_bg')]),
(spmask, spikes_bg, [('out_file', 'in_mask')]),
])
mosaic_mean = pe.Node(PlotMosaic(out_file='plot_func_mean_mosaic1.svg',
cmap='Greys_r'),
name='PlotMosaicMean')
mosaic_stddev = pe.Node(PlotMosaic(
out_file='plot_func_stddev_mosaic2_stddev.svg', cmap='viridis'),
name='PlotMosaicSD')
mplots = pe.Node(
niu.Merge(pages + extra_pages +
int(settings.get('fft_spikes_detector', False)) +
int(settings.get('ica', False))),
name='MergePlots')
rnode = pe.Node(niu.Function(input_names=['in_iqms', 'in_plots'],
output_names=['out_file'],
function=individual_html),
name='GenerateReport')
# Link images that should be reported
dsplots = pe.Node(nio.DataSink(base_directory=settings['output_dir'],
parameterization=False),
name='dsplots')
dsplots.inputs.container = 'reports'
workflow.connect([
(inputnode, rnode, [('in_iqms', 'in_iqms')]),
(inputnode, mosaic_mean, [('epi_mean', 'in_file')]),
(inputnode, mosaic_stddev, [('in_stddev', 'in_file')]),
(mosaic_mean, mplots, [('out_file', 'in1')]),
(mosaic_stddev, mplots, [('out_file', 'in2')]),
(bigplot, mplots, [('out_file', 'in3')]),
(mplots, rnode, [('out', 'in_plots')]),
(rnode, dsplots, [('out_file', '@html_report')]),
])
if settings.get('fft_spikes_detector', False):
mosaic_spikes = pe.Node(PlotSpikes(out_file='plot_spikes.svg',
cmap='viridis',
title='High-Frequency spikes'),
name='PlotSpikes')
workflow.connect([(inputnode, mosaic_spikes, [('in_ras', 'in_file'),
('in_spikes',
'in_spikes'),
('in_fft', 'in_fft')]),
(mosaic_spikes, mplots, [('out_file', 'in4')])])
if settings.get('ica', False):
page_number = 4
if settings.get('fft_spikes_detector', False):
page_number += 1
workflow.connect([(inputnode, mplots, [('ica_report',
'in%d' % page_number)])])
if not verbose:
return workflow
mosaic_zoom = pe.Node(PlotMosaic(out_file='plot_anat_mosaic1_zoomed.svg',
cmap='Greys_r'),
name='PlotMosaicZoomed')
mosaic_noise = pe.Node(PlotMosaic(out_file='plot_anat_mosaic2_noise.svg',
only_noise=True,
cmap='viridis_r'),
name='PlotMosaicNoise')
# Verbose-reporting goes here
from ..interfaces.viz import PlotContours
plot_bmask = pe.Node(PlotContours(display_mode='z',
levels=[.5],
colors=['r'],
cut_coords=10,
out_file='bmask'),
name='PlotBrainmask')
workflow.connect([
(inputnode, plot_bmask, [('epi_mean', 'in_file'),
('brainmask', 'in_contours')]),
(inputnode, mosaic_zoom, [('epi_mean', 'in_file'),
('brainmask', 'bbox_mask_file')]),
(inputnode, mosaic_noise, [('epi_mean', 'in_file')]),
(mosaic_zoom, mplots, [('out_file', 'in%d' % (pages + 1))]),
(mosaic_noise, mplots, [('out_file', 'in%d' % (pages + 2))]),
(plot_bmask, mplots, [('out_file', 'in%d' % (pages + 3))]),
(inputnode, mplots, [('mni_report', 'in%d' % (pages + 4))]),
])
return workflow
def init_bold_confs_wf(mem_gb, use_aroma, ignore_aroma_err, metadata,
name="bold_confs_wf"):
"""
This workflow calculates confounds for a BOLD series, and aggregates them
into a :abbr:`TSV (tab-separated value)` file, for use as nuisance
regressors in a :abbr:`GLM (general linear model)`.
The following confounds are calculated, with column headings in parentheses:
#. Region-wise average signal (``CSF``, ``WhiteMatter``, ``GlobalSignal``)
#. DVARS - standard, nonstandard, and voxel-wise standard variants
(``stdDVARS``, ``non-stdDVARS``, ``vx-wisestdDVARS``)
#. Framewise displacement, based on MCFLIRT motion parameters
(``FramewiseDisplacement``)
#. Temporal CompCor (``tCompCorXX``)
#. Anatomical CompCor (``aCompCorXX``)
#. Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off
(``CosineXX``)
#. Non-steady-state volumes (``NonSteadyStateXX``)
#. Estimated head-motion parameters, in mm and rad
(``X``, ``Y``, ``Z``, ``RotX``, ``RotY``, ``RotZ``)
#. ICA-AROMA-identified noise components, if enabled
(``AROMAAggrCompXX``)
Prior to estimating aCompCor and tCompCor, non-steady-state volumes are
censored and high-pass filtered using a :abbr:`DCT (discrete cosine
transform)` basis.
The cosine basis, as well as one regressor per censored volume, are included
for convenience.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold.confounds import init_bold_confs_wf
wf = init_bold_confs_wf(
mem_gb=1,
use_aroma=True,
ignore_aroma_err=True,
metadata={})
**Parameters**
mem_gb : float
Size of BOLD file in GB - please note that this size
should be calculated after resamplings that may extend
the FoV
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
metadata : dict
BIDS metadata for BOLD file
**Inputs**
bold
BOLD image, after the prescribed corrections (STC, HMC and SDC)
when available.
bold_mask
BOLD series mask
movpar_file
SPM-formatted motion parameters file
t1_mask
Mask of the skull-stripped template image
t1_tpms
List of tissue probability maps in T1w space
t1_bold_xform
Affine matrix that maps the T1w space into alignment with
the native BOLD space
bold_mni
BOLD image resampled in MNI space (only if ``use_aroma`` enabled)
bold_mask_mni
Brain mask corresponding to the BOLD image resampled in MNI space
(only if ``use_aroma`` enabled)
**Outputs**
confounds_file
TSV of all aggregated confounds
confounds_list
List of calculated confounds for reporting
acompcor_report
Reportlet visualizing white-matter/CSF mask used for aCompCor
tcompcor_report
Reportlet visualizing ROI identified in tCompCor
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
**Subworkflows**
* :py:func:`~fmriprep.workflows.bold.confounds.init_ica_aroma_wf`
"""
inputnode = pe.Node(niu.IdentityInterface(
fields=['bold', 'bold_mask', 'movpar_file', 't1_mask', 't1_tpms',
't1_bold_xform', 'bold_mni', 'bold_mask_mni']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(
fields=['confounds_file', 'confounds_list', 'rois_report', 'ica_aroma_report',
'aroma_noise_ics', 'melodic_mix', 'nonaggr_denoised_file']),
name='outputnode')
# Get masks ready in T1w space
acc_tpm = pe.Node(AddTPMs(indices=[0, 2]), name='tpms_add_csf_wm') # acc stands for aCompCor
csf_roi = pe.Node(TPM2ROI(erode_mm=0, mask_erode_mm=30), name='csf_roi')
wm_roi = pe.Node(TPM2ROI(
erode_prop=0.6, mask_erode_prop=0.6**3), # 0.6 = radius; 0.6^3 = volume
name='wm_roi')
acc_roi = pe.Node(TPM2ROI(
erode_prop=0.6, mask_erode_prop=0.6**3), # 0.6 = radius; 0.6^3 = volume
name='acc_roi')
# Map ROIs in T1w space into BOLD space
csf_tfm = pe.Node(ApplyTransforms(interpolation='NearestNeighbor', float=True),
name='csf_tfm', mem_gb=0.1)
wm_tfm = pe.Node(ApplyTransforms(interpolation='NearestNeighbor', float=True),
name='wm_tfm', mem_gb=0.1)
acc_tfm = pe.Node(ApplyTransforms(interpolation='NearestNeighbor', float=True),
name='acc_tfm', mem_gb=0.1)
tcc_tfm = pe.Node(ApplyTransforms(interpolation='NearestNeighbor', float=True),
name='tcc_tfm', mem_gb=0.1)
# Ensure ROIs don't go off-limits (reduced FoV)
csf_msk = pe.Node(niu.Function(function=_maskroi), name='csf_msk')
wm_msk = pe.Node(niu.Function(function=_maskroi), name='wm_msk')
acc_msk = pe.Node(niu.Function(function=_maskroi), name='acc_msk')
tcc_msk = pe.Node(niu.Function(function=_maskroi), name='tcc_msk')
# DVARS
dvars = pe.Node(nac.ComputeDVARS(save_all=True, remove_zerovariance=True),
name="dvars", mem_gb=mem_gb)
# Frame displacement
fdisp = pe.Node(nac.FramewiseDisplacement(parameter_source="SPM"),
name="fdisp", mem_gb=mem_gb)
# a/t-CompCor
non_steady_state = pe.Node(nac.NonSteadyStateDetector(), name='non_steady_state')
tcompcor = pe.Node(nac.TCompCor(
components_file='tcompcor.tsv', pre_filter='cosine', save_pre_filter=True,
percentile_threshold=.05), name="tcompcor", mem_gb=mem_gb)
acompcor = pe.Node(nac.ACompCor(
components_file='acompcor.tsv', pre_filter='cosine', save_pre_filter=True),
name="acompcor", mem_gb=mem_gb)
# Set TR if present
if 'RepetitionTime' in metadata:
tcompcor.inputs.repetition_time = metadata['RepetitionTime']
acompcor.inputs.repetition_time = metadata['RepetitionTime']
# Global and segment regressors
mrg_lbl = pe.Node(niu.Merge(3), name='merge_rois', run_without_submitting=True)
signals = pe.Node(SignalExtraction(
detrend=True, class_labels=["CSF", "WhiteMatter", "GlobalSignal"]),
name="signals", mem_gb=mem_gb)
# Arrange confounds
add_header = pe.Node(AddTSVHeader(columns=["X", "Y", "Z", "RotX", "RotY", "RotZ"]),
name="add_header", mem_gb=0.01, run_without_submitting=True)
concat = pe.Node(GatherConfounds(), name="concat", mem_gb=0.01, run_without_submitting=True)
# Generate reportlet
mrg_compcor = pe.Node(niu.Merge(2), name='merge_compcor', run_without_submitting=True)
rois_plot = pe.Node(ROIsPlot(compress_report=True, colors=['r', 'b', 'magenta'],
generate_report=True), name='rois_plot')
def _pick_csf(files):
return files[0]
def _pick_wm(files):
return files[-1]
workflow = pe.Workflow(name=name)
workflow.connect([
# Massage ROIs (in T1w space)
(inputnode, acc_tpm, [('t1_tpms', 'in_files')]),
(inputnode, csf_roi, [(('t1_tpms', _pick_csf), 'in_tpm'),
('t1_mask', 'in_mask')]),
(inputnode, wm_roi, [(('t1_tpms', _pick_wm), 'in_tpm'),
('t1_mask', 'in_mask')]),
(inputnode, acc_roi, [('t1_mask', 'in_mask')]),
(acc_tpm, acc_roi, [('out_file', 'in_tpm')]),
# Map ROIs to BOLD
(inputnode, csf_tfm, [('bold_mask', 'reference_image'),
('t1_bold_xform', 'transforms')]),
(csf_roi, csf_tfm, [('roi_file', 'input_image')]),
(inputnode, wm_tfm, [('bold_mask', 'reference_image'),
('t1_bold_xform', 'transforms')]),
(wm_roi, wm_tfm, [('roi_file', 'input_image')]),
(inputnode, acc_tfm, [('bold_mask', 'reference_image'),
('t1_bold_xform', 'transforms')]),
(acc_roi, acc_tfm, [('roi_file', 'input_image')]),
(inputnode, tcc_tfm, [('bold_mask', 'reference_image'),
('t1_bold_xform', 'transforms')]),
(csf_roi, tcc_tfm, [('eroded_mask', 'input_image')]),
# Mask ROIs with bold_mask
(inputnode, csf_msk, [('bold_mask', 'in_mask')]),
(inputnode, wm_msk, [('bold_mask', 'in_mask')]),
(inputnode, acc_msk, [('bold_mask', 'in_mask')]),
(inputnode, tcc_msk, [('bold_mask', 'in_mask')]),
# connect inputnode to each non-anatomical confound node
(inputnode, dvars, [('bold', 'in_file'),
('bold_mask', 'in_mask')]),
(inputnode, fdisp, [('movpar_file', 'in_file')]),
# Calculate nonsteady state
(inputnode, non_steady_state, [('bold', 'in_file')]),
# tCompCor
(inputnode, tcompcor, [('bold', 'realigned_file')]),
(non_steady_state, tcompcor, [('n_volumes_to_discard', 'ignore_initial_volumes')]),
(tcc_tfm, tcc_msk, [('output_image', 'roi_file')]),
(tcc_msk, tcompcor, [('out', 'mask_files')]),
# aCompCor
(inputnode, acompcor, [('bold', 'realigned_file')]),
(non_steady_state, acompcor, [('n_volumes_to_discard', 'ignore_initial_volumes')]),
(acc_tfm, acc_msk, [('output_image', 'roi_file')]),
(acc_msk, acompcor, [('out', 'mask_files')]),
# Global signals extraction (constrained by anatomy)
(inputnode, signals, [('bold', 'in_file')]),
(csf_tfm, csf_msk, [('output_image', 'roi_file')]),
(csf_msk, mrg_lbl, [('out', 'in1')]),
(wm_tfm, wm_msk, [('output_image', 'roi_file')]),
(wm_msk, mrg_lbl, [('out', 'in2')]),
(inputnode, mrg_lbl, [('bold_mask', 'in3')]),
(mrg_lbl, signals, [('out', 'label_files')]),
# Collate computed confounds together
(inputnode, add_header, [('movpar_file', 'in_file')]),
(signals, concat, [('out_file', 'signals')]),
(dvars, concat, [('out_all', 'dvars')]),
(fdisp, concat, [('out_file', 'fd')]),
(tcompcor, concat, [('components_file', 'tcompcor'),
('pre_filter_file', 'cos_basis')]),
(acompcor, concat, [('components_file', 'acompcor')]),
(add_header, concat, [('out_file', 'motion')]),
# Set outputs
(concat, outputnode, [('confounds_file', 'confounds_file'),
('confounds_list', 'confounds_list')]),
(inputnode, rois_plot, [('bold', 'in_file'),
('bold_mask', 'in_mask')]),
(tcompcor, mrg_compcor, [('high_variance_masks', 'in1')]),
(acc_msk, mrg_compcor, [('out', 'in2')]),
(mrg_compcor, rois_plot, [('out', 'in_rois')]),
(rois_plot, outputnode, [('out_report', 'rois_report')]),
])
if use_aroma:
# ICA-AROMA
ica_aroma_wf = init_ica_aroma_wf(name='ica_aroma_wf',
ignore_aroma_err=ignore_aroma_err)
workflow.connect([
(inputnode, ica_aroma_wf, [('bold_mni', 'inputnode.bold_mni'),
('bold_mask_mni', 'inputnode.bold_mask_mni'),
('movpar_file', 'inputnode.movpar_file')]),
(ica_aroma_wf, concat,
[('outputnode.aroma_confounds', 'aroma')]),
(ica_aroma_wf, outputnode,
[('outputnode.out_report', 'ica_aroma_report'),
('outputnode.aroma_noise_ics', 'aroma_noise_ics'),
('outputnode.melodic_mix', 'melodic_mix'),
('outputnode.nonaggr_denoised_file', 'nonaggr_denoised_file')])
])
return workflow
def individual_reports(settings, name='ReportsWorkflow'):
"""
Encapsulates nodes writing plots
.. workflow::
from mriqc.workflows.anatomical import individual_reports
wf = individual_reports(settings={'output_dir': 'out'})
"""
from ..interfaces import PlotMosaic
from ..reports import individual_html
verbose = settings.get('verbose_reports', False)
pages = 2
extra_pages = 0
if verbose:
extra_pages = 7
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'in_ras', 'brainmask', 'headmask', 'airmask', 'artmask', 'rotmask',
'segmentation', 'inu_corrected', 'noisefit', 'in_iqms', 'mni_report'
]),
name='inputnode')
mosaic_zoom = pe.Node(PlotMosaic(out_file='plot_anat_mosaic1_zoomed.svg',
title='zoomed',
cmap='Greys_r'),
name='PlotMosaicZoomed')
mosaic_noise = pe.Node(PlotMosaic(out_file='plot_anat_mosaic2_noise.svg',
title='noise enhanced',
only_noise=True,
cmap='viridis_r'),
name='PlotMosaicNoise')
mplots = pe.Node(niu.Merge(pages + extra_pages), name='MergePlots')
rnode = pe.Node(niu.Function(input_names=['in_iqms', 'in_plots'],
output_names=['out_file'],
function=individual_html),
name='GenerateReport')
# Link images that should be reported
dsplots = pe.Node(nio.DataSink(base_directory=settings['output_dir'],
parameterization=False),
name='dsplots')
dsplots.inputs.container = 'reports'
workflow.connect([
(inputnode, rnode, [('in_iqms', 'in_iqms')]),
(inputnode, mosaic_zoom, [('in_ras', 'in_file'),
('brainmask', 'bbox_mask_file')]),
(inputnode, mosaic_noise, [('in_ras', 'in_file')]),
(mosaic_zoom, mplots, [('out_file', "in1")]),
(mosaic_noise, mplots, [('out_file', "in2")]),
(mplots, rnode, [('out', 'in_plots')]),
(rnode, dsplots, [('out_file', "@html_report")]),
])
if not verbose:
return workflow
from ..interfaces.viz import PlotContours
from ..viz.utils import plot_bg_dist
plot_bgdist = pe.Node(niu.Function(input_names=['in_file'],
output_names=['out_file'],
function=plot_bg_dist),
name='PlotBackground')
plot_segm = pe.Node(PlotContours(display_mode='z',
levels=[.5, 1.5, 2.5],
cut_coords=10,
colors=['r', 'g', 'b']),
name='PlotSegmentation')
plot_bmask = pe.Node(PlotContours(display_mode='z',
levels=[.5],
colors=['r'],
cut_coords=10,
out_file='bmask'),
name='PlotBrainmask')
plot_airmask = pe.Node(PlotContours(display_mode='x',
levels=[.5],
colors=['r'],
cut_coords=6,
out_file='airmask'),
name='PlotAirmask')
plot_headmask = pe.Node(PlotContours(display_mode='x',
levels=[.5],
colors=['r'],
cut_coords=6,
out_file='headmask'),
name='PlotHeadmask')
plot_artmask = pe.Node(PlotContours(display_mode='z',
levels=[.5],
colors=['r'],
cut_coords=10,
out_file='artmask',
saturate=True),
name='PlotArtmask')
workflow.connect([
(inputnode, plot_segm, [('in_ras', 'in_file'),
('segmentation', 'in_contours')]),
(inputnode, plot_bmask, [('in_ras', 'in_file'),
('brainmask', 'in_contours')]),
(inputnode, plot_headmask, [('in_ras', 'in_file'),
('headmask', 'in_contours')]),
(inputnode, plot_airmask, [('in_ras', 'in_file'),
('airmask', 'in_contours')]),
(inputnode, plot_artmask, [('in_ras', 'in_file'),
('artmask', 'in_contours')]),
(inputnode, plot_bgdist, [('noisefit', 'in_file')]),
(inputnode, mplots, [('mni_report', "in%d" % (pages + 1))]),
(plot_bmask, mplots, [('out_file', 'in%d' % (pages + 2))]),
(plot_segm, mplots, [('out_file', 'in%d' % (pages + 3))]),
(plot_artmask, mplots, [('out_file', 'in%d' % (pages + 4))]),
(plot_headmask, mplots, [('out_file', 'in%d' % (pages + 5))]),
(plot_airmask, mplots, [('out_file', 'in%d' % (pages + 6))]),
(plot_bgdist, mplots, [('out_file', 'in%d' % (pages + 7))])
])
return workflow
def init_bold_confs_wf(bold_file_size_gb,
use_aroma,
ignore_aroma_err,
metadata,
name="bold_confs_wf"):
"""
This workflow calculates confounds for a BOLD series, and aggregates them
into a :abbr:`TSV (tab-separated value)` file, for use as nuisance
regressors in a :abbr:`GLM (general linear model)`.
The following confounds are calculated, with column headings in parentheses:
#. White matter / global signals (WhiteMatter, GlobalSignal)
#. DVARS - standard, nonstandard, and voxel-wise standard variants
(stdDVARS, non-stdDVARS, vx-wisestdDVARS)
#. Framewise displacement, based on MCFLIRT motion parameters (FramewiseDisplacement)
#. tCompCor
#. aCompCor
#. Cosine basis set for high-pass filtering w/ 0.008 Hz cut-off (CosineXX)
#. Non-steady-state volumes (NonSteadyStateXX)
#. MCFLIRT motion parameters, in mm and rad (X, Y, Z, RotX, RotY, RotZ)
#. ICA-AROMA-identified noise components, if enabled (AROMAAggrCompXX)
Prior to estimating aCompCor and tCompCor, non-steady-state volumes are
censored and high-pass filtered using a :abbr:`DCT (discrete cosine
transform)` basis.
The cosine basis, as well as one regressor per censored volume, are included
for convenience.
.. workflow::
:graph2use: orig
:simpleform: yes
from fmriprep.workflows.confounds import init_bold_confs_wf
wf = init_bold_confs_wf(bold_file_size_gb=1,
use_aroma=True,
ignore_aroma_err=True,
metadata={})
Parameters
bold_file_size_gb : float
Size of BOLD file in GB
use_aroma : bool
Perform ICA-AROMA on MNI-resampled functional series
ignore_aroma_err : bool
Do not fail on ICA-AROMA errors
metadata : dict
BIDS metadata for BOLD file
Inputs
bold_t1
BOLD image, resampled in T1w space
movpar_file
SPM-formatted motion parameters file
t1_mask
Mask of the skull-stripped template image
t1_tpms
List of tissue probability maps in 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
Outputs
confounds_file
TSV of all aggregated confounds
confounds_list
List of calculated confounds for reporting
acompcor_report
Reportlet visualizing white-matter/CSF mask used for aCompCor
tcompcor_report
Reportlet visualizing ROI identified in tCompCor
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
"""
inputnode = pe.Node(niu.IdentityInterface(fields=[
'bold_t1', 'movpar_file', 't1_mask', 't1_tpms', 'bold_mask_t1',
'bold_mni', 'bold_mask_mni'
]),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=[
'confounds_file', 'confounds_list', 'acompcor_report',
'tcompcor_report', 'ica_aroma_report', 'aroma_noise_ics',
'melodic_mix', 'nonaggr_denoised_file'
]),
name='outputnode')
# ICA-AROMA
if use_aroma:
ica_aroma_wf = init_ica_aroma_wf(name='ica_aroma_wf',
ignore_aroma_err=ignore_aroma_err)
# DVARS
dvars = pe.Node(nac.ComputeDVARS(save_all=True, remove_zerovariance=True),
name="dvars",
mem_gb=bold_file_size_gb * 3)
# Frame displacement
fdisp = pe.Node(nac.FramewiseDisplacement(parameter_source="SPM"),
name="fdisp",
mem_gb=bold_file_size_gb * 3)
# CompCor
non_steady_state = pe.Node(nac.NonSteadyStateDetector(),
name='non_steady_state')
tcompcor = pe.Node(TCompCorRPT(components_file='tcompcor.tsv',
generate_report=True,
pre_filter='cosine',
save_pre_filter=True,
percentile_threshold=.05),
name="tcompcor",
mem_gb=bold_file_size_gb * 3)
acompcor = pe.Node(ACompCorRPT(components_file='acompcor.tsv',
pre_filter='cosine',
save_pre_filter=True,
generate_report=True),
name="acompcor",
mem_gb=bold_file_size_gb * 3)
csf_roi = pe.Node(TPM2ROI(erode_mm=0, mask_erode_mm=30), name='csf_roi')
wm_roi = pe.Node(TPM2ROI(erode_mm=6, mask_erode_mm=10), name='wm_roi')
merge_rois = pe.Node(niu.Merge(2),
name='merge_rois',
run_without_submitting=True,
mem_gb=0.01)
combine_rois = pe.Node(CombineROIs(), name='combine_rois')
concat_rois = pe.Node(ConcatROIs(), name='concat_rois')
# Global and segment regressors
signals = pe.Node(SignalExtraction(
detrend=True, class_labels=["WhiteMatter", "GlobalSignal"]),
name="signals",
mem_gb=bold_file_size_gb * 3)
# Arrange confounds
add_header = pe.Node(
AddTSVHeader(columns=["X", "Y", "Z", "RotX", "RotY", "RotZ"]),
name="add_header",
mem_gb=0.01,
run_without_submitting=True)
concat = pe.Node(GatherConfounds(),
name="concat",
mem_gb=0.01,
run_without_submitting=True)
# Set TR if present
if 'RepetitionTime' in metadata:
tcompcor.inputs.repetition_time = metadata['RepetitionTime']
acompcor.inputs.repetition_time = metadata['RepetitionTime']
def _pick_csf(files):
return files[0]
def _pick_wm(files):
return files[2]
workflow = pe.Workflow(name=name)
workflow.connect([
# connect inputnode to each non-anatomical confound node
(inputnode, dvars, [('bold_t1', 'in_file'),
('bold_mask_t1', 'in_mask')]),
(inputnode, fdisp, [('movpar_file', 'in_file')]),
(inputnode, non_steady_state, [('bold_t1', 'in_file')]),
(inputnode, tcompcor, [('bold_t1', 'realigned_file')]),
(non_steady_state, tcompcor, [('n_volumes_to_discard',
'ignore_initial_volumes')]),
(non_steady_state, acompcor, [('n_volumes_to_discard',
'ignore_initial_volumes')]),
(inputnode, csf_roi, [(('t1_tpms', _pick_csf), 't1_tpm'),
('t1_mask', 't1_mask'),
('bold_mask_t1', 'bold_mask')]),
(csf_roi, tcompcor, [('eroded_mask', 'mask_files')]),
(inputnode, wm_roi, [(('t1_tpms', _pick_wm), 't1_tpm'),
('t1_mask', 't1_mask'),
('bold_mask_t1', 'bold_mask')]),
(csf_roi, merge_rois, [('roi_file', 'in1')]),
(wm_roi, merge_rois, [('roi_file', 'in2')]),
(merge_rois, combine_rois, [('out', 'in_files')]),
(inputnode, combine_rois, [('bold_t1', 'ref_header')]),
# anatomical confound: aCompCor.
(inputnode, acompcor, [('bold_t1', 'realigned_file')]),
(combine_rois, acompcor, [('out_file', 'mask_files')]),
(wm_roi, concat_rois, [('roi_file', 'in_file')]),
(inputnode, concat_rois, [('bold_mask_t1', 'in_mask')]),
(inputnode, concat_rois, [('bold_t1', 'ref_header')]),
# anatomical confound: signal extraction
(concat_rois, signals, [('out_file', 'label_files')]),
(inputnode, signals, [('bold_t1', 'in_file')]),
# connect the confound nodes to the concatenate node
(inputnode, add_header, [('movpar_file', 'in_file')]),
(signals, concat, [('out_file', 'signals')]),
(dvars, concat, [('out_all', 'dvars')]),
(fdisp, concat, [('out_file', 'fd')]),
(tcompcor, concat, [('components_file', 'tcompcor'),
('pre_filter_file', 'cos_basis')]),
(acompcor, concat, [('components_file', 'acompcor')]),
(add_header, concat, [('out_file', 'motion')]),
(concat, outputnode, [('confounds_file', 'confounds_file'),
('confounds_list', 'confounds_list')]),
(acompcor, outputnode, [('out_report', 'acompcor_report')]),
(tcompcor, outputnode, [('out_report', 'tcompcor_report')]),
])
if use_aroma:
workflow.connect([
(inputnode, ica_aroma_wf,
[('bold_mni', 'inputnode.bold_mni'),
('bold_mask_mni', 'inputnode.bold_mask_mni'),
('movpar_file', 'inputnode.movpar_file')]),
(ica_aroma_wf, concat, [('outputnode.aroma_confounds', 'aroma')]),
(ica_aroma_wf, outputnode,
[('outputnode.out_report', 'ica_aroma_report'),
('outputnode.aroma_noise_ics', 'aroma_noise_ics'),
('outputnode.melodic_mix', 'melodic_mix'),
('outputnode.nonaggr_denoised_file', 'nonaggr_denoised_file')])
])
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_bold_reg_wf(freesurfer, use_bbr, bold2t1w_dof, mem_gb, omp_nthreads,
name='bold_reg_wf', use_compression=True,
use_fieldwarp=False):
"""
This workflow registers the reference BOLD image to T1-space, using a
boundary-based registration (BBR) cost function.
If FreeSurfer-based preprocessing is enabled, the ``bbregister`` utility
is used to align the BOLD images to the reconstructed subject, and the
resulting transform is adjusted to target the T1 space.
If FreeSurfer-based preprocessing is disabled, FSL FLIRT is used with the
BBR cost function to directly target the T1 space.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold.registration import init_bold_reg_wf
wf = init_bold_reg_wf(freesurfer=True,
mem_gb=3,
omp_nthreads=1,
use_bbr=True,
bold2t1w_dof=9)
**Parameters**
freesurfer : bool
Enable FreeSurfer functional registration (bbregister)
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
mem_gb : float
Size of BOLD file in GB
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: ``bold_reg_wf``)
use_compression : bool
Save registered BOLD series as ``.nii.gz``
use_fieldwarp : bool
Include SDC warp in single-shot transform from BOLD to T1
**Inputs**
name_source
BOLD series NIfTI file
Used to recover original information lost during processing
ref_bold_brain
Reference image to which BOLD series is aligned
If ``fieldwarp == True``, ``ref_bold_brain`` should be unwarped
ref_bold_mask
Skull-stripping mask of reference image
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_aseg
FreeSurfer's ``aseg.mgz`` atlas projected into the T1w reference
(only if ``recon-all`` was run).
t1_aparc
FreeSurfer's ``aparc+aseg.mgz`` atlas projected into the T1w reference
(only if ``recon-all`` was run).
bold_split
Individual 3D BOLD volumes, not motion corrected
hmc_xforms
List of affine transforms aligning each volume to ``ref_image`` in ITK format
subjects_dir
FreeSurfer SUBJECTS_DIR
subject_id
FreeSurfer subject ID
t1_2_fsnative_reverse_transform
LTA-style affine matrix translating from FreeSurfer-conformed subject space to T1w
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
**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)
bold_t1
Motion-corrected BOLD series in T1 space
bold_mask_t1
BOLD mask in T1 space
bold_aseg_t1
FreeSurfer's ``aseg.mgz`` atlas, in T1w-space at the BOLD resolution
(only if ``recon-all`` was run).
bold_aparc_t1
FreeSurfer's ``aparc+aseg.mgz`` atlas, in T1w-space at the BOLD resolution
(only if ``recon-all`` was run).
out_report
Reportlet visualizing quality of registration
fallback
Boolean indicating whether BBR was rejected (mri_coreg registration returned)
**Subworkflows**
* :py:func:`~fmriprep.workflows.util.init_bbreg_wf`
* :py:func:`~fmriprep.workflows.util.init_fsl_bbr_wf`
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface(
fields=['name_source', 'ref_bold_brain', 'ref_bold_mask',
't1_preproc', 't1_brain', 't1_mask', 't1_seg',
't1_aseg', 't1_aparc', 'bold_split', 'hmc_xforms',
'subjects_dir', 'subject_id', 't1_2_fsnative_reverse_transform', 'fieldwarp']),
name='inputnode'
)
outputnode = pe.Node(
niu.IdentityInterface(fields=[
'itk_bold_to_t1', 'itk_t1_to_bold', 'out_report', 'fallback',
'bold_t1', 'bold_mask_t1', 'bold_aseg_t1', 'bold_aparc_t1']),
name='outputnode'
)
if freesurfer:
bbr_wf = init_bbreg_wf(use_bbr=use_bbr, bold2t1w_dof=bold2t1w_dof,
omp_nthreads=omp_nthreads)
else:
bbr_wf = init_fsl_bbr_wf(use_bbr=use_bbr, bold2t1w_dof=bold2t1w_dof)
workflow.connect([
(inputnode, bbr_wf, [
('ref_bold_brain', 'inputnode.in_file'),
('t1_2_fsnative_reverse_transform', 'inputnode.t1_2_fsnative_reverse_transform'),
('subjects_dir', 'inputnode.subjects_dir'),
('subject_id', 'inputnode.subject_id'),
('t1_seg', 'inputnode.t1_seg'),
('t1_brain', 'inputnode.t1_brain')]),
(bbr_wf, outputnode, [('outputnode.itk_bold_to_t1', 'itk_bold_to_t1'),
('outputnode.itk_t1_to_bold', 'itk_t1_to_bold'),
('outputnode.out_report', 'out_report'),
('outputnode.fallback', 'fallback')]),
])
gen_ref = pe.Node(GenerateSamplingReference(), name='gen_ref',
mem_gb=0.3) # 256x256x256 * 64 / 8 ~ 150MB
mask_t1w_tfm = pe.Node(
ApplyTransforms(interpolation='MultiLabel', float=True),
name='mask_t1w_tfm', mem_gb=0.1
)
workflow.connect([
(inputnode, gen_ref, [('ref_bold_brain', 'moving_image'),
('t1_brain', 'fixed_image'),
('t1_mask', 'fov_mask')]),
(inputnode, mask_t1w_tfm, [('ref_bold_mask', 'input_image')]),
(gen_ref, mask_t1w_tfm, [('out_file', 'reference_image')]),
(bbr_wf, mask_t1w_tfm, [('outputnode.itk_bold_to_t1', 'transforms')]),
(mask_t1w_tfm, outputnode, [('output_image', 'bold_mask_t1')]),
])
if freesurfer:
# Resample aseg and aparc in T1w space (no transforms needed)
aseg_t1w_tfm = pe.Node(
ApplyTransforms(interpolation='MultiLabel', transforms='identity', float=True),
name='aseg_t1w_tfm', mem_gb=0.1)
aparc_t1w_tfm = pe.Node(
ApplyTransforms(interpolation='MultiLabel', transforms='identity', float=True),
name='aparc_t1w_tfm', mem_gb=0.1)
workflow.connect([
(inputnode, aseg_t1w_tfm, [('t1_aseg', 'input_image')]),
(inputnode, aparc_t1w_tfm, [('t1_aparc', 'input_image')]),
(gen_ref, aseg_t1w_tfm, [('out_file', 'reference_image')]),
(gen_ref, aparc_t1w_tfm, [('out_file', 'reference_image')]),
(aseg_t1w_tfm, outputnode, [('output_image', 'bold_aseg_t1')]),
(aparc_t1w_tfm, outputnode, [('output_image', 'bold_aparc_t1')]),
])
# Merge transforms placing the head motion correction last
nforms = 2 + int(use_fieldwarp)
merge_xforms = pe.Node(niu.Merge(nforms), name='merge_xforms',
run_without_submitting=True, mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, merge_xforms, [('hmc_xforms', 'in%d' % nforms)])
])
if use_fieldwarp:
workflow.connect([
(inputnode, merge_xforms, [('fieldwarp', 'in2')])
])
bold_to_t1w_transform = pe.Node(
MultiApplyTransforms(interpolation="LanczosWindowedSinc", float=True, copy_dtype=True),
name='bold_to_t1w_transform', mem_gb=mem_gb * 3 * omp_nthreads, n_procs=omp_nthreads)
merge = pe.Node(Merge(compress=use_compression), name='merge', mem_gb=mem_gb)
workflow.connect([
(bbr_wf, merge_xforms, [('outputnode.itk_bold_to_t1', 'in1')]),
(merge_xforms, bold_to_t1w_transform, [('out', 'transforms')]),
(inputnode, merge, [('name_source', 'header_source')]),
(merge, outputnode, [('out_file', 'bold_t1')]),
(inputnode, bold_to_t1w_transform, [('bold_split', 'input_image')]),
(gen_ref, bold_to_t1w_transform, [('out_file', 'reference_image')]),
(bold_to_t1w_transform, merge, [('out_files', 'in_files')]),
])
return workflow
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_nonlinear_sdc_wf(bold_file,
freesurfer,
bold2t1w_dof,
template,
omp_nthreads,
bold_pe='j',
atlas_threshold=3,
name='nonlinear_sdc_wf'):
"""
This workflow takes a skull-stripped T1w image and reference BOLD image and
estimates a susceptibility distortion correction warp, using ANTs symmetric
normalization (SyN) and the average fieldmap atlas described in
[Treiber2016]_.
SyN deformation is restricted to the phase-encoding (PE) direction.
If no PE direction is specified, anterior-posterior PE is assumed.
SyN deformation is also restricted to regions that are expected to have a
>3mm (approximately 1 voxel) warp, based on the fieldmap atlas.
This technique is a variation on those developed in [Huntenburg2014]_ and
[Wang2017]_.
.. workflow ::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.fieldmap.syn import init_nonlinear_sdc_wf
wf = init_nonlinear_sdc_wf(
bold_file='/dataset/sub-01/func/sub-01_task-rest_bold.nii.gz',
bold_pe='j',
freesurfer=True,
bold2t1w_dof=9,
template='MNI152NLin2009cAsym',
omp_nthreads=8)
**Inputs**
t1_brain
skull-stripped, bias-corrected structural image
bold_ref
skull-stripped reference image
t1_seg
FAST segmentation white and gray matter, in native T1w space
t1_2_mni_reverse_transform
inverse registration transform of T1w image to MNI template
**Outputs**
out_reference_brain
the ``bold_ref`` image after unwarping
out_warp
the corresponding :abbr:`DFM (displacements field map)` compatible with
ANTs
out_mask
mask of the unwarped input file
out_mask_report
reportlet for the skullstripping
.. [Huntenburg2014] Huntenburg, J. M. (2014) Evaluating Nonlinear
Coregistration of BOLD EPI and T1w Images. Berlin: Master
Thesis, Freie Universität. `PDF
<http://pubman.mpdl.mpg.de/pubman/item/escidoc:2327525:5/component/escidoc:2327523/master_thesis_huntenburg_4686947.pdf>`_.
.. [Treiber2016] Treiber, J. M. et al. (2016) Characterization and Correction
of Geometric Distortions in 814 Diffusion Weighted Images,
PLoS ONE 11(3): e0152472. doi:`10.1371/journal.pone.0152472
<https://doi.org/10.1371/journal.pone.0152472>`_.
.. [Wang2017] Wang S, et al. (2017) Evaluation of Field Map and Nonlinear
Registration Methods for Correction of Susceptibility Artifacts
in Diffusion MRI. Front. Neuroinform. 11:17.
doi:`10.3389/fninf.2017.00017
<https://doi.org/10.3389/fninf.2017.00017>`_.
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(
['t1_brain', 'bold_ref', 't1_2_mni_reverse_transform', 't1_seg']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface([
'out_reference_brain', 'out_mask', 'out_warp', 'out_warp_report',
'out_mask_report'
]),
name='outputnode')
if bold_pe is None or bold_pe[0] not in ['i', 'j']:
LOGGER.warning(
'Incorrect phase-encoding direction, assuming PA (posterior-to-anterior'
)
bold_pe = 'j'
# Collect predefined data
# Atlas image and registration affine
atlas_img = pkgr.resource_filename('fmriprep', 'data/fmap_atlas.nii.gz')
atlas_2_template_affine = pkgr.resource_filename(
'fmriprep', 'data/fmap_atlas_2_{}_affine.mat'.format(template))
# Registration specifications
affine_transform = pkgr.resource_filename('fmriprep', 'data/affine.json')
syn_transform = pkgr.resource_filename('fmriprep',
'data/susceptibility_syn.json')
invert_t1w = pe.Node(InvertT1w(), name='invert_t1w', mem_gb=0.3)
ref_2_t1 = pe.Node(Registration(from_file=affine_transform),
name='ref_2_t1',
n_procs=omp_nthreads)
t1_2_ref = pe.Node(ApplyTransforms(invert_transform_flags=[True]),
name='t1_2_ref',
n_procs=omp_nthreads)
# 1) BOLD -> T1; 2) MNI -> T1; 3) ATLAS -> MNI
transform_list = pe.Node(niu.Merge(3),
name='transform_list',
mem_gb=DEFAULT_MEMORY_MIN_GB)
transform_list.inputs.in3 = atlas_2_template_affine
# Inverting (1), then applying in reverse order:
#
# ATLAS -> MNI -> T1 -> BOLD
atlas_2_ref = pe.Node(
ApplyTransforms(invert_transform_flags=[True, False, False]),
name='atlas_2_ref',
n_procs=omp_nthreads,
mem_gb=0.3)
atlas_2_ref.inputs.input_image = atlas_img
threshold_atlas = pe.Node(fsl.maths.MathsCommand(
args='-thr {:.8g} -bin'.format(atlas_threshold),
output_datatype='char'),
name='threshold_atlas',
mem_gb=0.3)
fixed_image_masks = pe.Node(niu.Merge(2),
name='fixed_image_masks',
mem_gb=DEFAULT_MEMORY_MIN_GB)
fixed_image_masks.inputs.in1 = 'NULL'
restrict = [[int(bold_pe[0] == 'i'), int(bold_pe[0] == 'j'), 0]] * 2
syn = pe.Node(Registration(from_file=syn_transform,
restrict_deformation=restrict),
name='syn',
n_procs=omp_nthreads)
seg_2_ref = pe.Node(ApplyTransforms(interpolation='NearestNeighbor',
float=True,
invert_transform_flags=[True]),
name='seg_2_ref',
n_procs=omp_nthreads,
mem_gb=0.3)
sel_wm = pe.Node(niu.Function(function=extract_wm),
name='sel_wm',
mem_gb=DEFAULT_MEMORY_MIN_GB)
syn_rpt = pe.Node(SimpleBeforeAfter(), name='syn_rpt', mem_gb=0.1)
skullstrip_bold_wf = init_skullstrip_bold_wf()
workflow.connect([
(inputnode, invert_t1w, [('t1_brain', 'in_file'),
('bold_ref', 'ref_file')]),
(inputnode, ref_2_t1, [('bold_ref', 'moving_image')]),
(invert_t1w, ref_2_t1, [('out_file', 'fixed_image')]),
(inputnode, t1_2_ref, [('bold_ref', 'reference_image')]),
(invert_t1w, t1_2_ref, [('out_file', 'input_image')]),
(ref_2_t1, t1_2_ref, [('forward_transforms', 'transforms')]),
(ref_2_t1, transform_list, [('forward_transforms', 'in1')]),
(inputnode, transform_list, [('t1_2_mni_reverse_transform', 'in2')]),
(inputnode, atlas_2_ref, [('bold_ref', 'reference_image')]),
(transform_list, atlas_2_ref, [('out', 'transforms')]),
(atlas_2_ref, threshold_atlas, [('output_image', 'in_file')]),
(threshold_atlas, fixed_image_masks, [('out_file', 'in2')]),
(inputnode, syn, [('bold_ref', 'moving_image')]),
(t1_2_ref, syn, [('output_image', 'fixed_image')]),
(fixed_image_masks, syn, [('out', 'fixed_image_masks')]),
(inputnode, seg_2_ref, [('t1_seg', 'input_image')]),
(ref_2_t1, seg_2_ref, [('forward_transforms', 'transforms')]),
(syn, seg_2_ref, [('warped_image', 'reference_image')]),
(seg_2_ref, sel_wm, [('output_image', 'in_seg')]),
(inputnode, syn_rpt, [('bold_ref', 'before')]),
(syn, syn_rpt, [('warped_image', 'after')]),
(sel_wm, syn_rpt, [('out', 'wm_seg')]),
(syn, skullstrip_bold_wf, [('warped_image', 'inputnode.in_file')]),
(syn, outputnode, [('forward_transforms', 'out_warp')]),
(skullstrip_bold_wf, outputnode,
[('outputnode.skull_stripped_file', 'out_reference_brain'),
('outputnode.mask_file', 'out_mask'),
('outputnode.out_report', 'out_mask_report')]),
(syn_rpt, outputnode, [('out_report', 'out_warp_report')])
])
return workflow
def init_bold_confs_wf(bold_file_size_gb,
use_aroma,
ignore_aroma_err,
metadata,
name="bold_confs_wf"):
''' All input fields are required.
Calculates global regressor and tCompCor
from motion-corrected fMRI ('inputnode.fmri_file').
Calculates DVARS from the fMRI and an EPI brain mask ('inputnode.bold_mask')
Calculates frame displacement from MCFLIRT movement parameters ('inputnode.movpar_file')
Calculates segment regressors and aCompCor
from the fMRI and a white matter/gray matter/CSF segmentation ('inputnode.t1_seg'), after
applying the transform to the images. Transforms should be fsl-formatted.
Calculates noise components identified from ICA-AROMA (if ``use_aroma=True``)
Saves the confounds in a file ('outputnode.confounds_file')'''
inputnode = pe.Node(niu.IdentityInterface(fields=[
'fmri_file', 'movpar_file', 't1_mask', 't1_tpms', 'bold_mask',
'bold_mni', 'bold_mask_mni'
]),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=[
'confounds_file', 'confounds_list', 'acompcor_report',
'tcompcor_report', 'ica_aroma_report', 'aroma_noise_ics',
'melodic_mix', 'nonaggr_denoised_file'
]),
name='outputnode')
# ICA-AROMA
if use_aroma:
ica_aroma_wf = init_ica_aroma_wf(name='ica_aroma_wf',
ignore_aroma_err=ignore_aroma_err)
# DVARS
dvars = pe.Node(nac.ComputeDVARS(save_all=True, remove_zerovariance=True),
name="dvars",
mem_gb=bold_file_size_gb * 3)
# Frame displacement
fdisp = pe.Node(nac.FramewiseDisplacement(parameter_source="SPM"),
name="fdisp",
mem_gb=bold_file_size_gb * 3)
# CompCor
non_steady_state = pe.Node(nac.NonSteadyStateDetector(),
name='non_steady_state')
tcompcor = pe.Node(TCompCorRPT(components_file='tcompcor.tsv',
generate_report=True,
pre_filter='cosine',
save_pre_filter=True,
percentile_threshold=.05),
name="tcompcor",
mem_gb=bold_file_size_gb * 3)
acompcor = pe.Node(ACompCorRPT(components_file='acompcor.tsv',
pre_filter='cosine',
save_pre_filter=True,
generate_report=True),
name="acompcor",
mem_gb=bold_file_size_gb * 3)
csf_roi = pe.Node(TPM2ROI(erode_mm=0, mask_erode_mm=30), name='csf_roi')
wm_roi = pe.Node(TPM2ROI(erode_mm=6, mask_erode_mm=10), name='wm_roi')
merge_rois = pe.Node(niu.Merge(2),
name='merge_rois',
run_without_submit=True,
mem_gb=0.01)
combine_rois = pe.Node(CombineROIs(), name='combine_rois')
concat_rois = pe.Node(ConcatROIs(), name='concat_rois')
# Global and segment regressors
signals = pe.Node(SignalExtraction(
detrend=True, class_labels=["WhiteMatter", "GlobalSignal"]),
name="signals",
mem_gb=bold_file_size_gb * 3)
# Arrange confounds
add_header = pe.Node(
AddTSVHeader(columns=["X", "Y", "Z", "RotX", "RotY", "RotZ"]),
name="add_header",
mem_gb=0.01,
run_without_submit=True)
concat = pe.Node(GatherConfounds(),
name="concat",
mem_gb=0.01,
run_without_submit=True)
# Set TR if present
if 'RepetitionTime' in metadata:
tcompcor.inputs.repetition_time = metadata['RepetitionTime']
acompcor.inputs.repetition_time = metadata['RepetitionTime']
def _pick_csf(files):
return files[0]
def _pick_wm(files):
return files[2]
workflow = pe.Workflow(name=name)
workflow.connect([
# connect inputnode to each non-anatomical confound node
(inputnode, dvars, [('fmri_file', 'in_file'),
('bold_mask', 'in_mask')]),
(inputnode, fdisp, [('movpar_file', 'in_file')]),
(inputnode, non_steady_state, [('fmri_file', 'in_file')]),
(inputnode, tcompcor, [('fmri_file', 'realigned_file')]),
(non_steady_state, tcompcor, [('n_volumes_to_discard',
'ignore_initial_volumes')]),
(non_steady_state, acompcor, [('n_volumes_to_discard',
'ignore_initial_volumes')]),
(inputnode, csf_roi, [(('t1_tpms', _pick_csf), 't1_tpm'),
('t1_mask', 't1_mask'),
('bold_mask', 'bold_mask')]),
(csf_roi, tcompcor, [('eroded_mask', 'mask_files')]),
(inputnode, wm_roi, [(('t1_tpms', _pick_wm), 't1_tpm'),
('t1_mask', 't1_mask'),
('bold_mask', 'bold_mask')]),
(csf_roi, merge_rois, [('roi_file', 'in1')]),
(wm_roi, merge_rois, [('roi_file', 'in2')]),
(merge_rois, combine_rois, [('out', 'in_files')]),
(inputnode, combine_rois, [('fmri_file', 'ref_header')]),
# anatomical confound: aCompCor.
(inputnode, acompcor, [('fmri_file', 'realigned_file')]),
(combine_rois, acompcor, [('out_file', 'mask_files')]),
(wm_roi, concat_rois, [('roi_file', 'in_file')]),
(inputnode, concat_rois, [('bold_mask', 'in_mask')]),
(inputnode, concat_rois, [('fmri_file', 'ref_header')]),
# anatomical confound: signal extraction
(concat_rois, signals, [('out_file', 'label_files')]),
(inputnode, signals, [('fmri_file', 'in_file')]),
# connect the confound nodes to the concatenate node
(inputnode, add_header, [('movpar_file', 'in_file')]),
(signals, concat, [('out_file', 'signals')]),
(dvars, concat, [('out_all', 'dvars')]),
(fdisp, concat, [('out_file', 'fd')]),
(tcompcor, concat, [('components_file', 'tcompcor'),
('pre_filter_file', 'cos_basis')]),
(acompcor, concat, [('components_file', 'acompcor')]),
(add_header, concat, [('out_file', 'motion')]),
(concat, outputnode, [('confounds_file', 'confounds_file'),
('confounds_list', 'confounds_list')]),
(acompcor, outputnode, [('out_report', 'acompcor_report')]),
(tcompcor, outputnode, [('out_report', 'tcompcor_report')]),
])
if use_aroma:
workflow.connect([
(inputnode, ica_aroma_wf,
[('bold_mni', 'inputnode.bold_mni'),
('bold_mask_mni', 'inputnode.bold_mask_mni'),
('movpar_file', 'inputnode.movpar_file')]),
(ica_aroma_wf, concat, [('outputnode.aroma_confounds', 'aroma')]),
(ica_aroma_wf, outputnode,
[('outputnode.out_report', 'ica_aroma_report'),
('outputnode.aroma_noise_ics', 'aroma_noise_ics'),
('outputnode.melodic_mix', 'melodic_mix'),
('outputnode.nonaggr_denoised_file', 'nonaggr_denoised_file')])
])
return workflow
def init_carpetplot_wf(mem_gb, metadata, name="bold_carpet_wf"):
"""
Resamples the MNI parcellation (ad-hoc parcellation derived from the
Harvard-Oxford template and others).
**Parameters**
mem_gb : float
Size of BOLD file in GB - please note that this size
should be calculated after resamplings that may extend
the FoV
metadata : dict
BIDS metadata for BOLD file
name : str
Name of workflow (default: ``bold_carpet_wf``)
**Inputs**
bold
BOLD image, after the prescribed corrections (STC, HMC and SDC)
when available.
bold_mask
BOLD series mask
confounds_file
TSV of all aggregated confounds
t1_bold_xform
Affine matrix that maps the T1w space into alignment with
the native BOLD space
t1_2_mni_reverse_transform
ANTs-compatible affine-and-warp transform file
**Outputs**
out_carpetplot
Path of the generated SVG file
"""
inputnode = pe.Node(niu.IdentityInterface(
fields=['bold', 'bold_mask', 'confounds_file',
't1_bold_xform', 't1_2_mni_reverse_transform']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(
fields=['out_carpetplot']), name='outputnode')
# List transforms
mrg_xfms = pe.Node(niu.Merge(2), name='mrg_xfms')
# Warp segmentation into EPI space
resample_parc = pe.Node(ApplyTransforms(
float=True,
input_image=os.path.join(
get_mni_icbm152_nlin_asym_09c(), '1mm_parc.nii.gz'),
dimension=3, default_value=0, interpolation='MultiLabel'),
name='resample_parc')
# Carpetplot and confounds plot
conf_plot = pe.Node(FMRISummary(
tr=metadata['RepetitionTime'],
confounds_list=[
('GlobalSignal', None, 'GS'),
('CSF', None, 'GSCSF'),
('WhiteMatter', None, 'GSWM'),
('stdDVARS', None, 'DVARS'),
('FramewiseDisplacement', 'mm', 'FD')]),
name='conf_plot', mem_gb=mem_gb)
ds_report_bold_conf = pe.Node(
DerivativesDataSink(suffix='carpetplot'),
name='ds_report_bold_conf', run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow = pe.Workflow(name=name)
workflow.connect([
(inputnode, mrg_xfms, [('t1_bold_xform', 'in1'),
('t1_2_mni_reverse_transform', 'in2')]),
(inputnode, resample_parc, [('bold_mask', 'reference_image')]),
(mrg_xfms, resample_parc, [('out', 'transforms')]),
# Carpetplot
(inputnode, conf_plot, [
('bold', 'in_func'),
('bold_mask', 'in_mask'),
('confounds_file', 'confounds_file')]),
(resample_parc, conf_plot, [('output_image', 'in_segm')]),
(conf_plot, ds_report_bold_conf, [('out_file', 'in_file')]),
(conf_plot, outputnode, [('out_file', 'out_carpetplot')]),
])
return workflow
