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()
Mandatory Inputs:

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

Optional Inputs:

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

Outputs:

  • 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()
Mandatory Inputs:

  • 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).

Outputs:

stimcorr_files (a list of items which are a pathlike object or string representing an existing file) – List of files containing correlation values.