Preprocess module

PyMIALSRTK preprocessing functions.

It includes BTK Non-local-mean denoising, slice intensity correction slice N4 bias field correction, slice-by-slice correct bias field, intensity standardization, histogram normalization and both manual or deep learning based automatic brain extraction.

ApplyAlignmentTransform

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Apply a rigid 3D transform.

Examples

>>> from pymialsrtk.interfaces.preprocess import ApplyAlignmentTransform
>>> align_img = ApplyAlignmentTransform()
>>> align_img.inputs.input_image = "sub-01_acq-haste_run-1_T2w.nii.gz"
>>> align_img.inputs.input_template = "STA30.nii.gz"
>>> align_img.inputs.input_mask = "sub-01_acq-haste_run-1_T2w_mask.nii.gz"
>>> align_img.inputs.input_transform = "sub-01_acq-haste_run-1_rigid.tfm"
>>> align_img.run()
Mandatory Inputs

  • input_image (a pathlike object or string representing a file) – Input image to realign.

  • input_template (a pathlike object or string representing a file) – Input reference image.

  • input_transform (a pathlike object or string representing a file) – Input alignment transform to apply.

Optional Inputs

input_mask (a pathlike object or string representing a file) – Input mask to realign.

Outputs

  • output_image (a pathlike object or string representing a file) – Output reoriented image.

  • output_mask (a pathlike object or string representing a file) – Output reoriented mask.

BrainExtraction

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the automatic brain extraction module.

This module is based on a 2D U-Net (Ronneberger et al. [1]_) using the pre-trained weights from Salehi et al. [2]_.

References

1

Ronneberger et al.; Medical Image Computing and Computer Assisted Interventions, 2015. (link to paper)

2

Salehi et al.; arXiv, 2017. (link to paper)

Examples

>>> from pymialsrtk.interfaces.preprocess import BrainExtraction
>>> brainMask = BrainExtraction()
>>> brainmask.inputs.base_dir = '/my_directory'
>>> brainmask.inputs.in_file = 'sub-01_acq-haste_run-1_2w.nii.gz'
>>> brainmask.inputs.in_ckpt_loc = 'my_loc_checkpoint'
>>> brainmask.inputs.threshold_loc = 0.49
>>> brainmask.inputs.in_ckpt_seg = 'my_seg_checkpoint'
>>> brainmask.inputs.threshold_seg = 0.5
>>> brainmask.inputs.out_postfix = '_brainMask.nii.gz'
>>> brainmask.run()
Mandatory Inputs

  • in_ckpt_loc (a pathlike object or string representing a file) – Network_checkpoint for localization.

  • in_ckpt_seg (a pathlike object or string representing a file) – Network_checkpoint for segmentation.

  • in_file (a pathlike object or string representing a file) – Input image.

Optional Inputs

  • out_postfix (a string) – Suffix of the automatically generated mask. (Nipype default value: _brainMask)

  • threshold_loc (a float) – Threshold determining cutoff probability (0.49 by default).

  • threshold_seg (a float) – Threshold for cutoff probability (0.5 by default).

Outputs

out_file (a pathlike object or string representing a file) – Output brain mask image.

BtkNLMDenoising

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the non-local mean denoising module.

It calls the Baby toolkit implementation by Rousseau et al. [1]_ of the method proposed by Coupé et al. [2]_.

References

1

Rousseau et al.; Computer Methods and Programs in Biomedicine, 2013. (link to paper)

2

Coupé et al.; IEEE Transactions on Medical Imaging, 2008. (link to paper)

Example

>>> from pymialsrtk.interfaces.preprocess import BtkNLMDenoising
>>> nlmDenoise = BtkNLMDenoising()
>>> nlmDenoise.inputs.in_file = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> nlmDenoise.inputs.in_mask = 'sub-01_acq-haste_run-1_mask.nii.gz'
>>> nlmDenoise.inputs.weight = 0.2
>>> nlmDenoise.run()
Mandatory Inputs

in_file (a pathlike object or string representing a file) – Input image filename.

Optional Inputs

  • in_mask (a pathlike object or string representing a file) – Input mask filename.

  • out_postfix (a string) – Suffix to be added to input image filename to construst denoised output filename. (Nipype default value: _nlm)

  • verbose (a boolean) – Enable verbosity.

  • weight (a float) – NLM smoothing parameter (high beta produces smoother result). (Nipype default value: 0.1)

Outputs

out_file (a pathlike object or string representing a file) – Output denoised image file.

CheckAndFilterInputStacks

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs a filtering and a check on the input files.

This module filters the input files matching the specified run-ids. Other files are discarded.

Examples

>>> from pymialsrtk.interfaces.preprocess import CheckAndFilterInputStacks
>>> stacksFiltering = CheckAndFilterInputStacks()
>>> stacksFiltering.inputs.input_masks = ['sub-01_run-1_mask.nii.gz', 'sub-01_run-4_mask.nii.gz', 'sub-01_run-2_mask.nii.gz']
>>> stacksFiltering.inputs.stacks_id = [1,2]
>>> stacksFiltering.run()
Optional Inputs

  • input_images (a list of items which are a pathlike object or string representing a file) – Input images.

  • input_labels (a list of items which are a pathlike object or string representing a file) – Input label maps.

  • input_masks (a list of items which are a pathlike object or string representing a file) – Input masks.

  • stacks_id (a list of items which are any value) – List of stacks id to be kept.

Outputs

  • output_images (a list of items which are a string) – Filtered list of image files.

  • output_labels (a list of items which are any value) – Filtered list of label files.

  • output_masks (a list of items which are any value) – Filtered list of mask files.

  • output_stacks (a list of items which are any value) – Filtered list of stack files.

CheckAndFilterInputStacks.m_output_images = []
CheckAndFilterInputStacks.m_output_labels = []
CheckAndFilterInputStacks.m_output_masks = []
CheckAndFilterInputStacks.m_output_stacks = []

ComputeAlignmentToReference

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Reorient image along reference, based on principal brain axis.

This module relies on the implementation [1]_ from EbnerWang2020 [2]_.

References

1

(link to github)

2

Ebner et al. (2020). An automated framework for localization,

segmentation and super-resolution reconstruction of fetal brain MRI.

NeuroImage, 206, 116324. (link to paper)

Examples

>>> from pymialsrtk.interfaces.preprocess import ComputeAlignmentToReference
>>> align_to_ref = ComputeAlignmentToReference()
>>> align_to_ref.inputs.input_image = "sub-01_acq-haste_run-1_T2w.nii.gz"
>>> align_to_ref.inputs.input_template = "STA30.nii.gz"
>>> align_to_ref.run()
Mandatory Inputs

  • input_image (a pathlike object or string representing a file) – Input image to realign.

  • input_template (a pathlike object or string representing a file) – Input reference image.

Outputs

output_transform (a pathlike object or string representing a file) – Output 3D rigid tranformation file.

ComputeAlignmentToReference.m_best_transform = None

ListsMerger

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Interface to merge list of paths or list of list of paths.

Examples

>>> from pymialsrtk.interfaces.preprocess import ListsMerger
>>> merge_lists = ListsMerger()
>>> merge_lists.inputs.inputs = ["sub-01_acq-haste_run-1_labels_1.nii.gz", "sub-01_acq-haste_run-1_labels_2.nii.gz"]
>>> merge_lists.run()
Optional Inputs

inputs (a list of items which are any value)

Outputs

outputs (a list of items which are any value)

ListsMerger.m_list_of_files = None

MialsrtkCorrectSliceIntensity

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK mean slice intensity correction module.

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkCorrectSliceIntensity
>>> sliceIntensityCorr = MialsrtkCorrectSliceIntensity()
>>> sliceIntensityCorr.inputs.in_file = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> sliceIntensityCorr.inputs.in_mask = 'sub-01_acq-haste_run-1_mask.nii.gz'
>>> sliceIntensityCorr.run()
Mandatory Inputs

in_file (a pathlike object or string representing a file) – Input image filename.

Optional Inputs

  • in_mask (a pathlike object or string representing a file) – Input mask filename.

  • out_postfix (a string) – Suffix to be added to input image file to construct corrected output filename. (Nipype default value: "")

  • verbose (a boolean) – Enable verbosity.

Outputs

out_file (a pathlike object or string representing a file) – Output image with corrected slice intensities.

MialsrtkHistogramNormalization

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK histogram normalizaton module.

This module implements the method proposed by Nyúl et al. [1]_.

References

1

Nyúl et al.; Medical Imaging, IEEE Transactions, 2000. (link to paper)

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkHistogramNormalization
>>> histNorm = MialsrtkHistogramNormalization()
>>> histNorm.inputs.input_images = ['sub-01_acq-haste_run-1_T2w.nii.gz','sub-01_acq-haste_run-2_T2w.nii.gz']
>>> histNorm.inputs.input_masks = ['sub-01_acq-haste_run-1_mask.nii.gz','sub-01_acq-haste_run-2_mask.nii.gz']
>>> histNorm.run()
Optional Inputs

  • input_images (a list of items which are a pathlike object or string representing a file) – Input image filenames to be normalized.

  • input_masks (a list of items which are a pathlike object or string representing a file) – Input mask filenames.

  • out_postfix (a string) – Suffix to be added to normalized input image filenames to construct ouptut normalized image filenames. (Nipype default value: _histnorm)

  • verbose (a boolean) – Enable verbosity.

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Histogram-normalized images.

MialsrtkIntensityStandardization

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK intensity standardization module.

This module rescales image intensity by linear transformation

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkIntensityStandardization
>>> intensityStandardization= MialsrtkIntensityStandardization()
>>> intensityStandardization.inputs.input_images = ['sub-01_acq-haste_run-1_T2w.nii.gz','sub-01_acq-haste_run-2_T2w.nii.gz']
>>> intensityStandardization.run()
Optional Inputs

  • in_max (a float) – Maximal intensity.

  • input_images (a list of items which are a pathlike object or string representing a file) – Files to be corrected for intensity.

  • out_postfix (a string) – Suffix to be added to intensity corrected input_images. (Nipype default value: "")

  • stacks_order (a list of items which are any value) – Order of images index. To ensure images are processed with their correct corresponding mask.

  • verbose (a boolean) – Enable verbosity.

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Intensity-standardized images.

MialsrtkMaskImage

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK mask image module.

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkMaskImage
>>> maskImg = MialsrtkMaskImage()
>>> maskImg.inputs.in_file = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> maskImg.inputs.in_mask = 'sub-01_acq-haste_run-1_mask.nii.gz'
>>> maskImg.inputs.out_im_postfix = '_masked'
>>> maskImg.run()
Mandatory Inputs

  • in_file (a pathlike object or string representing a file) – Input image filename to be masked.

  • in_mask (a pathlike object or string representing a file) – Input mask filename.

Optional Inputs

  • out_im_postfix (a string) – Suffix to be added to masked in_file. (Nipype default value: "")

  • verbose (a boolean) – Enable verbosity.

Outputs

out_im_file (a pathlike object or string representing a file) – Masked image.

MialsrtkSliceBySliceCorrectBiasField

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK independant slice by slice bias field correction module.

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkSliceBySliceCorrectBiasField
>>> biasFieldCorr = MialsrtkSliceBySliceCorrectBiasField()
>>> biasFieldCorr.inputs.in_file = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> biasFieldCorr.inputs.in_mask = 'sub-01_acq-haste_run-1_mask.nii.gz'
>>> biasFieldCorr.inputs.in_field = 'sub-01_acq-haste_run-1_field.nii.gz'
>>> biasFieldCorr.run()
Mandatory Inputs

  • in_field (a pathlike object or string representing a file) – Input bias field file.

  • in_file (a pathlike object or string representing a file) – Input image file.

  • in_mask (a pathlike object or string representing a file) – Input mask file.

Optional Inputs

  • out_im_postfix (a string) – Suffix to be added to bias field corrected in_file. (Nipype default value: _bcorr)

  • verbose (a boolean) – Enable verbosity.

Outputs

out_im_file (a pathlike object or string representing a file) – Bias field corrected image.

MialsrtkSliceBySliceN4BiasFieldCorrection

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK slice by slice N4 bias field correction module.

This module implements the method proposed by Tustison et al. [1]_.

References

1

Tustison et al.; Medical Imaging, IEEE Transactions, 2010. (link to paper)

Example

>>> from pymialsrtk.interfaces.preprocess import MialsrtkSliceBySliceN4BiasFieldCorrection
>>> N4biasFieldCorr = MialsrtkSliceBySliceN4BiasFieldCorrection()
>>> N4biasFieldCorr.inputs.in_file = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> N4biasFieldCorr.inputs.in_mask = 'sub-01_acq-haste_run-1_mask.nii.gz'
>>> N4biasFieldCorr.run()
Mandatory Inputs

  • in_file (a pathlike object or string representing a file) – Input image.

  • in_mask (a pathlike object or string representing a file) – Input mask.

Optional Inputs

  • out_fld_postfix (a string) – Suffix to be added to input image filename to construct output bias field filename. (Nipype default value: _n4bias)

  • out_im_postfix (a string) – Suffix to be added to input image filename to construct corrected output filename. (Nipype default value: _bcorr)

  • verbose (a boolean) – Enable verbosity.

Outputs

  • out_fld_file (a pathlike object or string representing a file) – Filename bias field extracted slice by slice from input image.

  • out_im_file (a pathlike object or string representing a file) – Filename of corrected output image from N4 bias field (slice by slice).

ReduceFieldOfView

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Interface to reduce the Field-of-View.

Examples

>>> from pymialsrtk.interfaces.preprocess import ReduceFieldOfView
>>> reduce_fov = ReduceFieldOfView()
>>> reduce_fov.inputs.input_image = 'sub-01_acq-haste_run-1_T2w.nii.gz'
>>> reduce_fov.inputs.input_mask = 'sub-01_acq-haste_run-1_T2w_mask.nii.gz'
>>> reduce_fov.run()
Mandatory Inputs

  • input_image (a pathlike object or string representing a file) – Input image filename.

  • input_mask (a pathlike object or string representing a file) – Input mask filename.

Optional Inputs

input_label (a pathlike object or string representing a file) – Input label filename.

Outputs

  • output_image (a pathlike object or string representing a file) – Cropped image.

  • output_label (a pathlike object or string representing a file) – Cropped labels.

  • output_mask (a pathlike object or string representing a file) – Cropped mask.

ResampleImage

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Retrieve atlas of the same age and resample it to subject’s in-plane resolution.

Examples

>>> from pymialsrtk.interfaces.preprocess import ResampleImage
>>> resample_image = ResampleImage()
>>> resample_image.inputs.input_image = "sub-01_acq-haste_run-1_T2w.nii.gz"
>>> resample_image.inputs.input_reference = "STA30.nii.gz"
>>> resample_image.run()
Mandatory Inputs

  • input_image (a pathlike object or string representing a file) – Input image to resample.

  • input_reference (a pathlike object or string representing a file) – Input image with reference resolution.

Optional Inputs

verbose (a boolean) – Enable verbosity.

Outputs

output_image (a pathlike object or string representing a file) – Masked image.

SplitLabelMaps

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Split a multi-label labelmap into one label map per label.

Examples

>>> from pymialsrtk.interfaces.preprocess import SplitLabelMaps
>>> split_labels = SplitLabelMaps()
>>> split_labels.inputs.in_labelmap = 'sub-01_acq-haste_run-1_labels.nii.gz'
>>> split_labels.run()
Mandatory Inputs

in_labelmap (a pathlike object or string representing a file) – Input label map.

Optional Inputs

all_labels (a list of items which are any value)

Outputs

  • out_labelmaps (a list of items which are a pathlike object or string representing a file) – Output masks.

  • out_labels (a list of items which are any value) – List of labels ids that were extracted.

StacksOrdering

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the automatic ordering of stacks.

This module is based on the tracking of the brain mask centroid slice by slice.

Examples

>>> from pymialsrtk.interfaces.preprocess import StacksOrdering
>>> stacksOrdering = StacksOrdering()
>>> stacksOrdering.inputs.input_masks = ['sub-01_run-1_mask.nii.gz',
>>>                                      'sub-01_run-4_mask.nii.gz',
>>>                                      'sub-01_run-2_mask.nii.gz']
>>> stacksOrdering.run()

Note

In the case of discontinuous brain masks, the centroid coordinates of the slices excluded from the mask are set to numpy.nan and are not anymore considered in the motion index computation since v2.0.2 release. Prior to this release, the centroids of these slices were set to zero that has shown to drastically increase the motion index with respect to the real motion during acquisition. However the motion in the remaining slices that were actually used for SR reconstruction might not correspond to the high value of this index.

Mandatory Inputs

sub_ses (a string) – Subject and session BIDS identifier.

Optional Inputs

  • input_masks (a list of items which are a pathlike object or string representing a file) – Input brain masks on which motion is computed.

  • verbose (a boolean) – Enable verbosity.

Outputs

  • motion_tsv (a pathlike object or string representing a file) – Output TSV file with results used to create report_image.

  • report_image (a pathlike object or string representing a file) – Output PNG image for report.

  • stacks_order (a list of items which are any value) – Order of image run-id to be used for reconstruction.

StacksOrdering.m_stack_order = []