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() 
in_filesa list of items which are a pathlike object or string representing an existing file

Images for filtering.

addnoisea 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_prefixa string

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

filename_suffixa string

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

intliman integer

Intensity limitation (default = 100). (Nipype default value: 100)

matlab_cmda string

Matlab command to use.

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

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

replace_nan_and_infa boolean

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

riciana 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_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

out_filea 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() 
in_filesa list of items which are a pathlike object or string representing an existing file

File to segment.

n_jobsan integer

Number of threads. (Nipype default value: 1)

affine_preprocessingan 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_regularizationa 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)

cobraa boolean

Extract brain measures for COBRA template. (Nipype default value: True)

csf_output_dartela boolean

Save dartel CSF images. (Nipype default value: False)

csf_output_modulateda boolean

Save dartel CSF images. (Nipype default value: True)

csf_output_nativea boolean

Save dartel CSF images. (Nipype default value: False)

gm_output_dartela boolean

Save dartel grey matter images. (Nipype default value: False)

gm_output_modulateda boolean

Save native grey matter images. (Nipype default value: True)

gm_output_nativea boolean

Save modulated grey matter images. (Nipype default value: False)

hammersa boolean

Extract brain measures for Hammers template. (Nipype default value: True)

ignore_errorsan 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_segmentationan 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_processa tuple of the form: (a float, a float)

Help_resampling. (Nipype default value: (1, 0.1))

jacobianwarpeda 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_dartela boolean

This is the option to save a labeled version of your segmentations in the dartel space for fast visual comparision. 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_nativea boolean

This is the option to save a labeled version of your segmentations in the native space for fast visual comparision. 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_warpeda boolean

This is the option to save a labeled version of your segmentations in the warped space for fast visual comparision. 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_dartela 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_nativea 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_warpeda 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_sega 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)

lpba40a boolean

Extract brain measures for LPBA40 template. (Nipype default value: True)

matlab_cmda string

Matlab command to use.

mfilea boolean

Run m-code using m-file. (Nipype default value: True)

neuromorphometricsa boolean

Extract brain measures for Neuromorphometrics template. (Nipype default value: True)

output_labelnativea boolean

This is the option to save a labeled version of your segmentations in the native space for fast visual comparision. 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_atlasa list of items which are a pathlike object or string representing an existing file

Extract brain measures for a given template.

pathsa list of items which are a pathlike object or string representing a directory

Paths to add to matlabpath.

power_spm_inhomogeneity_correctiona 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_correcteda boolean

Save bias corrected image. (Nipype default value: True)

shooting_tpma 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_1a 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_2a 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_3a 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_4a 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_stripa 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 automaticaly 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_estimationan 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_measuresan integer

Extract surface measures. (Nipype default value: 1)

tpma 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_mcra boolean

Run m-code using SPM MCR.

use_v8structa boolean

Generate SPM8 and higher compatible jobs. (Nipype default value: True)

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

warpsa 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_correctionan 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_dartela boolean

Save dartel white matter images. (Nipype default value: False)

wm_output_modulateda boolean

Save dartel white matter images. (Nipype default value: True)

wm_output_nativea boolean

Save dartel white matter images. (Nipype default value: False)

bias_corrected_imagea pathlike object or string representing an existing file

Bias corrected image.

csf_dartel_imagea pathlike object or string representing an existing file

CSF dartel image.

csf_modulated_imagea pathlike object or string representing an existing file

CSF modulated image.

csf_native_imagea pathlike object or string representing an existing file

CSF in native space.

gm_dartel_imagea pathlike object or string representing an existing file

Grey matter dartel image.

gm_modulated_imagea pathlike object or string representing an existing file

Grey matter modulated image.

gm_native_imagea pathlike object or string representing an existing file

Grey matter native space.

label_filesa list of items which are a pathlike object or string representing an existing file

Files with the measures extracted for OI ands ROIs.

label_roia pathlike object or string representing an existing file

Files with thickness values of ROI.

label_roisa pathlike object or string representing an existing file

Files with thickness values of ROIs.

lh_central_surfacea pathlike object or string representing an existing file

Central left hemisphere files.

lh_sphere_surfacea pathlike object or string representing an existing file

Sphere left hemisphere files.

mri_imagesa list of items which are a pathlike object or string representing an existing file

Different segmented images.

reporta pathlike object or string representing an existing file

Report file.

report_filesa list of items which are a pathlike object or string representing an existing file

Report files.

rh_central_surfacea pathlike object or string representing an existing file

Central right hemisphere files.

rh_sphere_surfacea pathlike object or string representing an existing file

Sphere right hemisphere files.

surface_filesa list of items which are a pathlike object or string representing an existing file

Surface files.

wm_dartel_imagea pathlike object or string representing an existing file

White matter dartel image.

wm_modulated_imagea pathlike object or string representing an existing file

White matter modulated image.

wm_native_imagea 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