nipype.algorithms.rapidart module

The rapidart module provides routines for artifact detection and region of interest analysis.

These functions include:

  • ArtifactDetect: performs artifact detection on functional images
  • StimulusCorrelation: determines correlation between stimuli schedule and movement/intensity parameters

ArtifactDetect

Link to code

Bases: BaseInterface

Detects outliers in a functional imaging series

Uses intensity and motion parameters to infer outliers. If use_norm is True, it computes the movement of the center of each face a cuboid centered around the head and returns the maximal movement across the centers. If you wish to use individual thresholds instead, import Undefined from nipype.interfaces.base and set ….inputs.use_norm = Undefined

Examples

>>> ad = ArtifactDetect()
>>> ad.inputs.realigned_files = 'functional.nii'
>>> ad.inputs.realignment_parameters = 'functional.par'
>>> ad.inputs.parameter_source = 'FSL'
>>> ad.inputs.norm_threshold = 1
>>> ad.inputs.use_differences = [True, False]
>>> ad.inputs.zintensity_threshold = 3
>>> ad.run()  # doctest: +SKIP
mask_type : ‘spm_global’ or ‘file’ or ‘thresh’
Type of mask that should be used to mask the functional data. spm_global uses an spm_global like calculation to determine the brain mask. file specifies a brain mask file (should be an image file consisting of 0s and 1s). thresh specifies a threshold to use. By default all voxels are used,unless one of these mask types are defined.
norm_threshold : a float
Threshold to use to detect motion-related outliers when composite motion is being used. Mutually exclusive with inputs: rotation_threshold, translation_threshold.
parameter_source : ‘SPM’ or ‘FSL’ or ‘AFNI’ or ‘NiPy’ or ‘FSFAST’
Source of movement parameters.
realigned_files : a list of items which are a pathlike object or string representing an existing file
Names of realigned functional data files.
realignment_parameters : a list of items which are a pathlike object or string representing an existing file
Names of realignment parameters corresponding to the functional data files.
rotation_threshold : a float
Threshold (in radians) to use to detect rotation-related outliers. Mutually exclusive with inputs: norm_threshold.
translation_threshold : a float
Threshold (in mm) to use to detect translation-related outliers. Mutually exclusive with inputs: norm_threshold.
zintensity_threshold : a float
Intensity Z-threshold use to detection images that deviate from the mean.
bound_by_brainmask : a boolean
Use the brain mask to determine bounding boxfor composite norm (worksfor SPM and Nipy - currentlyinaccurate for FSL, AFNI. (Nipype default value: False)
global_threshold : a float
Use this threshold when mask type equal’s spm_global. (Nipype default value: 8.0)
intersect_mask : a boolean
Intersect the masks when computed from spm_global. (Nipype default value: True)
mask_file : a pathlike object or string representing an existing file
Mask file to be used if mask_type is ‘file’.
mask_threshold : a float
Mask threshold to be used if mask_type is ‘thresh’.
plot_type : ‘png’ or ‘svg’ or ‘eps’ or ‘pdf’
File type of the outlier plot. (Nipype default value: png)
save_plot : a boolean
Save plots containing outliers. (Nipype default value: True)
use_differences : a list of items which are a bool or None
Use differences between successive motion (first element) and intensity parameter (second element) estimates in order to determine outliers. (default is [True, False]). (Nipype default value: [True, False])
use_norm : a boolean
Uses a composite of the motion parameters in order to determine outliers. Requires inputs: norm_threshold. (Nipype default value: True)
displacement_files : a list of items which are a pathlike object or string representing a file
One image file for each functional run containing the voxel displacement timeseries.
intensity_files : a list of items which are a pathlike object or string representing an existing file
One file for each functional run containing the global intensity values determined from the brainmask.
mask_files : a list of items which are a pathlike object or string representing a file
One image file for each functional run containing the mask used for global signal calculation.
norm_files : a list of items which are a pathlike object or string representing a file
One file for each functional run containing the composite norm.
outlier_files : a list of items which are a pathlike object or string representing an existing file
One file for each functional run containing a list of 0-based indices corresponding to outlier volumes.
plot_files : a list of items which are a pathlike object or string representing a file
One image file for each functional run containing the detected outliers.
statistic_files : a list of items which are a pathlike object or string representing an existing file
One file for each functional run containing information about the different types of artifacts and if design info is provided then details of stimulus correlated motion and a listing or artifacts by event type.

StimulusCorrelation

Link to code

Bases: BaseInterface

Determines if stimuli are correlated with motion or intensity parameters.

Currently this class supports an SPM generated design matrix and requires intensity parameters. This implies that one must run ArtifactDetect and Level1Design prior to running this or provide an SPM.mat file and intensity parameters through some other means.

Examples

>>> sc = StimulusCorrelation()
>>> sc.inputs.realignment_parameters = 'functional.par'
>>> sc.inputs.intensity_values = 'functional.rms'
>>> sc.inputs.spm_mat_file = 'SPM.mat'
>>> sc.inputs.concatenated_design = False
>>> sc.run() # doctest: +SKIP
concatenated_design : a boolean
State if the design matrix contains concatenated sessions.
intensity_values : a list of items which are a pathlike object or string representing an existing file
Name of file containing intensity values.
realignment_parameters : a list of items which are a pathlike object or string representing an existing file
Names of realignment parameters corresponding to the functional data files.
spm_mat_file : a pathlike object or string representing an existing file
SPM mat file (use pre-estimate SPM.mat file).
stimcorr_files : a list of items which are a pathlike object or string representing an existing file
List of files containing correlation values.