def extract_magnitude_pipeline(self, **name_maps):
pipeline = self.new_pipeline(
'extract_magnitude',
desc="Extracts the first b==0 volume from the series",
citations=[],
name_maps=name_maps)
dwiextract = pipeline.add(
'dwiextract',
ExtractDWIorB0(
bzero=True,
out_ext='.nii.gz'),
inputs={
'in_file': ('series', nifti_gz_format),
'fslgrad': self.fsl_grads(pipeline, coregistered=False)},
requirements=[mrtrix_req.v('3.0rc3')])
pipeline.add(
"extract_first_vol",
MRConvert(
coord=(3, 0)),
inputs={
'in_file': (dwiextract, 'out_file')},
outputs={
'magnitude': ('out_file', nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3')])
return pipeline
def extract_magnitude_pipeline(self, **name_maps):
pipeline = self.new_pipeline(
'extract_magnitude',
desc="Extracts a single magnitude volume from a series",
citations=[],
name_maps=name_maps)
pipeline.add("extract_first_vol",
MRConvert(coord=(3, 0)),
inputs={'in_file': ('series', nifti_gz_format)},
outputs={'magnitude': ('out_file', nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3')])
return pipeline
def extract_b0_pipeline(self, **name_maps): # @UnusedVariable
"""
Extracts the b0 images from a DWI study and takes their mean
"""
# inputs=[FilesetSpec('bias_correct', nifti_gz_format),
# FilesetSpec('grad_dirs', fsl_bvecs_format),
# FilesetSpec('bvalues', fsl_bvals_format)],
# outputs=[FilesetSpec('b0', nifti_gz_format)],
pipeline = self.new_pipeline(
name='extract_b0',
desc="Extract b0 image from a DWI study",
references=[mrtrix_cite],
name_maps=name_maps)
# Gradient merge node
fsl_grads = pipeline.add("fsl_grads", MergeTuple(2))
# Extraction node
extract_b0s = pipeline.add(
'extract_b0s', ExtractDWIorB0(),
requirements=[mrtrix_req.v('3.0rc3')])
extract_b0s.inputs.bzero = True
extract_b0s.inputs.quiet = True
# FIXME: Need a registration step before the mean
# Mean calculation node
mean = pipeline.add(
"mean",
MRMath(),
requirements=[mrtrix_req.v('3.0rc3')])
mean.inputs.axis = 3
mean.inputs.operation = 'mean'
mean.inputs.quiet = True
# Convert to Nifti
mrconvert = pipeline.add("output_conversion", MRConvert(),
requirements=[mrtrix_req.v('3.0rc3')])
mrconvert.inputs.out_ext = '.nii.gz'
mrconvert.inputs.quiet = True
# Connect inputs
pipeline.connect_input('bias_correct', extract_b0s, 'in_file')
pipeline.connect_input('grad_dirs', fsl_grads, 'in1')
pipeline.connect_input('bvalues', fsl_grads, 'in2')
# Connect between nodes
pipeline.connect(extract_b0s, 'out_file', mean, 'in_files')
pipeline.connect(fsl_grads, 'out', extract_b0s, 'grad_fsl')
pipeline.connect(mean, 'out_file', mrconvert, 'in_file')
# Connect outputs
pipeline.connect_output('b0', mrconvert, 'out_file')
# Check inputs/outputs are connected
return pipeline
def extract_b0_pipeline(self, **name_maps):
"""
Extracts the b0 images from a DWI study and takes their mean
"""
pipeline = self.new_pipeline(
name='extract_b0',
desc="Extract b0 image from a DWI study",
citations=[mrtrix_cite],
name_maps=name_maps)
# Extraction node
extract_b0s = pipeline.add(
'extract_b0s',
ExtractDWIorB0(
bzero=True,
quiet=True),
inputs={
'fslgrad': self.fsl_grads(pipeline),
'in_file': (self.series_preproc_spec_name, nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# FIXME: Need a registration step before the mean
# Mean calculation node
mean = pipeline.add(
"mean",
MRMath(
axis=3,
operation='mean',
quiet=True),
inputs={
'in_files': (extract_b0s, 'out_file')},
requirements=[mrtrix_req.v('3.0rc3')])
# Convert to Nifti
pipeline.add(
"output_conversion",
MRConvert(
out_ext='.nii.gz',
quiet=True),
inputs={
'in_file': (mean, 'out_file')},
outputs={
'b0': ('out_file', nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3')])
return pipeline
def interface(self):
return MRConvert(out_ext=self.output_format.extension, quiet=True)
def intensity_normalisation_pipeline(self, **name_maps):
# inputs=[FilesetSpec('bias_correct', nifti_gz_format),
# FilesetSpec('brain_mask', nifti_gz_format),
# FilesetSpec('grad_dirs', fsl_bvecs_format),
# FilesetSpec('bvalues', fsl_bvals_format)],
# outputs=[FilesetSpec('norm_intensity', mrtrix_format),
# FilesetSpec('norm_intens_fa_template', mrtrix_format,
# frequency='per_study'),
# FilesetSpec('norm_intens_wm_mask', mrtrix_format,
# frequency='per_study')],
pipeline = self.new_pipeline(
name='intensity_normalization',
desc="Corrects for B1 field inhomogeneity",
references=[mrtrix_req.v('3.0rc3')],
name_maps=name_maps)
# Convert from nifti to mrtrix format
grad_merge = pipeline.add("grad_merge", MergeTuple(2))
mrconvert = pipeline.add('mrconvert', MRConvert())
mrconvert.inputs.out_ext = '.mif'
# Set up join nodes
fields = ['dwis', 'masks', 'subject_ids', 'visit_ids']
join_subjects = pipeline.add(
'join_subjects',
IdentityInterface(fields),
joinsource=self.SUBJECT_ID,
joinfield=fields)
join_visits = pipeline.add(
'join_visits',
Chain(fields),
joinsource=self.VISIT_ID,
joinfield=fields)
# Set up expand nodes
select = pipeline.add(
'expand', SelectSession())
# Intensity normalization
intensity_norm = pipeline.add(
'dwiintensitynorm', DWIIntensityNorm())
# Connect inputs
pipeline.connect_input('bias_correct', mrconvert, 'in_file')
pipeline.connect_input('grad_dirs', grad_merge, 'in1')
pipeline.connect_input('bvalues', grad_merge, 'in2')
pipeline.connect_subject_id(join_subjects, 'subject_ids')
pipeline.connect_visit_id(join_subjects, 'visit_ids')
pipeline.connect_subject_id(select, 'subject_id')
pipeline.connect_visit_id(select, 'visit_id')
pipeline.connect_input('brain_mask', join_subjects, 'masks')
# Internal connections
pipeline.connect(grad_merge, 'out', mrconvert, 'grad_fsl')
pipeline.connect(mrconvert, 'out_file', join_subjects, 'dwis')
pipeline.connect(join_subjects, 'dwis', join_visits, 'dwis')
pipeline.connect(join_subjects, 'masks', join_visits, 'masks')
pipeline.connect(join_subjects, 'subject_ids', join_visits,
'subject_ids')
pipeline.connect(join_subjects, 'visit_ids', join_visits,
'visit_ids')
pipeline.connect(join_visits, 'dwis', intensity_norm, 'in_files')
pipeline.connect(join_visits, 'masks', intensity_norm, 'masks')
pipeline.connect(join_visits, 'subject_ids', select, 'subject_ids')
pipeline.connect(join_visits, 'visit_ids', select, 'visit_ids')
pipeline.connect(intensity_norm, 'out_files', select, 'items')
# Connect outputs
pipeline.connect_output('norm_intensity', select, 'item')
pipeline.connect_output('norm_intens_fa_template', intensity_norm,
'fa_template')
pipeline.connect_output('norm_intens_wm_mask', intensity_norm,
'wm_mask')
return pipeline
def preprocess_pipeline(self, **name_maps): # @UnusedVariable @IgnorePep8
"""
Performs a series of FSL preprocessing steps, including Eddy and Topup
Parameters
----------
phase_dir : str{AP|LR|IS}
The phase encode direction
"""
# Determine whether we can correct for distortion, i.e. if reference
# scans are provided
# Include all references
references = [fsl_cite, eddy_cite, topup_cite,
distort_correct_cite]
if self.branch('preproc_denoise'):
references.extend(dwidenoise_cites)
pipeline = self.new_pipeline(
name='preprocess',
name_maps=name_maps,
desc=(
"Preprocess dMRI studies using distortion correction"),
references=references)
# Create nodes to gradients to FSL format
if self.input('magnitude').format == dicom_format:
extract_grad = pipeline.add(
"extract_grad",
ExtractFSLGradients(),
inputs={
'in_file': ('magnitude', dicom_format)},
outputs={
'bvecs_file': ('grad_dirs', fsl_bvecs_format),
'bvals_file': ('bvalues', fsl_bvals_format)},
requirements=[mrtrix_req.v('3.0rc3')])
grad_fsl_kwargs = {
'connect': {'in1': (extract_grad, 'bvecs_file'),
'in2': (extract_grad, 'bvals_file')}}
elif self.provided('grad_dirs') and self.provided('bvalues'):
grad_fsl_kwargs = {
'inputs': {'in1': ('grad_dirs', fsl_bvecs_format),
'in2': ('bvalues', fsl_bvals_format)}}
else:
raise ArcanaDesignError(
"Either input 'magnitude' image needs to be in DICOM format "
"or gradient directions and b-values need to be explicitly "
"provided to {}".format(self))
# Gradient merge node
grad_fsl = pipeline.add(
"grad_fsl",
MergeTuple(2),
**grad_fsl_kwargs)
# Denoise the dwi-scan
if self.branch('preproc_denoise'):
# Run denoising
denoise = pipeline.add(
'denoise',
DWIDenoise(),
inputs={
'in_file': ('magnitude', nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# Calculate residual noise
subtract_operands = pipeline.add(
'subtract_operands',
Merge(2),
inputs={
'in1': ('magnitude', nifti_gz_format)},
connect={
'in2': (denoise, 'noise')})
pipeline.add(
'subtract',
MRCalc(
operation='subtract'),
connect={
'operands': (subtract_operands, 'out')},
outputs={
'out_file': ('noise_residual', mrtrix_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# Preproc kwargs
preproc_kwargs = {}
if (self.provided('dwi_reference') or
self.provided('reverse_phase')):
# Extract b=0 volumes
dwiextract = pipeline.add(
'dwiextract',
ExtractDWIorB0(
bzero=True,
out_ext='.nii.gz'),
inputs={
'in_file': ('magnitude', dicom_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# Get first b=0 from dwi b=0 volumes
mrconvert = pipeline.add(
"mrconvert",
MRConvert(
coord=(3, 0)),
connect={
'in_file': (dwiextract, 'out_file')},
requirements=[mrtrix_req.v('3.0rc3')])
# Concatenate extracted forward rpe with reverse rpe
mrcat = pipeline.add(
'mrcat',
MRCat(),
inputs={
'second_scan': ((
'dwi_reference' if self.provided('dwi_reference')
else 'reverse_phase'), mrtrix_format)},
connect={
'first_scan': (mrconvert, 'out_file')},
requirements=[mrtrix_req.v('3.0rc3')])
# Create node to assign the right PED to the diffusion
prep_dwi = pipeline.add(
'prepare_dwi',
PrepareDWI(),
inputs={
'pe_dir': ('ped', float),
'ped_polarity': ('pe_angle', float)})
preproc_kwargs['rpe_pair'] = True
distortion_correction = True
preproc_conns = {'connect': {'se_epi': (mrcat, 'out_file')}}
else:
distortion_correction = False
preproc_kwargs['rpe_none'] = True
preproc_conns = {}
if self.parameter('preproc_pe_dir') is not None:
preproc_kwargs['pe_dir'] = self.parameter('preproc_pe_dir')
preproc = pipeline.add(
'dwipreproc',
DWIPreproc(
no_clean_up=True,
out_file_ext='.nii.gz',
# FIXME: Need to determine this programmatically
# eddy_parameters = '--data_is_shelled '
temp_dir='dwipreproc_tempdir',
**preproc_kwargs),
connect={
'grad_fsl': (grad_fsl, 'out')},
outputs={
'eddy_parameters': ('eddy_par', eddy_par_format)},
requirements=[mrtrix_req.v('3.0rc3'), fsl_req.v('5.0.10')],
wall_time=60,
**preproc_conns)
if self.branch('preproc_denoise'):
pipeline.connect(denoise, 'out_file', preproc, 'in_file')
else:
pipeline.connect_input('magnitude', preproc, 'in_file',
nifti_gz_format)
if distortion_correction:
pipeline.connect(prep_dwi, 'pe', preproc, 'pe_dir')
# Create node to reorient preproc out_file
pipeline.add(
'fslreorient2std',
fsl.utils.Reorient2Std(),
connect={
'in_file': (preproc, 'out_file')},
outputs={
'out_file': ('preproc', nifti_gz_format)},
requirements=[fsl_req.v('5.0.9')])
return pipeline
def intensity_normalisation_pipeline(self, **name_maps):
if self.num_sessions < 2:
raise ArcanaMissingDataException(
"Cannot normalise intensities of DWI images as study only "
"contains a single session")
elif self.num_sessions < self.RECOMMENDED_NUM_SESSIONS_FOR_INTENS_NORM:
logger.warning(
"The number of sessions in the study ({}) is less than the "
"recommended number for intensity normalisation ({}). The "
"results may be unreliable".format(
self.num_sessions,
self.RECOMMENDED_NUM_SESSIONS_FOR_INTENS_NORM))
pipeline = self.new_pipeline(
name='intensity_normalization',
desc="Corrects for B1 field inhomogeneity",
citations=[mrtrix_req.v('3.0rc3')],
name_maps=name_maps)
mrconvert = pipeline.add(
'mrconvert',
MRConvert(
out_ext='.mif'),
inputs={
'in_file': (self.series_preproc_spec_name, nifti_gz_format),
'grad_fsl': self.fsl_grads(pipeline)},
requirements=[mrtrix_req.v('3.0rc3')])
# Pair subject and visit ids together, expanding so they can be
# joined and chained together
session_ids = pipeline.add(
'session_ids',
utility.IdentityInterface(
['subject_id', 'visit_id']),
inputs={
'subject_id': (Study.SUBJECT_ID, int),
'visit_id': (Study.VISIT_ID, int)})
# Set up join nodes
join_fields = ['dwis', 'masks', 'subject_ids', 'visit_ids']
join_over_subjects = pipeline.add(
'join_over_subjects',
utility.IdentityInterface(
join_fields),
inputs={
'masks': (self.brain_mask_spec_name, nifti_gz_format),
'dwis': (mrconvert, 'out_file'),
'subject_ids': (session_ids, 'subject_id'),
'visit_ids': (session_ids, 'visit_id')},
joinsource=self.SUBJECT_ID,
joinfield=join_fields)
join_over_visits = pipeline.add(
'join_over_visits',
Chain(
join_fields),
inputs={
'dwis': (join_over_subjects, 'dwis'),
'masks': (join_over_subjects, 'masks'),
'subject_ids': (join_over_subjects, 'subject_ids'),
'visit_ids': (join_over_subjects, 'visit_ids')},
joinsource=self.VISIT_ID,
joinfield=join_fields)
# Intensity normalization
intensity_norm = pipeline.add(
'dwiintensitynorm',
DWIIntensityNorm(),
inputs={
'in_files': (join_over_visits, 'dwis'),
'masks': (join_over_visits, 'masks')},
outputs={
'norm_intens_fa_template': ('fa_template',
mrtrix_image_format),
'norm_intens_wm_mask': ('wm_mask', mrtrix_image_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# Set up expand nodes
pipeline.add(
'expand', SelectSession(),
inputs={
'subject_ids': (join_over_visits, 'subject_ids'),
'visit_ids': (join_over_visits, 'visit_ids'),
'inlist': (intensity_norm, 'out_files'),
'subject_id': (Study.SUBJECT_ID, int),
'visit_id': (Study.VISIT_ID, int)},
outputs={
'norm_intensity': ('item', mrtrix_image_format)})
# Connect inputs
return pipeline
def preprocess_pipeline(self, **name_maps):
"""
Performs a series of FSL preprocessing steps, including Eddy and Topup
Parameters
----------
phase_dir : str{AP|LR|IS}
The phase encode direction
"""
# Determine whether we can correct for distortion, i.e. if reference
# scans are provided
# Include all references
references = [fsl_cite, eddy_cite, topup_cite,
distort_correct_cite, n4_cite]
if self.branch('preproc_denoise'):
references.extend(dwidenoise_cites)
pipeline = self.new_pipeline(
name='preprocess',
name_maps=name_maps,
desc=(
"Preprocess dMRI studies using distortion correction"),
citations=references)
# Create nodes to gradients to FSL format
if self.input('series').format == dicom_format:
extract_grad = pipeline.add(
"extract_grad",
ExtractFSLGradients(),
inputs={
'in_file': ('series', dicom_format)},
outputs={
'grad_dirs': ('bvecs_file', fsl_bvecs_format),
'bvalues': ('bvals_file', fsl_bvals_format)},
requirements=[mrtrix_req.v('3.0rc3')])
grad_fsl_inputs = {'in1': (extract_grad, 'bvecs_file'),
'in2': (extract_grad, 'bvals_file')}
elif self.provided('grad_dirs') and self.provided('bvalues'):
grad_fsl_inputs = {'in1': ('grad_dirs', fsl_bvecs_format),
'in2': ('bvalues', fsl_bvals_format)}
else:
raise BananaUsageError(
"Either input 'magnitude' image needs to be in DICOM format "
"or gradient directions and b-values need to be explicitly "
"provided to {}".format(self))
# Gradient merge node
grad_fsl = pipeline.add(
"grad_fsl",
MergeTuple(2),
inputs=grad_fsl_inputs)
gradients = (grad_fsl, 'out')
# Create node to reorient preproc out_file
if self.branch('reorient2std'):
reorient = pipeline.add(
'fslreorient2std',
fsl.utils.Reorient2Std(
output_type='NIFTI_GZ'),
inputs={
'in_file': ('series', nifti_gz_format)},
requirements=[fsl_req.v('5.0.9')])
reoriented = (reorient, 'out_file')
else:
reoriented = ('series', nifti_gz_format)
# Denoise the dwi-scan
if self.branch('preproc_denoise'):
# Run denoising
denoise = pipeline.add(
'denoise',
DWIDenoise(),
inputs={
'in_file': reoriented},
requirements=[mrtrix_req.v('3.0rc3')])
# Calculate residual noise
subtract_operands = pipeline.add(
'subtract_operands',
Merge(2),
inputs={
'in1': reoriented,
'in2': (denoise, 'noise')})
pipeline.add(
'subtract',
MRCalc(
operation='subtract'),
inputs={
'operands': (subtract_operands, 'out')},
outputs={
'noise_residual': ('out_file', mrtrix_image_format)},
requirements=[mrtrix_req.v('3.0rc3')])
denoised = (denoise, 'out_file')
else:
denoised = reoriented
# Preproc kwargs
preproc_kwargs = {}
preproc_inputs = {'in_file': denoised,
'grad_fsl': gradients}
if self.provided('reverse_phase'):
if self.provided('magnitude', default_okay=False):
dwi_reference = ('magnitude', mrtrix_image_format)
else:
# Extract b=0 volumes
dwiextract = pipeline.add(
'dwiextract',
ExtractDWIorB0(
bzero=True,
out_ext='.nii.gz'),
inputs={
'in_file': denoised,
'fslgrad': gradients},
requirements=[mrtrix_req.v('3.0rc3')])
# Get first b=0 from dwi b=0 volumes
extract_first_b0 = pipeline.add(
"extract_first_vol",
MRConvert(
coord=(3, 0)),
inputs={
'in_file': (dwiextract, 'out_file')},
requirements=[mrtrix_req.v('3.0rc3')])
dwi_reference = (extract_first_b0, 'out_file')
# Concatenate extracted forward rpe with reverse rpe
combined_images = pipeline.add(
'combined_images',
MRCat(),
inputs={
'first_scan': dwi_reference,
'second_scan': ('reverse_phase', mrtrix_image_format)},
requirements=[mrtrix_req.v('3.0rc3')])
# Create node to assign the right PED to the diffusion
prep_dwi = pipeline.add(
'prepare_dwi',
PrepareDWI(),
inputs={
'pe_dir': ('ped', float),
'ped_polarity': ('pe_angle', float)})
preproc_kwargs['rpe_pair'] = True
distortion_correction = True
preproc_inputs['se_epi'] = (combined_images, 'out_file')
else:
distortion_correction = False
preproc_kwargs['rpe_none'] = True
if self.parameter('preproc_pe_dir') is not None:
preproc_kwargs['pe_dir'] = self.parameter('preproc_pe_dir')
preproc = pipeline.add(
'dwipreproc',
DWIPreproc(
no_clean_up=True,
out_file_ext='.nii.gz',
# FIXME: Need to determine this programmatically
# eddy_parameters = '--data_is_shelled '
temp_dir='dwipreproc_tempdir',
**preproc_kwargs),
inputs=preproc_inputs,
outputs={
'eddy_par': ('eddy_parameters', eddy_par_format)},
requirements=[mrtrix_req.v('3.0rc3'), fsl_req.v('5.0.10')],
wall_time=60)
if distortion_correction:
pipeline.connect(prep_dwi, 'pe', preproc, 'pe_dir')
mask = pipeline.add(
'dwi2mask',
BrainMask(
out_file='brainmask.nii.gz'),
inputs={
'in_file': (preproc, 'out_file'),
'grad_fsl': gradients},
requirements=[mrtrix_req.v('3.0rc3')])
# Create bias correct node
pipeline.add(
"bias_correct",
DWIBiasCorrect(
method='ants'),
inputs={
'grad_fsl': gradients, # internal
'in_file': (preproc, 'out_file'),
'mask': (mask, 'out_file')},
outputs={
'series_preproc': ('out_file', nifti_gz_format)},
requirements=[mrtrix_req.v('3.0rc3'), ants_req.v('2.0')])
return pipeline
