def init_anat_derivatives_wf(
*,
bids_root,
freesurfer,
num_t1w,
output_dir,
spaces,
name="anat_derivatives_wf",
tpm_labels=BIDS_TISSUE_ORDER,
):
"""
Set up a battery of datasinks to store derivatives in the right location.
Parameters
----------
bids_root : :obj:`str`
Root path of BIDS dataset
freesurfer : :obj:`bool`
FreeSurfer was enabled
num_t1w : :obj:`int`
Number of T1w images
output_dir : :obj:`str`
Directory in which to save derivatives
name : :obj:`str`
Workflow name (default: anat_derivatives_wf)
tpm_labels : :obj:`tuple`
Tissue probability maps in order
Inputs
------
template
Template space and specifications
source_files
List of input T1w images
t1w_ref_xfms
List of affine transforms to realign input T1w images
t1w_preproc
The T1w reference map, which is calculated as the average of bias-corrected
and preprocessed T1w images, defining the anatomical space.
t1w_mask
Mask of the ``t1w_preproc``
t1w_dseg
Segmentation in T1w space
t1w_tpms
Tissue probability maps in T1w space
anat2std_xfm
Nonlinear spatial transform to resample imaging data given in anatomical space
into standard space.
std2anat_xfm
Inverse transform of ``anat2std_xfm``
std_t1w
T1w reference resampled in one or more standard spaces.
std_mask
Mask of skull-stripped template, in standard space
std_dseg
Segmentation, resampled into standard space
std_tpms
Tissue probability maps in standard space
t1w2fsnative_xfm
LTA-style affine matrix translating from T1w to
FreeSurfer-conformed subject space
fsnative2t1w_xfm
LTA-style affine matrix translating from FreeSurfer-conformed
subject space to T1w
surfaces
GIFTI surfaces (gray/white boundary, midthickness, pial, inflated)
t1w_fs_aseg
FreeSurfer's aseg segmentation, in native T1w space
t1w_fs_aparc
FreeSurfer's aparc+aseg segmentation, in native T1w space
"""
from niworkflows.interfaces.utility import KeySelect
workflow = Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface(fields=[
"template",
"source_files",
"t1w_ref_xfms",
"t1w_preproc",
"t1w_mask",
"t1w_dseg",
"t1w_tpms",
"anat2std_xfm",
"std2anat_xfm",
"t1w2fsnative_xfm",
"fsnative2t1w_xfm",
"surfaces",
"t1w_fs_aseg",
"t1w_fs_aparc",
]),
name="inputnode",
)
raw_sources = pe.Node(niu.Function(function=_bids_relative),
name="raw_sources")
raw_sources.inputs.bids_root = bids_root
ds_t1w_preproc = pe.Node(
DerivativesDataSink(base_directory=output_dir,
desc="preproc",
compress=True),
name="ds_t1w_preproc",
run_without_submitting=True,
)
ds_t1w_preproc.inputs.SkullStripped = False
ds_t1w_mask = pe.Node(
DerivativesDataSink(base_directory=output_dir,
desc="brain",
suffix="mask",
compress=True),
name="ds_t1w_mask",
run_without_submitting=True,
)
ds_t1w_mask.inputs.Type = "Brain"
ds_t1w_dseg = pe.Node(
DerivativesDataSink(base_directory=output_dir,
suffix="dseg",
compress=True),
name="ds_t1w_dseg",
run_without_submitting=True,
)
ds_t1w_tpms = pe.Node(
DerivativesDataSink(base_directory=output_dir,
suffix="probseg",
compress=True),
name="ds_t1w_tpms",
run_without_submitting=True,
)
ds_t1w_tpms.inputs.label = tpm_labels
# fmt:off
workflow.connect([
(inputnode, raw_sources, [('source_files', 'in_files')]),
(inputnode, ds_t1w_preproc, [('t1w_preproc', 'in_file'),
('source_files', 'source_file')]),
(inputnode, ds_t1w_mask, [('t1w_mask', 'in_file'),
('source_files', 'source_file')]),
(inputnode, ds_t1w_tpms, [('t1w_tpms', 'in_file'),
('source_files', 'source_file')]),
(inputnode, ds_t1w_dseg, [('t1w_dseg', 'in_file'),
('source_files', 'source_file')]),
(raw_sources, ds_t1w_mask, [('out', 'RawSources')]),
])
# fmt:on
# Transforms
if spaces.get_spaces(nonstandard=False, dim=(3, )):
ds_std2t1w_xfm = pe.MapNode(
DerivativesDataSink(base_directory=output_dir,
to="T1w",
mode="image",
suffix="xfm"),
iterfield=("in_file", "from"),
name="ds_std2t1w_xfm",
run_without_submitting=True,
)
ds_t1w2std_xfm = pe.MapNode(
DerivativesDataSink(base_directory=output_dir,
mode="image",
suffix="xfm",
**{"from": "T1w"}),
iterfield=("in_file", "to"),
name="ds_t1w2std_xfm",
run_without_submitting=True,
)
# fmt:off
workflow.connect([
(inputnode, ds_t1w2std_xfm, [('anat2std_xfm', 'in_file'),
(('template', _combine_cohort), 'to'),
('source_files', 'source_file')]),
(inputnode, ds_std2t1w_xfm, [('std2anat_xfm', 'in_file'),
(('template', _combine_cohort),
'from'),
('source_files', 'source_file')]),
])
# fmt:on
if num_t1w > 1:
# Please note the dictionary unpacking to provide the from argument.
# It is necessary because from is a protected keyword (not allowed as argument name).
ds_t1w_ref_xfms = pe.MapNode(
DerivativesDataSink(
base_directory=output_dir,
to="T1w",
mode="image",
suffix="xfm",
extension="txt",
**{"from": "orig"},
),
iterfield=["source_file", "in_file"],
name="ds_t1w_ref_xfms",
run_without_submitting=True,
)
# fmt:off
workflow.connect([
(inputnode, ds_t1w_ref_xfms, [('source_files', 'source_file'),
('t1w_ref_xfms', 'in_file')]),
])
# fmt:on
# Write derivatives in standard spaces specified by --output-spaces
if getattr(spaces, "_cached") is not None and spaces.cached.references:
from niworkflows.interfaces.space import SpaceDataSource
from niworkflows.interfaces.nibabel import GenerateSamplingReference
from niworkflows.interfaces.fixes import (
FixHeaderApplyTransforms as ApplyTransforms, )
from ..interfaces.templateflow import TemplateFlowSelect
spacesource = pe.Node(SpaceDataSource(),
name="spacesource",
run_without_submitting=True)
spacesource.iterables = (
"in_tuple",
[(s.fullname, s.spec)
for s in spaces.cached.get_standard(dim=(3, ))],
)
gen_tplid = pe.Node(
niu.Function(function=_fmt_cohort),
name="gen_tplid",
run_without_submitting=True,
)
select_xfm = pe.Node(
KeySelect(fields=["anat2std_xfm"]),
name="select_xfm",
run_without_submitting=True,
)
select_tpl = pe.Node(TemplateFlowSelect(),
name="select_tpl",
run_without_submitting=True)
gen_ref = pe.Node(GenerateSamplingReference(),
name="gen_ref",
mem_gb=0.01)
# Mask T1w preproc images
mask_t1w = pe.Node(ApplyMask(), name='mask_t1w')
# Resample T1w-space inputs
anat2std_t1w = pe.Node(
ApplyTransforms(
dimension=3,
default_value=0,
float=True,
interpolation="LanczosWindowedSinc",
),
name="anat2std_t1w",
)
anat2std_mask = pe.Node(ApplyTransforms(interpolation="MultiLabel"),
name="anat2std_mask")
anat2std_dseg = pe.Node(ApplyTransforms(interpolation="MultiLabel"),
name="anat2std_dseg")
anat2std_tpms = pe.MapNode(
ApplyTransforms(dimension=3,
default_value=0,
float=True,
interpolation="Gaussian"),
iterfield=["input_image"],
name="anat2std_tpms",
)
ds_std_t1w = pe.Node(
DerivativesDataSink(
base_directory=output_dir,
desc="preproc",
compress=True,
),
name="ds_std_t1w",
run_without_submitting=True,
)
ds_std_t1w.inputs.SkullStripped = True
ds_std_mask = pe.Node(
DerivativesDataSink(base_directory=output_dir,
desc="brain",
suffix="mask",
compress=True),
name="ds_std_mask",
run_without_submitting=True,
)
ds_std_mask.inputs.Type = "Brain"
ds_std_dseg = pe.Node(
DerivativesDataSink(base_directory=output_dir,
suffix="dseg",
compress=True),
name="ds_std_dseg",
run_without_submitting=True,
)
ds_std_tpms = pe.Node(
DerivativesDataSink(base_directory=output_dir,
suffix="probseg",
compress=True),
name="ds_std_tpms",
run_without_submitting=True,
)
# CRITICAL: the sequence of labels here (CSF-GM-WM) is that of the output of FSL-FAST
# (intensity mean, per tissue). This order HAS to be matched also by the ``tpms``
# output in the data/io_spec.json file.
ds_std_tpms.inputs.label = tpm_labels
# fmt:off
workflow.connect([
(inputnode, mask_t1w, [('t1w_preproc', 'in_file'),
('t1w_mask', 'in_mask')]),
(mask_t1w, anat2std_t1w, [('out_file', 'input_image')]),
(inputnode, anat2std_mask, [('t1w_mask', 'input_image')]),
(inputnode, anat2std_dseg, [('t1w_dseg', 'input_image')]),
(inputnode, anat2std_tpms, [('t1w_tpms', 'input_image')]),
(inputnode, gen_ref, [('t1w_preproc', 'moving_image')]),
(inputnode, select_xfm, [('anat2std_xfm', 'anat2std_xfm'),
('template', 'keys')]),
(spacesource, gen_tplid, [('space', 'template'),
('cohort', 'cohort')]),
(gen_tplid, select_xfm, [('out', 'key')]),
(spacesource, select_tpl, [('space', 'template'),
('cohort', 'cohort'),
(('resolution', _no_native),
'resolution')]),
(spacesource, gen_ref, [(('resolution', _is_native), 'keep_native')
]),
(select_tpl, gen_ref, [('t1w_file', 'fixed_image')]),
(anat2std_t1w, ds_std_t1w, [('output_image', 'in_file')]),
(anat2std_mask, ds_std_mask, [('output_image', 'in_file')]),
(anat2std_dseg, ds_std_dseg, [('output_image', 'in_file')]),
(anat2std_tpms, ds_std_tpms, [('output_image', 'in_file')]),
(select_tpl, ds_std_mask, [(('brain_mask', _drop_path),
'RawSources')]),
])
workflow.connect(
# Connect apply transforms nodes
[(gen_ref, n, [('out_file', 'reference_image')])
for n in (anat2std_t1w, anat2std_mask, anat2std_dseg,
anat2std_tpms)] +
[(select_xfm, n, [('anat2std_xfm', 'transforms')])
for n in (anat2std_t1w, anat2std_mask, anat2std_dseg,
anat2std_tpms)]
# Connect the source_file input of these datasinks
+ [(inputnode, n, [('source_files', 'source_file')])
for n in (ds_std_t1w, ds_std_mask, ds_std_dseg, ds_std_tpms)]
# Connect the space input of these datasinks
+ [(spacesource, n, [('space', 'space'), ('cohort', 'cohort'),
('resolution', 'resolution')])
for n in (ds_std_t1w, ds_std_mask, ds_std_dseg, ds_std_tpms)])
# fmt:on
if not freesurfer:
return workflow
from niworkflows.interfaces.nitransforms import ConcatenateXFMs
from niworkflows.interfaces.surf import Path2BIDS
# FS native space transforms
lta2itk_fwd = pe.Node(ConcatenateXFMs(),
name="lta2itk_fwd",
run_without_submitting=True)
lta2itk_inv = pe.Node(ConcatenateXFMs(),
name="lta2itk_inv",
run_without_submitting=True)
ds_t1w_fsnative = pe.Node(
DerivativesDataSink(
base_directory=output_dir,
mode="image",
to="fsnative",
suffix="xfm",
extension="txt",
**{"from": "T1w"},
),
name="ds_t1w_fsnative",
run_without_submitting=True,
)
ds_fsnative_t1w = pe.Node(
DerivativesDataSink(
base_directory=output_dir,
mode="image",
to="T1w",
suffix="xfm",
extension="txt",
**{"from": "fsnative"},
),
name="ds_fsnative_t1w",
run_without_submitting=True,
)
# Surfaces
name_surfs = pe.MapNode(Path2BIDS(),
iterfield="in_file",
name="name_surfs",
run_without_submitting=True)
ds_surfs = pe.MapNode(
DerivativesDataSink(base_directory=output_dir, extension=".surf.gii"),
iterfield=["in_file", "hemi", "suffix"],
name="ds_surfs",
run_without_submitting=True,
)
# Parcellations
ds_t1w_fsaseg = pe.Node(
DerivativesDataSink(base_directory=output_dir,
desc="aseg",
suffix="dseg",
compress=True),
name="ds_t1w_fsaseg",
run_without_submitting=True,
)
ds_t1w_fsparc = pe.Node(
DerivativesDataSink(base_directory=output_dir,
desc="aparcaseg",
suffix="dseg",
compress=True),
name="ds_t1w_fsparc",
run_without_submitting=True,
)
# fmt:off
workflow.connect([
(inputnode, lta2itk_fwd, [('t1w2fsnative_xfm', 'in_xfms')]),
(inputnode, lta2itk_inv, [('fsnative2t1w_xfm', 'in_xfms')]),
(inputnode, ds_t1w_fsnative, [('source_files', 'source_file')]),
(lta2itk_fwd, ds_t1w_fsnative, [('out_xfm', 'in_file')]),
(inputnode, ds_fsnative_t1w, [('source_files', 'source_file')]),
(lta2itk_inv, ds_fsnative_t1w, [('out_xfm', 'in_file')]),
(inputnode, name_surfs, [('surfaces', 'in_file')]),
(inputnode, ds_surfs, [('surfaces', 'in_file'),
('source_files', 'source_file')]),
(name_surfs, ds_surfs, [('hemi', 'hemi'), ('suffix', 'suffix')]),
(inputnode, ds_t1w_fsaseg, [('t1w_fs_aseg', 'in_file'),
('source_files', 'source_file')]),
(inputnode, ds_t1w_fsparc, [('t1w_fs_aparc', 'in_file'),
('source_files', 'source_file')]),
])
# fmt:on
return workflow
def init_bold_t1_trans_wf(freesurfer,
mem_gb,
omp_nthreads,
use_compression=True,
name='bold_t1_trans_wf'):
"""
Co-register the reference BOLD image to T1w-space.
The workflow uses :abbr:`BBR (boundary-based registration)`.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold.registration import init_bold_t1_trans_wf
wf = init_bold_t1_trans_wf(freesurfer=True,
mem_gb=3,
omp_nthreads=1)
Parameters
----------
freesurfer : :obj:`bool`
Enable FreeSurfer functional registration (bbregister)
mem_gb : :obj:`float`
Size of BOLD file in GB
omp_nthreads : :obj:`int`
Maximum number of threads an individual process may use
use_compression : :obj:`bool`
Save registered BOLD series as ``.nii.gz``
name : :obj:`str`
Name of workflow (default: ``bold_reg_wf``)
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
t1w_brain
Skull-stripped bias-corrected structural template image
t1w_mask
Mask of the skull-stripped template image
t1w_aseg
FreeSurfer's ``aseg.mgz`` atlas projected into the T1w reference
(only if ``recon-all`` was run).
t1w_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
itk_bold_to_t1
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
Outputs
-------
bold_t1
Motion-corrected BOLD series in T1 space
bold_t1_ref
Reference, contrast-enhanced summary of the motion-corrected BOLD series in T1w 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).
See also
--------
* :py:func:`~fmriprep.workflows.bold.registration.init_bbreg_wf`
* :py:func:`~fmriprep.workflows.bold.registration.init_fsl_bbr_wf`
"""
from niworkflows.engine.workflows import LiterateWorkflow as Workflow
from niworkflows.func.util import init_bold_reference_wf
from niworkflows.interfaces.fixes import FixHeaderApplyTransforms as ApplyTransforms
from niworkflows.interfaces.itk import MultiApplyTransforms
from niworkflows.interfaces.nibabel import GenerateSamplingReference
from niworkflows.interfaces.nilearn import Merge
workflow = Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=[
'name_source', 'ref_bold_brain', 'ref_bold_mask', 't1w_brain',
't1w_mask', 't1w_aseg', 't1w_aparc', 'bold_split', 'fieldwarp',
'hmc_xforms', 'itk_bold_to_t1'
]),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=[
'bold_t1', 'bold_t1_ref', 'bold_mask_t1', 'bold_aseg_t1',
'bold_aparc_t1'
]),
name='outputnode')
gen_ref = pe.Node(GenerateSamplingReference(), name='gen_ref',
mem_gb=0.3) # 256x256x256 * 64 / 8 ~ 150MB
mask_t1w_tfm = pe.Node(ApplyTransforms(interpolation='MultiLabel'),
name='mask_t1w_tfm',
mem_gb=0.1)
workflow.connect([
(inputnode, gen_ref, [('ref_bold_brain', 'moving_image'),
('t1w_brain', 'fixed_image'),
('t1w_mask', 'fov_mask')]),
(inputnode, mask_t1w_tfm, [('ref_bold_mask', 'input_image')]),
(gen_ref, mask_t1w_tfm, [('out_file', 'reference_image')]),
(inputnode, mask_t1w_tfm, [('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'),
name='aseg_t1w_tfm',
mem_gb=0.1)
aparc_t1w_tfm = pe.Node(ApplyTransforms(interpolation='MultiLabel',
transforms='identity'),
name='aparc_t1w_tfm',
mem_gb=0.1)
workflow.connect([
(inputnode, aseg_t1w_tfm, [('t1w_aseg', 'input_image')]),
(inputnode, aparc_t1w_tfm, [('t1w_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')]),
])
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 3D volumes into 4D timeseries
merge = pe.Node(Merge(compress=use_compression),
name='merge',
mem_gb=mem_gb)
# Generate a reference on the target T1w space
gen_final_ref = init_bold_reference_wf(omp_nthreads, pre_mask=True)
# Merge transforms placing the head motion correction last
merge_xforms = pe.Node(niu.Merge(3),
name='merge_xforms',
run_without_submitting=True,
mem_gb=DEFAULT_MEMORY_MIN_GB)
workflow.connect([
(inputnode, merge, [('name_source', 'header_source')]),
(
inputnode,
merge_xforms,
[
('hmc_xforms',
'in3'), # May be 'identity' if HMC already applied
('fieldwarp',
'in2'), # May be 'identity' if SDC already applied
('itk_bold_to_t1', 'in1')
]),
(inputnode, bold_to_t1w_transform, [('bold_split', 'input_image')]),
(merge_xforms, bold_to_t1w_transform, [('out', 'transforms')]),
(gen_ref, bold_to_t1w_transform, [('out_file', 'reference_image')]),
(bold_to_t1w_transform, merge, [('out_files', 'in_files')]),
(merge, gen_final_ref, [('out_file', 'inputnode.bold_file')]),
(mask_t1w_tfm, gen_final_ref, [('output_image', 'inputnode.bold_mask')
]),
(merge, outputnode, [('out_file', 'bold_t1')]),
(gen_final_ref, outputnode, [('outputnode.ref_image', 'bold_t1_ref')]),
])
return workflow
def init_syn_preprocessing_wf(
*,
debug=False,
name="syn_preprocessing_wf",
omp_nthreads=1,
auto_bold_nss=False,
t1w_inversion=False,
):
"""
Prepare EPI references and co-registration to anatomical for SyN.
Workflow Graph
.. workflow ::
:graph2use: orig
:simple_form: yes
from sdcflows.workflows.fit.syn import init_syn_sdc_wf
wf = init_syn_sdc_wf(omp_nthreads=8)
Parameters
----------
debug : :obj:`bool`
Whether a fast (less accurate) configuration of the workflow should be applied.
name : :obj:`str`
Name for this workflow
omp_nthreads : :obj:`int`
Parallelize internal tasks across the number of CPUs given by this option.
auto_bold_nss : :obj:`bool`
Set up the reference workflow to automatically execute nonsteady states detection
of BOLD images.
t1w_inversion : :obj:`bool`
Run T1w intensity inversion so that it looks more like a T2 contrast.
Inputs
------
in_epis : :obj:`list` of :obj:`str`
Distorted EPI images that will be merged together to create the
EPI reference file.
t_masks : :obj:`list` of :obj:`bool`
(optional) mask of timepoints for calculating an EPI reference.
Not used if ``auto_bold_nss=True``.
in_meta : :obj:`list` of :obj:`dict`
Metadata dictionaries corresponding to the ``in_epis`` input.
in_anat : :obj:`str`
A preprocessed anatomical (T1w or T2w) image.
mask_anat : :obj:`str`
A brainmask corresponding to the anatomical (T1w or T2w) image.
std2anat_xfm : :obj:`str`
inverse registration transform of T1w image to MNI template.
Outputs
-------
epi_ref : :obj:`tuple` (:obj:`str`, :obj:`dict`)
A tuple, where the first element is the path of the distorted EPI
reference map (e.g., an average of *b=0* volumes), and the second
element is a dictionary of associated metadata.
anat_ref : :obj:`str`
Path to the anatomical, skull-stripped reference in EPI space.
anat_mask : :obj:`str`
Path to the brain mask corresponding to ``anat_ref`` in EPI space.
sd_prior : :obj:`str`
A template map of areas with strong susceptibility distortions (SD) to regularize
the cost function of SyN.
"""
from pkg_resources import resource_filename as pkgrf
from niworkflows.interfaces.nibabel import (
IntensityClip,
ApplyMask,
GenerateSamplingReference,
)
from niworkflows.interfaces.fixes import (
FixHeaderApplyTransforms as ApplyTransforms,
FixHeaderRegistration as Registration,
)
from niworkflows.workflows.epi.refmap import init_epi_reference_wf
from ...interfaces.utils import Deoblique, DenoiseImage
from ...interfaces.brainmask import BrainExtraction, BinaryDilation
workflow = Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface(
fields=[
"in_epis",
"t_masks",
"in_meta",
"in_anat",
"mask_anat",
"std2anat_xfm",
]
),
name="inputnode",
)
outputnode = pe.Node(
niu.IdentityInterface(
fields=["epi_ref", "epi_mask", "anat_ref", "anat_mask", "sd_prior"]
),
name="outputnode",
)
deob_epi = pe.Node(Deoblique(), name="deob_epi")
# Mapping & preparing prior knowledge
# Concatenate transform files:
# 1) MNI -> anat; 2) ATLAS -> MNI
transform_list = pe.Node(
niu.Merge(3),
name="transform_list",
mem_gb=DEFAULT_MEMORY_MIN_GB,
run_without_submitting=True,
)
transform_list.inputs.in3 = pkgrf(
"sdcflows", "data/fmap_atlas_2_MNI152NLin2009cAsym_affine.mat"
)
prior2epi = pe.Node(
ApplyTransforms(
invert_transform_flags=[True, False, False],
input_image=pkgrf("sdcflows", "data/fmap_atlas.nii.gz"),
),
name="prior2epi",
n_procs=omp_nthreads,
mem_gb=0.3,
)
anat2epi = pe.Node(
ApplyTransforms(invert_transform_flags=[True]),
name="anat2epi",
n_procs=omp_nthreads,
mem_gb=0.3,
)
mask2epi = pe.Node(
ApplyTransforms(invert_transform_flags=[True], interpolation="MultiLabel"),
name="mask2epi",
n_procs=omp_nthreads,
mem_gb=0.3,
)
mask_dtype = pe.Node(
niu.Function(function=_set_dtype, input_names=["in_file", "dtype"]),
name="mask_dtype",
)
mask_dtype.inputs.dtype = "uint8"
epi_reference_wf = init_epi_reference_wf(
omp_nthreads=omp_nthreads,
auto_bold_nss=auto_bold_nss,
)
epi_brain = pe.Node(BrainExtraction(), name="epi_brain")
merge_output = pe.Node(
niu.Function(function=_merge_meta),
name="merge_output",
run_without_submitting=True,
)
mask_anat = pe.Node(ApplyMask(), name="mask_anat")
clip_anat = pe.Node(IntensityClip(p_min=0.0, p_max=99.8), name="clip_anat")
ref_anat = pe.Node(
DenoiseImage(copy_header=True), name="ref_anat", n_procs=omp_nthreads
)
epi2anat = pe.Node(
Registration(from_file=resource_filename("sdcflows", "data/affine.json")),
name="epi2anat",
n_procs=omp_nthreads,
)
epi2anat.inputs.output_warped_image = debug
epi2anat.inputs.output_inverse_warped_image = debug
if debug:
epi2anat.inputs.args = "--write-interval-volumes 5"
def _remove_first_mask(in_file):
if not isinstance(in_file, list):
in_file = [in_file]
in_file.insert(0, "NULL")
return in_file
anat_dilmsk = pe.Node(BinaryDilation(), name="anat_dilmsk")
epi_dilmsk = pe.Node(BinaryDilation(), name="epi_dilmsk")
sampling_ref = pe.Node(GenerateSamplingReference(), name="sampling_ref")
# fmt:off
workflow.connect([
(inputnode, transform_list, [("std2anat_xfm", "in2")]),
(inputnode, epi_reference_wf, [("in_epis", "inputnode.in_files")]),
(inputnode, merge_output, [("in_meta", "meta_list")]),
(inputnode, anat_dilmsk, [("mask_anat", "in_file")]),
(inputnode, mask_anat, [("in_anat", "in_file"),
("mask_anat", "in_mask")]),
(inputnode, mask2epi, [("mask_anat", "input_image")]),
(epi_reference_wf, deob_epi, [("outputnode.epi_ref_file", "in_file")]),
(deob_epi, merge_output, [("out_file", "epi_ref")]),
(mask_anat, clip_anat, [("out_file", "in_file")]),
(clip_anat, ref_anat, [("out_file", "input_image")]),
(deob_epi, epi_brain, [("out_file", "in_file")]),
(epi_brain, epi_dilmsk, [("out_mask", "in_file")]),
(ref_anat, epi2anat, [("output_image", "fixed_image")]),
(anat_dilmsk, epi2anat, [("out_file", "fixed_image_masks")]),
(deob_epi, epi2anat, [("out_file", "moving_image")]),
(epi_dilmsk, epi2anat, [
(("out_file", _remove_first_mask), "moving_image_masks")]),
(deob_epi, sampling_ref, [("out_file", "fixed_image")]),
(epi2anat, transform_list, [("forward_transforms", "in1")]),
(transform_list, prior2epi, [("out", "transforms")]),
(sampling_ref, prior2epi, [("out_file", "reference_image")]),
(ref_anat, anat2epi, [("output_image", "input_image")]),
(epi2anat, anat2epi, [("forward_transforms", "transforms")]),
(sampling_ref, anat2epi, [("out_file", "reference_image")]),
(epi2anat, mask2epi, [("forward_transforms", "transforms")]),
(sampling_ref, mask2epi, [("out_file", "reference_image")]),
(mask2epi, mask_dtype, [("output_image", "in_file")]),
(anat2epi, outputnode, [("output_image", "anat_ref")]),
(mask_dtype, outputnode, [("out", "anat_mask")]),
(merge_output, outputnode, [("out", "epi_ref")]),
(epi_brain, outputnode, [("out_mask", "epi_mask")]),
(prior2epi, outputnode, [("output_image", "sd_prior")]),
])
# fmt:on
if debug:
from niworkflows.interfaces.nibabel import RegridToZooms
regrid_anat = pe.Node(
RegridToZooms(zooms=(2.0, 2.0, 2.0), smooth=True), name="regrid_anat"
)
# fmt:off
workflow.connect([
(inputnode, regrid_anat, [("in_anat", "in_file")]),
(regrid_anat, sampling_ref, [("out_file", "moving_image")]),
])
# fmt:on
else:
# fmt:off
workflow.connect([
(inputnode, sampling_ref, [("in_anat", "moving_image")]),
])
# fmt:on
if not auto_bold_nss:
workflow.connect(inputnode, "t_masks", epi_reference_wf, "inputnode.t_masks")
return workflow
def init_bold_std_trans_wf(
mem_gb,
omp_nthreads,
spaces,
name="bold_std_trans_wf",
use_compression=True,
use_fieldwarp=False,
):
"""
Sample fMRI into standard space with a single-step resampling of the original BOLD series.
.. important::
This workflow provides two outputnodes.
One output node (with name ``poutputnode``) will be parameterized in a Nipype sense
(see `Nipype iterables
<https://miykael.github.io/nipype_tutorial/notebooks/basic_iteration.html>`__), and a
second node (``outputnode``) will collapse the parameterized outputs into synchronous
lists of the output fields listed below.
Workflow Graph
.. workflow::
:graph2use: colored
:simple_form: yes
from niworkflows.utils.spaces import SpatialReferences
from fprodents.workflows.bold.resampling import init_bold_std_trans_wf
wf = init_bold_std_trans_wf(
mem_gb=3,
omp_nthreads=1,
spaces=SpatialReferences(
spaces=['MNI152Lin',
('MNIPediatricAsym', {'cohort': '6'})],
checkpoint=True),
)
Parameters
----------
mem_gb : :obj:`float`
Size of BOLD file in GB
omp_nthreads : :obj:`int`
Maximum number of threads an individual process may use
spaces : :py:class:`~niworkflows.utils.spaces.SpatialReferences`
A container for storing, organizing, and parsing spatial normalizations. Composed of
:py:class:`~niworkflows.utils.spaces.Reference` objects representing spatial references.
Each ``Reference`` contains a space, which is a string of either TemplateFlow template IDs
(e.g., ``MNI152Lin``, ``MNI152NLin6Asym``, ``MNIPediatricAsym``), nonstandard references
(e.g., ``T1w`` or ``anat``, ``sbref``, ``run``, etc.), or a custom template located in
the TemplateFlow root directory. Each ``Reference`` may also contain a spec, which is a
dictionary with template specifications (e.g., a specification of ``{'resolution': 2}``
would lead to resampling on a 2mm resolution of the space).
name : :obj:`str`
Name of workflow (default: ``bold_std_trans_wf``)
use_compression : :obj:`bool`
Save registered BOLD series as ``.nii.gz``
use_fieldwarp : :obj:`bool`
Include SDC warp in single-shot transform from BOLD to MNI
Inputs
------
anat2std_xfm
List of anatomical-to-standard space transforms generated during
spatial normalization.
bold_mask
Skull-stripping mask of reference image
bold_split
Individual 3D volumes, not motion corrected
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
hmc_xforms
List of affine transforms aligning each volume to ``ref_image`` in ITK format
bold2anat
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
name_source
BOLD series NIfTI file
Used to recover original information lost during processing
templates
List of templates that were applied as targets during
spatial normalization.
Outputs
-------
bold_std
BOLD series, resampled to template space
bold_std_ref
Reference, contrast-enhanced summary of the BOLD series, resampled to template space
bold_mask_std
BOLD series mask in template space
template
Template identifiers synchronized correspondingly to previously
described outputs.
"""
from niworkflows.engine.workflows import LiterateWorkflow as Workflow
from niworkflows.interfaces.fixes import FixHeaderApplyTransforms as ApplyTransforms
from niworkflows.interfaces.itk import MultiApplyTransforms
from niworkflows.interfaces.utility import KeySelect
from niworkflows.interfaces.nibabel import GenerateSamplingReference
from niworkflows.interfaces.nilearn import Merge
from niworkflows.utils.spaces import format_reference
workflow = Workflow(name=name)
output_references = spaces.cached.get_spaces(nonstandard=False, dim=(3, ))
std_vol_references = [(s.fullname, s.spec) for s in spaces.references
if s.standard and s.dim == 3]
if len(output_references) == 1:
workflow.__desc__ = """\
The BOLD time-series were resampled into standard space,
generating a *preprocessed BOLD run in {tpl} space*.
""".format(tpl=output_references[0])
elif len(output_references) > 1:
workflow.__desc__ = """\
The BOLD time-series were resampled into several standard spaces,
correspondingly generating the following *spatially-normalized,
preprocessed BOLD runs*: {tpl}.
""".format(tpl=", ".join(output_references))
inputnode = pe.Node(
niu.IdentityInterface(fields=[
"anat2std_xfm",
"bold_mask",
"bold_split",
"fieldwarp",
"hmc_xforms",
"bold2anat",
"name_source",
"templates",
]),
name="inputnode",
)
iterablesource = pe.Node(niu.IdentityInterface(fields=["std_target"]),
name="iterablesource")
# Generate conversions for every template+spec at the input
iterablesource.iterables = [("std_target", std_vol_references)]
split_target = pe.Node(
niu.Function(
function=_split_spec,
input_names=["in_target"],
output_names=["space", "template", "spec"],
),
run_without_submitting=True,
name="split_target",
)
select_std = pe.Node(
KeySelect(fields=["anat2std_xfm"]),
name="select_std",
run_without_submitting=True,
)
select_tpl = pe.Node(
niu.Function(function=_select_template),
name="select_tpl",
run_without_submitting=True,
)
gen_ref = pe.Node(GenerateSamplingReference(), name="gen_ref",
mem_gb=0.3) # 256x256x256 * 64 / 8 ~ 150MB)
mask_std_tfm = pe.Node(ApplyTransforms(interpolation="MultiLabel"),
name="mask_std_tfm",
mem_gb=1)
ref_std_tfm = pe.Node(ApplyTransforms(interpolation="LanczosWindowedSinc"),
name="ref_std_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 = 3 + use_fieldwarp
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")])])
bold_to_std_transform = pe.Node(
MultiApplyTransforms(interpolation="LanczosWindowedSinc",
float=True,
copy_dtype=True),
name="bold_to_std_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)
# fmt:off
workflow.connect([
(iterablesource, split_target, [('std_target', 'in_target')]),
(iterablesource, select_tpl, [('std_target', 'template')]),
(inputnode, select_std, [('anat2std_xfm', 'anat2std_xfm'),
('templates', 'keys')]),
(inputnode, mask_std_tfm, [('bold_mask', 'input_image')]),
(inputnode, ref_std_tfm, [('bold_mask', 'input_image')]),
(inputnode, gen_ref, [(('bold_split', _first), 'moving_image')]),
(inputnode, merge_xforms, [(('bold2anat', _aslist), 'in2')]),
(inputnode, merge, [('name_source', 'header_source')]),
(inputnode, mask_merge_tfms, [(('bold2anat', _aslist), 'in2')]),
(inputnode, bold_to_std_transform, [('bold_split', 'input_image')]),
(split_target, select_std, [('space', 'key')]),
(select_std, merge_xforms, [('anat2std_xfm', 'in1')]),
(select_std, mask_merge_tfms, [('anat2std_xfm', 'in1')]),
(split_target, gen_ref, [(('spec', _is_native), 'keep_native')]),
(select_tpl, gen_ref, [('out', 'fixed_image')]),
(merge_xforms, bold_to_std_transform, [('out', 'transforms')]),
(gen_ref, bold_to_std_transform, [('out_file', 'reference_image')]),
(gen_ref, mask_std_tfm, [('out_file', 'reference_image')]),
(mask_merge_tfms, mask_std_tfm, [('out', 'transforms')]),
(gen_ref, ref_std_tfm, [('out_file', 'reference_image')]),
(mask_merge_tfms, ref_std_tfm, [('out', 'transforms')]),
(bold_to_std_transform, merge, [('out_files', 'in_files')]),
])
# fmt:on
output_names = [
"bold_mask_std",
"bold_std",
"bold_std_ref",
"spatial_reference",
"template",
]
poutputnode = pe.Node(niu.IdentityInterface(fields=output_names),
name="poutputnode")
# fmt:off
workflow.connect([
# Connecting outputnode
(iterablesource, poutputnode, [(('std_target', format_reference),
'spatial_reference')]),
(merge, poutputnode, [('out_file', 'bold_std')]),
(ref_std_tfm, poutputnode, [('output_image', 'bold_std_ref')]),
(mask_std_tfm, poutputnode, [('output_image', 'bold_mask_std')]),
(select_std, poutputnode, [('key', 'template')]),
])
# fmt:on
# Connect parametric outputs to a Join outputnode
outputnode = pe.JoinNode(
niu.IdentityInterface(fields=output_names),
name="outputnode",
joinsource="iterablesource",
)
# fmt:off
workflow.connect([
(poutputnode, outputnode, [(f, f) for f in output_names]),
])
# fmt:on
return workflow
def init_bold_t1_trans_wf(
mem_gb,
omp_nthreads,
multiecho=False,
use_fieldwarp=False,
use_compression=True,
name="bold_t1_trans_wf",
):
"""
Co-register the reference BOLD image to T1w-space.
Workflow Graph
.. workflow::
:graph2use: orig
:simple_form: yes
from fprodents.workflows.bold.registration import init_bold_t1_trans_wf
wf = init_bold_t1_trans_wf(mem_gb=3,
omp_nthreads=1)
Parameters
----------
use_fieldwarp : :obj:`bool`
Include SDC warp in single-shot transform from BOLD to T1
multiecho : :obj:`bool`
If multiecho data was supplied, HMC already performed
mem_gb : :obj:`float`
Size of BOLD file in GB
omp_nthreads : :obj:`int`
Maximum number of threads an individual process may use
use_compression : :obj:`bool`
Save registered BOLD series as ``.nii.gz``
name : :obj:`str`
Name of workflow (default: ``bold_reg_wf``)
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
t1w_brain
Skull-stripped bias-corrected structural template image
t1w_mask
Mask of the skull-stripped template image
bold_split
Individual 3D BOLD volumes, not motion corrected
hmc_xforms
List of affine transforms aligning each volume to ``ref_image`` in ITK format
bold2anat
Affine transform from ``ref_bold_brain`` to T1 space (ITK format)
fieldwarp
a :abbr:`DFM (displacements field map)` in ITK format
Outputs
-------
bold_t1
Motion-corrected BOLD series in T1 space
bold_t1_ref
Reference, contrast-enhanced summary of the motion-corrected BOLD series in T1w space
"""
from niworkflows.engine.workflows import LiterateWorkflow as Workflow
from niworkflows.interfaces.fixes import FixHeaderApplyTransforms as ApplyTransforms
from niworkflows.interfaces.itk import MultiApplyTransforms
from niworkflows.interfaces.nibabel import GenerateSamplingReference
from niworkflows.interfaces.nilearn import Merge
workflow = Workflow(name=name)
inputnode = pe.Node(
niu.IdentityInterface(fields=[
"name_source",
"ref_bold_brain",
"t1w_brain",
"t1w_mask",
"bold_split",
"fieldwarp",
"hmc_xforms",
"bold2anat",
]),
name="inputnode",
)
outputnode = pe.Node(
niu.IdentityInterface(
fields=["bold_t1", "bold_t1_ref", "bold_mask_t1"]),
name="outputnode",
)
gen_ref = pe.Node(GenerateSamplingReference(), name="gen_ref",
mem_gb=0.3) # 256x256x256 * 64 / 8 ~ 150MB
bold_ref_t1w_tfm = pe.Node(
ApplyTransforms(interpolation="LanczosWindowedSinc"),
name="bold_ref_t1w_tfm",
mem_gb=0.1)
# fmt:off
workflow.connect([
(inputnode, gen_ref, [('ref_bold_brain', 'moving_image'),
('t1w_brain', 'fixed_image'),
('t1w_mask', 'fov_mask')]),
(inputnode, bold_ref_t1w_tfm, [('ref_bold_brain', 'input_image')]),
(gen_ref, bold_ref_t1w_tfm, [('out_file', 'reference_image')]),
(inputnode, bold_ref_t1w_tfm, [('bold2anat', 'transforms')]),
(bold_ref_t1w_tfm, outputnode, [('output_image', 'bold_t1_ref')]),
])
# fmt:on
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 3D volumes into 4D timeseries
merge = pe.Node(Merge(compress=use_compression),
name="merge",
mem_gb=mem_gb)
if not multiecho:
# 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,
)
if use_fieldwarp:
# fmt:off
workflow.connect([(inputnode, merge_xforms, [('fieldwarp', 'in2')])
])
# fmt:on
# fmt:off
workflow.connect([
# merge transforms
(inputnode, merge_xforms, [('hmc_xforms', 'in%d' % nforms),
('bold2anat', 'in1')]),
(merge_xforms, bold_to_t1w_transform, [('out', 'transforms')]),
(inputnode, bold_to_t1w_transform, [('bold_split', 'input_image')
]),
])
# fmt:on
else:
from nipype.interfaces.fsl import Split as FSLSplit
bold_split = pe.Node(FSLSplit(dimension="t"),
name="bold_split",
mem_gb=DEFAULT_MEMORY_MIN_GB)
# fmt:off
workflow.connect([
(inputnode, bold_split, [('bold_split', 'in_file')]),
(bold_split, bold_to_t1w_transform, [('out_files', 'input_image')
]),
(inputnode, bold_to_t1w_transform, [('bold2anat', 'transforms')]),
])
# fmt:on
# fmt:off
workflow.connect([
(inputnode, merge, [('name_source', 'header_source')]),
(gen_ref, bold_to_t1w_transform, [('out_file', 'reference_image')]),
(bold_to_t1w_transform, merge, [('out_files', 'in_files')]),
(merge, outputnode, [('out_file', 'bold_t1')]),
])
# fmt:on
return workflow