pymialsrtk.interfaces.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
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
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
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
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
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
- 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
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
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
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
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
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
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
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
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
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
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
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 sincev2.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 = []