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() # doctest: +SKIP

bids_dir : a directory name

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.

out_postfix : a unicode 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).

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() # doctest: +SKIP

bids_dir : a directory name

BIDS root directory.

in_file : a pathlike object or string representing a file

Input image filename.

in_mask : a pathlike object or string representing a file

Input mask filename.

out_postfix : a unicode 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)

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() # doctest: +SKIP

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.

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() # doctest: +SKIP

bids_dir : a directory name

BIDS root directory.

in_file : a pathlike object or string representing a file

Input image filename.

in_mask : a pathlike object or string representing a file

Input mask filename.

out_postfix : a unicode string

Suffix to be added to input image file to construct corrected output filename. (Nipype default value: "")

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()  # doctest: +SKIP

bids_dir : a directory name

BIDS root directory.

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 unicode string

Suffix to be added to normalized input image filenames to construct ouptut normalized image filenames. (Nipype default value: _histnorm)

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() # doctest: +SKIP

bids_dir : a directory name

BIDS root directory.

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

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() # doctest: +SKIP

bids_dir : a directory name

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.

out_im_postfix : a unicode string

Suffix to be added to masked in_file. (Nipype default value: "")

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() # doctest: +SKIP

bids_dir : a directory name

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.

out_im_postfix : a unicode string

Suffix to be added to bias field corrected in_file. (Nipype default value: _bcorr)

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() # doctest: +SKIP

bids_dir : a directory name

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.

out_fld_postfix : a unicode string

Suffix to be added to input image filename to construct output bias field filename. (Nipype default value: _n4bias)

out_im_postfix : a unicode string

Suffix to be added to input image filename to construct corrected output filename. (Nipype default value: _bcorr)

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

bids_dir : a directory name

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.

input_images : a list of items which are a pathlike object or string representing a file

MRI Images.

out_postfix : a unicode 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).

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() # doctest: +SKIP

See also

pymialsrtk.interfaces.preprocess.BtkNLMDenoising

bids_dir : a directory name

BIDS root directory.

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

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() # doctest: +SKIP

See also

pymialsrtk.interfaces.preprocess.MialsrtkCorrectSliceIntensity

bids_dir : a directory name

BIDS root directory.

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 unicode string

Suffix to be added to input image filenames to construct corrected output filenames. (Nipype default value: "")

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() # doctest: +SKIP

See also

pymialsrtk.interfaces.preprocess.MialsrtkMaskImage

bids_dir : a directory name

BIDS root directory.

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 unicode string

Suffix to be added to masked input_images. (Nipype default value: "")

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() # doctest: +SKIP

See also

pymialsrtk.interfaces.preprocess.MialsrtkSliceBySliceCorrectBiasField

bids_dir : a directory name

BIDS root directory.

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 unicode string

Suffix to be added to bias field corrected input_images. (Nipype default value: _bcorr)

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() # doctest: +SKIP

See also

pymialsrtk.interfaces.preprocess.MialsrtkSliceBySliceN4BiasFieldCorrection

bids_dir : a directory name

BIDS root directory.

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 unicode string

Suffix to be added to input image filenames to construct output bias field filenames. (Nipype default value: _n4bias)

out_im_postfix : a unicode string

Suffix to be added to input image filenames to construct corrected output filenames. (Nipype default value: _bcorr)

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() # doctest: +SKIP

input_masks : a list of items which are a pathlike object or string representing a file

Input brain masks on which motion is computed.

stacks_order : a list of items which are any value

Order of image run-id to be used for reconstruction.

StacksOrdering.m_stack_order = []