nipype.interfaces.cat12.preprocess module

CAT12SANLMDenoising

Link to code

Bases: SPMCommand

Spatially adaptive non-local means (SANLM) denoising filter

This function applies an spatial adaptive (sub-resolution) non-local means denoising filter to the data. This filter will remove noise while preserving edges. The filter strength is automatically estimated based on the standard deviation of the noise.

This filter is internally used in the segmentation procedure anyway. Thus, it is not necessary (and not recommended) to apply the filter before segmentation. ______________________________________________________________________ Christian Gaser, Robert Dahnke Structural Brain Mapping Group (http://www.neuro.uni-jena.de) Departments of Neurology and Psychiatry Jena University Hospital ______________________________________________________________________

Examples

>>> from nipype.interfaces import cat12
>>> c = cat12.CAT12SANLMDenoising()
>>> c.inputs.in_files = 'anatomical.nii'
>>> c.run()
Mandatory Inputs:

in_files (a list of items which are a pathlike object or string representing an existing file) – Images for filtering.

Optional Inputs:

  • addnoise (a float) –

    Strength of additional noise in noise-free regions.

    Add minimal amount of noise in regions without any noise to avoid image segmentation problems. This parameter defines the strength of additional noise as percentage of the average signal intensity.

    (Nipype default value: 0.5)

  • filename_prefix (a string) – Filename prefix. Specify the string to be prepended to the filenames of the filtered image file(s). (Nipype default value: sanlm_)

  • filename_suffix (a string) – Filename suffix. Specify the string to be appended to the filenames of the filtered image file(s). (Nipype default value: "")

  • intlim (an integer) – Intensity limitation (default = 100). (Nipype default value: 100)

  • matlab_cmd (a string) – Matlab command to use.

  • mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

  • noisecorr_strength (‘-Inf’ or 2 or 4) –

    Strength of Noise Corrections

    Strength of the (sub-resolution) spatial adaptive non local means (SANLM) noise correction. Please note that the filter strength is automatically estimated. Change this parameter only for specific conditions. The “light” option applies half of the filter strength of the adaptive “medium” cases, whereas the “strong” option uses the full filter strength, force sub-resolution filtering and applies an additional iteration. Sub-resolution filtering is only used in case of high image resolution below 0.8 mm or in case of the “strong” option. light = 2, medium = -Inf, strong = 4.

    (Nipype default value: -Inf)

  • paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

  • replace_nan_and_inf (a boolean) – Replace NAN by 0, -INF by the minimum and INF by the maximum of the image. (Nipype default value: True)

  • rician (a boolean) –

    Rician noise

    MRIs can have Gaussian or Rician distributed noise with uniform or nonuniform variance across the image. If SNR is high enough (>3) noise can be well approximated by Gaussian noise in the foreground. However, for SENSE reconstruction or DTI data a Rician distribution is expected. Please note that the Rician noise estimation is sensitive for large signals in the neighbourhood and can lead to artefacts, e.g. cortex can be affected by very high values in the scalp or in blood vessels.

    (Nipype default value: True)

  • spm_type (‘float32’ or ‘uint16’ or ‘uint8’ or ‘same’) – Data type of the output images. ‘same’ matches the input image type. (Nipype default value: float32)

  • use_mcr (a boolean) – Run m-code using SPM MCR.

  • use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

Outputs:

out_file (a pathlike object or string representing a file) – Out file.

CAT12Segment

Link to code

Bases: SPMCommand

CAT12: Segmentation

This toolbox is an extension to the default segmentation in SPM12, but uses a completely different segmentation approach. The segmentation approach is based on an Adaptive Maximum A Posterior (MAP) technique without the need for a priori information about tissue probabilities. That is, the Tissue Probability Maps (TPM) are not used constantly in the sense of the classical Unified Segmentation approach (Ashburner et. al. 2005), but just for spatial normalization. The following AMAP estimation is adaptive in the sense that local variations of the parameters (i.e., means and variance) are modeled as slowly varying spatial functions (Rajapakse et al. 1997). This not only accounts for intensity inhomogeneities but also for other local variations of intensity. Additionally, the segmentation approach uses a Partial Volume Estimation (PVE) with a simplified mixed model of at most two tissue types (Tohka et al. 2004). We start with an initial segmentation into three pure classes: gray matter (GM), white matter (WM), and cerebrospinal fluid (CSF) based on the above described AMAP estimation. The initial segmentation is followed by a PVE of two additional mixed classes: GM-WM and GM-CSF. This results in an estimation of the amount (or fraction) of each pure tissue type present in every voxel (as single voxels - given by Another important extension to the SPM12 segmentation is the integration of the Dartel or Geodesic Shooting registration into the toolbox by an already existing Dartel/Shooting template in MNI space. This template was derived from 555 healthy control subjects of the IXI-database (http://www.brain-development.org) and provides the several Dartel or Shooting iterations. Thus, for the majority of studies the creation of sample-specific templates is not necessary anymore and is mainly recommended for children data.’};

http://www.neuro.uni-jena.de/cat12/CAT12-Manual.pdf#page=15

Examples

>>> path_mr = 'structural.nii'
>>> cat = CAT12Segment(in_files=path_mr)
>>> cat.run()
Mandatory Inputs:

  • in_files (a list of items which are a pathlike object or string representing an existing file) – File to segment.

  • n_jobs (an integer) – Number of threads. (Nipype default value: 1)

Optional Inputs:

  • affine_preprocessing (an integer) – Affine registration and SPM preprocessing can fail in some subjects with deviating anatomy (e.g. other species/neonates) or in images with strong signal inhomogeneities, or untypical intensities (e.g. synthetic images). An initial bias correction can help to reduce such problems (see details below). Recommended are the “default” and “full” option. (Nipype default value: 1070)

  • affine_regularization (a string) – Affine Regularization. The procedure is a local optimisation, so it needs reasonable initial starting estimates. Images should be placed in approximate alignment using the Display function of SPM before beginning. A Mutual Information affine registration with the tissue probability maps (DAgostino et al, 2004) is used to achieve approximate alignment. (Nipype default value: mni)

  • cobra (a boolean) – Extract brain measures for COBRA template. (Nipype default value: True)

  • csf_output_dartel (a boolean) – Save dartel CSF images. (Nipype default value: False)

  • csf_output_modulated (a boolean) – Save dartel CSF images. (Nipype default value: True)

  • csf_output_native (a boolean) – Save dartel CSF images. (Nipype default value: False)

  • gm_output_dartel (a boolean) – Save dartel grey matter images. (Nipype default value: False)

  • gm_output_modulated (a boolean) – Save native grey matter images. (Nipype default value: True)

  • gm_output_native (a boolean) – Save modulated grey matter images. (Nipype default value: False)

  • hammers (a boolean) – Extract brain measures for Hammers template. (Nipype default value: True)

  • ignore_errors (an integer) – Error handling. Try to catch preprocessing errors and continue with the next data set or ignore all warnings (e.g., bad intensities) and use an experimental pipeline which is still in development. In case of errors, CAT continues with the next subject if this option is enabled. If the experimental option with backup functions is selected and warnings occur, CAT will try to use backup routines and skip some processing steps which require good T1 contrasts (e.g., LAS). If you want to avoid processing of critical data and ensure that only the main pipeline is used then select the option “Ignore errors (continue with the next subject)”. It is strongly recommended to check for preprocessing problems, especially with non-T1 contrasts. Values: none: 0, default: 1, details: 2. (Nipype default value: 1)

  • initial_segmentation (an integer) – In rare cases the Unified Segmentation can fail in highly abnormal brains, where e.g. the cerebrospinal fluid of superlarge ventricles (hydrocephalus) were classified as white matter. However, if the affine registration is correct, the AMAP segmentation with an prior-independent k-means initialization can be used to replace the SPM brain tissue classification. Moreover, if the default Dartel and Shooting registrations will fail then rhe “Optimized Shooting - superlarge ventricles” option for “Spatial registration” is ! required Values: none: 0; light: 1; full: 2; default: 1070. (Nipype default value: 0)

  • internal_resampling_process (a tuple of the form: (a float, a float)) – Help_resampling. (Nipype default value: (1, 0.1))

  • jacobianwarped (a boolean) – This is the option to save the Jacobian determinant, which expresses local volume changes. This image can be used in a pure deformation based morphometry (DBM) design. Please note that the affine part of the deformation field is ignored. Thus, there is no need for any additional correction for different brain sizes using ICV. (Nipype default value: True)

  • label_dartel (a boolean) – This is the option to save a labeled version of your segmentations in the dartel space for fast visual comparison. Labels are saved as Partial Volume Estimation (PVE) values with different mix classes for GM-WM (2.5) and GM-CSF (1.5). BG=0, CSF=1, GM=2, WM=3, WMH=4 (if WMHC=3), SL=1.5 (if SLC). (Nipype default value: False)

  • label_native (a boolean) – This is the option to save a labeled version of your segmentations in the native space for fast visual comparison. Labels are saved as Partial Volume Estimation (PVE) values with different mix classes for GM-WM (2.5) and GM-CSF (1.5). BG=0, CSF=1, GM=2, WM=3, WMH=4 (if WMHC=3), SL=1.5 (if SLC). (Nipype default value: False)

  • label_warped (a boolean) – This is the option to save a labeled version of your segmentations in the warped space for fast visual comparison. Labels are saved as Partial Volume Estimation (PVE) values with different mix classes for GM-WM (2.5) and GM-CSF (1.5). BG=0, CSF=1, GM=2, WM=3, WMH=4 (if WMHC=3), SL=1.5 (if SLC). (Nipype default value: True)

  • las_dartel (a boolean) – This is the option to save a bias, noise, and local intensity corrected version of the original T1 image in the dartel space. MR images are usually corrupted by a smooth, spatially varying artifact that modulates the intensity of the image (bias). These artifacts, although not usually a problem for visual inspection, can impede automated processing of the images. The bias corrected version should have more uniform intensities within the different types of tissues and can be saved in native space and/or normalised. Noise is corrected by an adaptive non-local mean (NLM) filter (Manjon 2008, Medical Image Analysis 12). (Nipype default value: False)

  • las_native (a boolean) – This is the option to save a bias, noise, and local intensity corrected version of the original T1 image in the native space. MR images are usually corrupted by a smooth, spatially varying artifact that modulates the intensity of the image (bias). These artifacts, although not usually a problem for visual inspection, can impede automated processing of the images. The bias corrected version should have more uniform intensities within the different types of tissues and can be saved in native space and/or normalised. Noise is corrected by an adaptive non-local mean (NLM) filter (Manjon 2008, Medical Image Analysis 12). (Nipype default value: False)

  • las_warped (a boolean) – This is the option to save a bias, noise, and local intensity corrected version of the original T1 image in the warped space. MR images are usually corrupted by a smooth, spatially varying artifact that modulates the intensity of the image (bias). These artifacts, although not usually a problem for visual inspection, can impede automated processing of the images. The bias corrected version should have more uniform intensities within the different types of tissues and can be saved in native space and/or normalised. Noise is corrected by an adaptive non-local mean (NLM) filter (Manjon 2008, Medical Image Analysis 12). (Nipype default value: True)

  • local_adaptive_seg (a float) – Additionally to WM-inhomogeneities, GM intensity can vary across different regions such as the motor cortex, the basal ganglia, or the occipital lobe. These changes have an anatomical background (e.g. iron content, myelinization), but are dependent on the MR-protocol and often lead to underestimation of GM at higher intensities and overestimation of CSF at lower intensities. Therefore, a local intensity transformation of all tissue classes is used to reduce these effects in the image. This local adaptive segmentation (LAS) is applied before the final AMAP segmentation.Possible Values: SPM Unified Segmentation: 0 k-means AMAP: 2. (Nipype default value: 0.5)

  • lpba40 (a boolean) – Extract brain measures for LPBA40 template. (Nipype default value: True)

  • matlab_cmd (a string) – Matlab command to use.

  • mfile (a boolean) – Run m-code using m-file. (Nipype default value: True)

  • neuromorphometrics (a boolean) – Extract brain measures for Neuromorphometrics template. (Nipype default value: True)

  • output_labelnative (a boolean) – This is the option to save a labeled version of your segmentations in the native space for fast visual comparison. Labels are saved as Partial Volume Estimation (PVE) values with different mix classes for GM-WM (2.5) and GM-CSF (1.5). BG=0, CSF=1, GM=2, WM=3, WMH=4 (if WMHC=3), SL=1.5 (if SLC). (Nipype default value: False)

  • own_atlas (a list of items which are a pathlike object or string representing an existing file) – Extract brain measures for a given template.

  • paths (a list of items which are a pathlike object or string representing a directory) – Paths to add to matlabpath.

  • power_spm_inhomogeneity_correction (a float) – Strength of the SPM inhomogeneity (bias) correction that simultaneously controls the SPM biasreg, biasfwhm, samp (resolution), and tol (iteration) parameter. (Nipype default value: 0.5)

  • save_bias_corrected (a boolean) – Save bias corrected image. (Nipype default value: True)

  • shooting_tpm (a pathlike object or string representing an existing file) – Shooting Template 0. The Shooting template must be in multi-volume nifti format and should contain GM, WM, and background segmentations and have to be saved with at least 16 bit. .

  • shooting_tpm_template_1 (a pathlike object or string representing an existing file) – Shooting Template 1. The Shooting template must be in multi-volume nifti format and should contain GM, WM, and background segmentations and have to be saved with at least 16 bit. .

  • shooting_tpm_template_2 (a pathlike object or string representing an existing file) – Shooting Template 2. The Shooting template must be in multi-volume nifti format and should contain GM, WM, and background segmentations and have to be saved with at least 16 bit. .

  • shooting_tpm_template_3 (a pathlike object or string representing an existing file) – Shooting Template 3. The Shooting template must be in multi-volume nifti format and should contain GM, WM, and background segmentations and have to be saved with at least 16 bit. .

  • shooting_tpm_template_4 (a pathlike object or string representing an existing file) – Shooting Template 4. The Shooting template must be in multi-volume nifti format and should contain GM, WM, and background segmentations and have to be saved with at least 16 bit. .

  • skull_strip (a float) – Method of initial skull-stripping before AMAP segmentation. The SPM approach works quite stable for the majority of data. However, in some rare cases parts of GM (i.e. in frontal lobe) might be cut. If this happens the GCUT approach is a good alternative. GCUT is a graph-cut/region-growing approach starting from the WM area. APRG (adaptive probability region-growing) is a new method that refines the probability maps of the SPM approach by region-growing techniques of the gcut approach with a final surface-based optimization strategy. This is currently the method with the most accurate and reliable results. If you use already skull-stripped data you can turn off skull-stripping although this is automatically detected in most cases. Please note that the choice of the skull-stripping method will also influence the estimation of TIV, because the methods mainly differ in the handling of the outer CSF around the cortical surface. Possible Values:

    • none (already skull-stripped): -1;

    • SPM approach: 0;

    • GCUT approach: 0.50;

    • APRG approach: 2.

    (Nipype default value: 2)

  • surface_and_thickness_estimation (an integer) – Surface and thickness estimation. Use projection-based thickness (PBT) (Dahnke et al. 2012) to estimate cortical thickness and to create the central cortical surface for left and right hemisphere. Surface reconstruction includes topology correction (Yotter et al. 2011), spherical inflation (Yotter et al.) and spherical registration. Additionally you can also estimate surface parameters such as gyrification, cortical complexity or sulcal depth that can be subsequently analyzed at each vertex of the surface. Please note, that surface reconstruction and spherical registration additionally requires about 20-60 min of computation time. A fast (1-3 min) surface pipeline is available for visual preview (e.g., to check preprocessing quality) in the cross-sectional, but not in the longitudinal pipeline. Only the initial surfaces are created with a lower resolution and without topology correction, spherical mapping and surface registration. Please note that the files with the estimated surface thickness can therefore not be used for further analysis! For distinction, these files contain “preview” in their filename and they are not available as batch dependencies objects. . (Nipype default value: 1)

  • surface_measures (an integer) – Extract surface measures. (Nipype default value: 1)

  • tpm (a list of items which are a pathlike object or string representing an existing file) – Tissue Probability Map. Select the tissue probability image that includes 6 tissue probability classes for (1) grey matter, (2) white matter, (3) cerebrospinal fluid, (4) bone, (5) non-brain soft tissue, and (6) the background. CAT uses the TPM only for the initial SPM segmentation.

  • use_mcr (a boolean) – Run m-code using SPM MCR.

  • use_v8struct (a boolean) – Generate SPM8 and higher compatible jobs. (Nipype default value: True)

  • voxel_size (a float) – The (isotropic) voxel sizes of any spatially normalised written images. A non-finite value will be replaced by the average voxel size of the tissue probability maps used by the segmentation. (Nipype default value: 1.5)

  • warps (a tuple of the form: (an integer, an integer)) – Deformation fields can be saved to disk, and used by the Deformations Utility and/or applied to coregistered data from other modalities (e.g. fMRI). For spatially normalising images to MNI space, you will need the forward deformation, whereas for spatially normalising (eg) GIFTI surface files, youll need the inverse. It is also possible to transform data in MNI space on to the individual subject, which also requires the inverse transform. Deformations are saved as .nii files, which contain three volumes to encode the x, y and z coordinates. Values: No:[0 0]; Image->Template (forward): [1 0]; Template->Image (inverse): [0 1]; inverse + forward: [1 1]. (Nipype default value: (1, 0))

  • wm_hyper_intensity_correction (an integer) – WARNING: Please note that the detection of WM hyperintensies is still under development and does not have the same accuracy as approaches that additionally consider FLAIR images (e.g. Lesion Segmentation Toolbox)! In aging or (neurodegenerative) diseases WM intensity can be reduced locally in T1 or increased in T2/PD images. These so-called WM hyperintensies (WMHs) can lead to preprocessing errors. Large GM areas next to the ventricle can cause normalization problems. Therefore, a temporary correction for normalization is useful if WMHs are expected. CAT allows different ways to handle WMHs: 0) No Correction (handled as GM). 1) Temporary (internal) correction as WM for spatial normalization and estimation of cortical thickness. 2) Permanent correction to WM. . (Nipype default value: 1)

  • wm_output_dartel (a boolean) – Save dartel white matter images. (Nipype default value: False)

  • wm_output_modulated (a boolean) – Save dartel white matter images. (Nipype default value: True)

  • wm_output_native (a boolean) – Save dartel white matter images. (Nipype default value: False)

Outputs:

  • bias_corrected_image (a pathlike object or string representing an existing file) – Bias corrected image.

  • csf_dartel_image (a pathlike object or string representing an existing file) – CSF dartel image.

  • csf_modulated_image (a pathlike object or string representing an existing file) – CSF modulated image.

  • csf_native_image (a pathlike object or string representing an existing file) – CSF in native space.

  • gm_dartel_image (a pathlike object or string representing an existing file) – Grey matter dartel image.

  • gm_modulated_image (a pathlike object or string representing an existing file) – Grey matter modulated image.

  • gm_native_image (a pathlike object or string representing an existing file) – Grey matter native space.

  • label_files (a list of items which are a pathlike object or string representing an existing file) – Files with the measures extracted for OI ands ROIs.

  • label_roi (a pathlike object or string representing an existing file) – Files with thickness values of ROI.

  • label_rois (a pathlike object or string representing an existing file) – Files with thickness values of ROIs.

  • lh_central_surface (a pathlike object or string representing an existing file) – Central left hemisphere files.

  • lh_sphere_surface (a pathlike object or string representing an existing file) – Sphere left hemisphere files.

  • mri_images (a list of items which are a pathlike object or string representing an existing file) – Different segmented images.

  • report (a pathlike object or string representing an existing file) – Report file.

  • report_files (a list of items which are a pathlike object or string representing an existing file) – Report files.

  • rh_central_surface (a pathlike object or string representing an existing file) – Central right hemisphere files.

  • rh_sphere_surface (a pathlike object or string representing an existing file) – Sphere right hemisphere files.

  • surface_files (a list of items which are a pathlike object or string representing an existing file) – Surface files.

  • wm_dartel_image (a pathlike object or string representing an existing file) – White matter dartel image.

  • wm_modulated_image (a pathlike object or string representing an existing file) – White matter modulated image.

  • wm_native_image (a pathlike object or string representing an existing file) – White matter in native space.

class nipype.interfaces.cat12.preprocess.Cell2Str(arg)

Bases: nipype.interfaces.cat12.base.Cell