def init_bold_reference_wf(omp_nthreads,
bold_file=None,
name='bold_reference_wf'):
"""
This workflow generates reference BOLD images for a series
The raw reference image is the target of :abbr:`HMC (head motion correction)`, and a
contrast-enhanced reference is the subject of distortion correction, as well as
boundary-based registration to T1w and template spaces.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold import init_bold_reference_wf
wf = init_bold_reference_wf(omp_nthreads=1)
**Parameters**
bold_file : str
BOLD series NIfTI file
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: ``bold_reference_wf``)
**Inputs**
bold_file
BOLD series NIfTI file
**Outputs**
bold_file
Validated BOLD series NIfTI file
raw_ref_image
Reference image to which BOLD series is motion corrected
skip_vols
Number of non-steady-state volumes detected at beginning of ``bold_file``
ref_image
Contrast-enhanced reference image
ref_image_brain
Skull-stripped reference image
bold_mask
Skull-stripping mask of reference image
bold_mask_report
Reportlet showing quality of masking
validation_report
HTML reportlet indicating whether ``bold_file`` had a valid affine
**Subworkflows**
* :py:func:`~fmriprep.workflows.bold.util.init_enhance_and_skullstrip_wf`
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=['bold_file']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=[
'bold_file', 'raw_ref_image', 'skip_vols', 'ref_image',
'ref_image_brain', 'bold_mask', 'bold_mask_report', 'validation_report'
]),
name='outputnode')
# Simplify manually setting input image
if bold_file is not None:
inputnode.inputs.bold_file = bold_file
validate = pe.Node(ValidateImage(),
name='validate',
mem_gb=DEFAULT_MEMORY_MIN_GB,
run_without_submitting=True)
gen_ref = pe.Node(EstimateReferenceImage(), name="gen_ref",
mem_gb=1) # OE: 128x128x128x50 * 64 / 8 ~ 900MB.
enhance_and_skullstrip_bold_wf = init_enhance_and_skullstrip_bold_wf(
omp_nthreads=omp_nthreads)
workflow.connect([
(inputnode, validate, [('bold_file', 'in_file')]),
(validate, gen_ref, [('out_file', 'in_file')]),
(gen_ref, enhance_and_skullstrip_bold_wf, [('ref_image',
'inputnode.in_file')]),
(validate, outputnode, [('out_file', 'bold_file'),
('out_report', 'validation_report')]),
(gen_ref, outputnode, [('ref_image', 'raw_ref_image'),
('n_volumes_to_discard', 'skip_vols')]),
(enhance_and_skullstrip_bold_wf, outputnode,
[('outputnode.bias_corrected_file', 'ref_image'),
('outputnode.mask_file', 'bold_mask'),
('outputnode.out_report', 'bold_mask_report'),
('outputnode.skull_stripped_file', 'ref_image_brain')]),
])
return workflow
def hmc(name='fMRI_HMC'):
"""
Create a :abbr:`HMC (head motion correction)` workflow for fMRI.
.. workflow::
from mriqc.workflows.functional import hmc
from mriqc.testing import mock_config
with mock_config():
wf = hmc()
"""
from nipype.algorithms.confounds import FramewiseDisplacement
from nipype.interfaces.afni import Calc, TShift, Refit, Despike, Volreg
from niworkflows.interfaces.registration import EstimateReferenceImage
mem_gb = config.workflow.biggest_file_gb
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(
fields=['in_file', 'fd_radius', 'start_idx', 'stop_idx']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(fields=['out_file', 'out_fd']),
name='outputnode')
if any((config.workflow.start_idx is not None, config.workflow.stop_idx
is not None)):
drop_trs = pe.Node(Calc(expr='a', outputtype='NIFTI_GZ'),
name='drop_trs')
workflow.connect([
(inputnode, drop_trs, [('in_file', 'in_file_a'),
('start_idx', 'start_idx'),
('stop_idx', 'stop_idx')]),
])
else:
drop_trs = pe.Node(niu.IdentityInterface(fields=['out_file']),
name='drop_trs')
workflow.connect([
(inputnode, drop_trs, [('in_file', 'out_file')]),
])
gen_ref = pe.Node(EstimateReferenceImage(mc_method="AFNI"), name="gen_ref")
# calculate hmc parameters
hmc = pe.Node(Volreg(args='-Fourier -twopass',
zpad=4,
outputtype='NIFTI_GZ'),
name='motion_correct',
mem_gb=mem_gb * 2.5)
# Compute the frame-wise displacement
fdnode = pe.Node(FramewiseDisplacement(normalize=False,
parameter_source="AFNI"),
name='ComputeFD')
workflow.connect([
(inputnode, fdnode, [('fd_radius', 'radius')]),
(gen_ref, hmc, [('ref_image', 'basefile')]),
(hmc, outputnode, [('out_file', 'out_file')]),
(hmc, fdnode, [('oned_file', 'in_file')]),
(fdnode, outputnode, [('out_file', 'out_fd')]),
])
# Slice timing correction, despiking, and deoblique
st_corr = pe.Node(TShift(outputtype='NIFTI_GZ'), name='TimeShifts')
deoblique_node = pe.Node(Refit(deoblique=True), name='deoblique')
despike_node = pe.Node(Despike(outputtype='NIFTI_GZ'), name='despike')
if all((config.workflow.correct_slice_timing, config.workflow.despike,
config.workflow.deoblique)):
workflow.connect([
(drop_trs, st_corr, [('out_file', 'in_file')]),
(st_corr, despike_node, [('out_file', 'in_file')]),
(despike_node, deoblique_node, [('out_file', 'in_file')]),
(deoblique_node, gen_ref, [('out_file', 'in_file')]),
(deoblique_node, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.correct_slice_timing and config.workflow.despike:
workflow.connect([
(drop_trs, st_corr, [('out_file', 'in_file')]),
(st_corr, despike_node, [('out_file', 'in_file')]),
(despike_node, gen_ref, [('out_file', 'in_file')]),
(despike_node, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.correct_slice_timing and config.workflow.deoblique:
workflow.connect([
(drop_trs, st_corr, [('out_file', 'in_file')]),
(st_corr, deoblique_node, [('out_file', 'in_file')]),
(deoblique_node, gen_ref, [('out_file', 'in_file')]),
(deoblique_node, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.correct_slice_timing:
workflow.connect([
(drop_trs, st_corr, [('out_file', 'in_file')]),
(st_corr, gen_ref, [('out_file', 'in_file')]),
(st_corr, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.despike and config.workflow.deoblique:
workflow.connect([
(drop_trs, despike_node, [('out_file', 'in_file')]),
(despike_node, deoblique_node, [('out_file', 'in_file')]),
(deoblique_node, gen_ref, [('out_file', 'in_file')]),
(deoblique_node, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.despike:
workflow.connect([
(drop_trs, despike_node, [('out_file', 'in_file')]),
(despike_node, gen_ref, [('out_file', 'in_file')]),
(despike_node, hmc, [('out_file', 'in_file')]),
])
elif config.workflow.deoblique:
workflow.connect([
(drop_trs, deoblique_node, [('out_file', 'in_file')]),
(deoblique_node, gen_ref, [('out_file', 'in_file')]),
(deoblique_node, hmc, [('out_file', 'in_file')]),
])
else:
workflow.connect([
(drop_trs, gen_ref, [('out_file', 'in_file')]),
(drop_trs, hmc, [('out_file', 'in_file')]),
])
return workflow
def init_bold_reference_wf(omp_nthreads, bold_file=None, pre_mask=False,
name='bold_reference_wf', gen_report=False):
"""
This workflow generates reference BOLD images for a series
The raw reference image is the target of :abbr:`HMC (head motion correction)`, and a
contrast-enhanced reference is the subject of distortion correction, as well as
boundary-based registration to T1w and template spaces.
.. workflow::
:graph2use: orig
:simple_form: yes
from fmriprep.workflows.bold import init_bold_reference_wf
wf = init_bold_reference_wf(omp_nthreads=1)
**Parameters**
bold_file : str
BOLD series NIfTI file
omp_nthreads : int
Maximum number of threads an individual process may use
name : str
Name of workflow (default: ``bold_reference_wf``)
gen_report : bool
Whether a mask report node should be appended in the end
enhance_t2 : bool
Perform logarithmic transform of input BOLD image to improve contrast
before calculating the preliminary mask
**Inputs**
bold_file
BOLD series NIfTI file
bold_mask : bool
A tentative brain mask to initialize the workflow (requires ``pre_mask``
parameter set ``True``).
**Outputs**
bold_file
Validated BOLD series NIfTI file
raw_ref_image
Reference image to which BOLD series is motion corrected
skip_vols
Number of non-steady-state volumes detected at beginning of ``bold_file``
ref_image
Contrast-enhanced reference image
ref_image_brain
Skull-stripped reference image
bold_mask
Skull-stripping mask of reference image
validation_report
HTML reportlet indicating whether ``bold_file`` had a valid affine
**Subworkflows**
* :py:func:`~fmriprep.workflows.bold.util.init_enhance_and_skullstrip_wf`
"""
workflow = Workflow(name=name)
workflow.__desc__ = """\
First, a reference volume and its skull-stripped version were generated
using a custom methodology of *fMRIPrep*.
"""
inputnode = pe.Node(niu.IdentityInterface(fields=['bold_file', 'sbref_file', 'bold_mask']),
name='inputnode')
outputnode = pe.Node(
niu.IdentityInterface(fields=['bold_file', 'raw_ref_image', 'skip_vols', 'ref_image',
'ref_image_brain', 'bold_mask', 'validation_report',
'mask_report']),
name='outputnode')
# Simplify manually setting input image
if bold_file is not None:
inputnode.inputs.bold_file = bold_file
validate = pe.Node(ValidateImage(), name='validate', mem_gb=DEFAULT_MEMORY_MIN_GB)
gen_ref = pe.Node(EstimateReferenceImage(), name="gen_ref",
mem_gb=1) # OE: 128x128x128x50 * 64 / 8 ~ 900MB.
# Re-run validation; no effect if no sbref; otherwise apply same validation to sbref as bold
validate_ref = pe.Node(ValidateImage(), name='validate_ref', mem_gb=DEFAULT_MEMORY_MIN_GB)
enhance_and_skullstrip_bold_wf = init_enhance_and_skullstrip_bold_wf(
omp_nthreads=omp_nthreads, pre_mask=pre_mask)
workflow.connect([
(inputnode, enhance_and_skullstrip_bold_wf, [('bold_mask', 'inputnode.pre_mask')]),
(inputnode, validate, [('bold_file', 'in_file')]),
(inputnode, gen_ref, [('sbref_file', 'sbref_file')]),
(validate, gen_ref, [('out_file', 'in_file')]),
(gen_ref, validate_ref, [('ref_image', 'in_file')]),
(validate_ref, enhance_and_skullstrip_bold_wf, [('out_file', 'inputnode.in_file')]),
(validate, outputnode, [('out_file', 'bold_file'),
('out_report', 'validation_report')]),
(gen_ref, outputnode, [('n_volumes_to_discard', 'skip_vols')]),
(validate_ref, outputnode, [('out_file', 'raw_ref_image')]),
(enhance_and_skullstrip_bold_wf, outputnode, [
('outputnode.bias_corrected_file', 'ref_image'),
('outputnode.mask_file', 'bold_mask'),
('outputnode.skull_stripped_file', 'ref_image_brain')]),
])
if gen_report:
mask_reportlet = pe.Node(SimpleShowMaskRPT(), name='mask_reportlet')
workflow.connect([
(enhance_and_skullstrip_bold_wf, mask_reportlet, [
('outputnode.bias_corrected_file', 'background_file'),
('outputnode.mask_file', 'mask_file'),
]),
])
return workflow
def init_epi_hmc_wf(metadata, bold_file_size_gb, ignore,
name='epi_hmc_wf'):
"""
Performs :abbr:`HMC (head motion correction)` over the input
:abbr:`EPI (echo-planar imaging)` image.
"""
workflow = pe.Workflow(name=name)
inputnode = pe.Node(niu.IdentityInterface(fields=['epi']),
name='inputnode')
outputnode = pe.Node(niu.IdentityInterface(
fields=['xforms', 'epi_hmc', 'epi_split', 'epi_mask', 'ref_image',
'ref_image_brain', 'movpar_file', 'n_volumes_to_discard',
'epi_mask_report']), name='outputnode')
def normalize_motion_func(in_file, format):
import os
import numpy as np
from nipype.utils.misc import normalize_mc_params
mpars = np.loadtxt(in_file) # mpars is N_t x 6
mpars = np.apply_along_axis(func1d=normalize_mc_params,
axis=1, arr=mpars,
source=format)
np.savetxt("motion_params.txt", mpars)
return os.path.abspath("motion_params.txt")
normalize_motion = pe.Node(niu.Function(function=normalize_motion_func),
name="normalize_motion", run_without_submitting=True)
normalize_motion.inputs.format = "FSL"
# Head motion correction (hmc)
hmc = pe.Node(fsl.MCFLIRT(
save_mats=True, save_plots=True), name='EPI_hmc')
hmc.interface.estimated_memory_gb = bold_file_size_gb * 3
hcm2itk = pe.MapNode(c3.C3dAffineTool(fsl2ras=True, itk_transform=True),
iterfield=['transform_file'], name='hcm2itk')
enhance_and_skullstrip_epi_wf = init_enhance_and_skullstrip_epi_wf()
gen_ref = pe.Node(EstimateReferenceImage(), name="gen_ref")
workflow.connect([
(inputnode, gen_ref, [('epi', 'in_file')]),
(gen_ref, enhance_and_skullstrip_epi_wf, [('ref_image', 'inputnode.in_file')]),
(gen_ref, hmc, [('ref_image', 'ref_file')]),
(enhance_and_skullstrip_epi_wf, outputnode, [('outputnode.bias_corrected_file', 'ref_image'),
('outputnode.mask_file', 'epi_mask'),
('outputnode.out_report', 'epi_mask_report'),
('outputnode.skull_stripped_file', 'ref_image_brain')]),
])
split = pe.Node(fsl.Split(dimension='t'), name='split')
split.interface.estimated_memory_gb = bold_file_size_gb * 3
if "SliceTiming" in metadata and 'slicetiming' not in ignore:
LOGGER.info('Slice-timing correction will be included.')
def create_custom_slice_timing_file_func(metadata):
import os
slice_timings = metadata["SliceTiming"]
slice_timings_ms = [str(t) for t in slice_timings]
out_file = "timings.1D"
with open("timings.1D", "w") as fp:
fp.write("\t".join(slice_timings_ms))
return os.path.abspath(out_file)
create_custom_slice_timing_file = pe.Node(
niu.Function(function=create_custom_slice_timing_file_func),
name="create_custom_slice_timing_file", run_without_submitting=True)
create_custom_slice_timing_file.inputs.metadata = metadata
slice_timing_correction = pe.Node(interface=afni.TShift(),
name='slice_timing_correction')
slice_timing_correction.inputs.outputtype = 'NIFTI_GZ'
slice_timing_correction.inputs.tr = str(metadata["RepetitionTime"]) + "s"
def prefix_at(x):
return "@" + x
workflow.connect([
(inputnode, slice_timing_correction, [('epi', 'in_file')]),
(gen_ref, slice_timing_correction, [('n_volumes_to_discard', 'ignore')]),
(create_custom_slice_timing_file, slice_timing_correction, [
(('out', prefix_at), 'tpattern')]),
(slice_timing_correction, hmc, [('out_file', 'in_file')])
])
else:
workflow.connect([
(inputnode, hmc, [('epi', 'in_file')])
])
workflow.connect([
(hmc, hcm2itk, [('mat_file', 'transform_file')]),
(gen_ref, hcm2itk, [('ref_image', 'source_file'),
('ref_image', 'reference_file')]),
(hcm2itk, outputnode, [('itk_transform', 'xforms')]),
(hmc, normalize_motion, [('par_file', 'in_file')]),
(normalize_motion, outputnode, [('out', 'movpar_file')]),
(inputnode, split, [('epi', 'in_file')]),
(split, outputnode, [('out_files', 'epi_split')]),
])
return workflow