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.

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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – Root directory.

  • 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.bids_dir = '/my_directory'
>>> 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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

  • 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)

  • 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.

FilteringByRunid

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs a filtering of files.

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

Examples

>>> from pymialsrtk.interfaces.preprocess import FilteringByRunid
>>> stacksFiltering = FilteringByRunid()
>>> 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_files (a list of items which are a pathlike object or string representing a file) – Input files on which motion is computed.

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

Outputs

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

FilteringByRunid.m_output_files = []

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.bids_dir = '/my_directory'
>>> 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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

  • 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: "")

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.bids_dir = '/my_directory'
>>> 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()
Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

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)

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.bids_dir = '/my_directory'
>>> intensityStandardization.inputs.input_images = ['sub-01_acq-haste_run-1_T2w.nii.gz','sub-01_acq-haste_run-2_T2w.nii.gz']
>>> intensityStandardization.run()
Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

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.

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.bids_dir = '/my_directory'
>>> 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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

  • 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: "")

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.bids_dir = '/my_directory'
>>> 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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

  • 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)

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.bids_dir = '/my_directory'
>>> 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

  • bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

  • 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)

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).

MultipleBrainExtraction

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs on multiple images the automatic brain extraction module.

It calls on a list of images the pymialsrtk.interfaces.preprocess.BrainExtraction.BrainExtraction module that implements a brain extraction algorithm 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)

See also

pymialsrtk.interfaces.preprocess.BrainExtraction

Mandatory Inputs

  • bids_dir (a string or os.PathLike object referring to an existing directory) – Root directory.

  • 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.

Optional Inputs

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

  • 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 determining cutoff probability (0.5 by default).

Outputs

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

MultipleBtkNLMDenoising

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Apply the non-local mean (NLM) denoising module on multiple inputs.

It runs for each input image the interface pymialsrtk.interfaces.preprocess.BtkNLMDenoising to the NLM denoising 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 MultipleBtkNLMDenoising
>>> multiNlmDenoise = MultipleBtkNLMDenoising()
>>> multiNlmDenoise.inputs.bids_dir = '/my_directory'
>>> multiNlmDenoise.inputs.in_file = ['sub-01_acq-haste_run-1_T2w.nii.gz', 'sub-01_acq-haste_run-1_2w.nii.gz']
>>> multiNlmDenoise.inputs.in_mask = ['sub-01_acq-haste_run-1_mask.nii.gz', 'sub-01_acq-haste_run-2_mask.nii.gz']
>>> multiNlmDenoise.run()

See also

pymialsrtk.interfaces.preprocess.BtkNLMDenoising

Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

Optional Inputs

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

  • 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 input image filenames to construst denoised output filenames. (Nipype default value: _nlm)

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

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Output denoised images.

MultipleMialsrtkCorrectSliceIntensity

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Apply the MIAL SRTK slice intensity correction module on multiple images.

It calls MialsrtkCorrectSliceIntensity interface with a list of images/masks.

Example

>>> from pymialsrtk.interfaces.preprocess import MultipleMialsrtkCorrectSliceIntensity
>>> multiSliceIntensityCorr = MialsrtkCorrectSliceIntensity()
>>> multiSliceIntensityCorr.inputs.bids_dir = '/my_directory'
>>> multiSliceIntensityCorr.inputs.in_file = ['sub-01_acq-haste_run-1_T2w.nii.gz', 'sub-01_acq-haste_run-2_T2w.nii.gz']
>>> multiSliceIntensityCorr.inputs.in_mask = ['sub-01_acq-haste_run-2_mask.nii.gz', 'sub-01_acq-haste_run-2_mask.nii.gz']
>>> multiSliceIntensityCorr.run()

See also

pymialsrtk.interfaces.preprocess.MialsrtkCorrectSliceIntensity

Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

Optional Inputs

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

  • 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 input image filenames to construct corrected output filenames. (Nipype default value: "")

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Output slice intensity corrected images.

MultipleMialsrtkMaskImage

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK mask image module on multiple images.

It calls the pymialsrtk.interfaces.preprocess.MialsrtkMaskImage interface with a list of images/masks.

Example

>>> from pymialsrtk.interfaces.preprocess import MultipleMialsrtkMaskImage
>>> multiMaskImg = MultipleMialsrtkMaskImage()
>>> multiMaskImg.inputs.bids_dir = '/my_directory'
>>> multiMaskImg.inputs.in_file = ['sub-01_acq-haste_run-1_T2w.nii.gz', 'sub-01_acq-haste_run-2_T2w.nii.gz']
>>> multiMaskImg.inputs.in_mask = ['sub-01_acq-haste_run-1_mask.nii.gz', 'sub-01_acq-haste_run-2_mask.nii.gz']
>>> multiMaskImg.inputs.out_im_postfix = '_masked'
>>> multiMaskImg.run()

See also

pymialsrtk.interfaces.preprocess.MialsrtkMaskImage

Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

Optional Inputs

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

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

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

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Output masked image filenames.

MultipleMialsrtkSliceBySliceCorrectBiasField

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

Runs the MIAL SRTK slice by slice bias field correction module on multiple images.

It calls pymialsrtk.interfaces.preprocess.MialsrtkSliceBySliceCorrectBiasField interface with a list of images/masks/fields.

Example

>>> from pymialsrtk.interfaces.preprocess import MultipleMialsrtkSliceBySliceN4BiasFieldCorrection
>>> multiN4biasFieldCorr = MialsrtkSliceBySliceN4BiasFieldCorrection()
>>> multiN4biasFieldCorr.inputs.bids_dir = '/my_directory'
>>> multiN4biasFieldCorr.inputs.input_images = ['sub-01_acq-haste_run-1_T2w.nii.gz', 'sub-01_acq-haste_run-2_T2w.nii.gz']
>>> multiN4biasFieldCorr.inputs.input_masks = ['sub-01_acq-haste_run-1_mask.nii.gz', 'sub-01_acq-haste_run-2_mask.nii.gz']
>>> multiN4biasFieldCorr.inputs.input_fields = ['sub-01_acq-haste_run-1_field.nii.gz', 'sub-01_acq-haste_run-2_field.nii.gz']
>>> multiN4biasFieldCorr.run()

See also

pymialsrtk.interfaces.preprocess.MialsrtkSliceBySliceCorrectBiasField

Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

Optional Inputs

  • input_fields (a list of items which are a pathlike object or string representing a file) – Bias field files to be removed.

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

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

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

Outputs

output_images (a list of items which are a pathlike object or string representing a file) – Output bias field corrected images.

MultipleMialsrtkSliceBySliceN4BiasFieldCorrection

Link to code

Bases: nipype.interfaces.base.core.BaseInterface

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

Calls MialsrtkSliceBySliceN4BiasFieldCorrection interface that implements the method proposed by Tustison et al. [1]_ with a list of images/masks.

References

1

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

Example

>>> from pymialsrtk.interfaces.preprocess import MultipleMialsrtkSliceBySliceN4BiasFieldCorrection
>>> multiN4biasFieldCorr = MialsrtkSliceBySliceN4BiasFieldCorrection()
>>> multiN4biasFieldCorr.inputs.bids_dir = '/my_directory'
>>> multiN4biasFieldCorr.inputs.input_images = ['sub-01_acq-haste_run-1_T2w.nii.gz', 'sub-01_acq-haste_run-2_T2w.nii.gz']
>>> multiN4biasFieldCorr.inputs.inputs_masks = ['sub-01_acq-haste_run-1_mask.nii.gz', 'sub-01_acq-haste_run-2_mask.nii.gz']
>>> multiN4biasFieldCorr.run()

See also

pymialsrtk.interfaces.preprocess.MialsrtkSliceBySliceN4BiasFieldCorrection

Mandatory Inputs

bids_dir (a string or os.PathLike object referring to an existing directory) – BIDS root directory.

Optional Inputs

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

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

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

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

Outputs

  • output_fields (a list of items which are a pathlike object or string representing a file) – Output bias fields.

  • output_images (a list of items which are a pathlike object or string representing a file) – Output N4 bias field corrected images.

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.

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.

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 = []