Generate Motion and Power Statistics

CPAC.generate_motion_statistics.motion_power_statistics(name='motion_stats')[source]
The main purpose of this workflow is to get various statistical measures
from the movement/motion parameters obtained in functional preprocessing.
Parameters:name (str) – Name of the workflow, defaults to ‘motion_stats’
Returns:Nuisance workflow.
Return type:nipype.pipeline.engine.Workflow

Workflow Inputs:

inputspec.subject_id : string
    Subject name or id

inputspec.scan_id : string
    Functional Scan id or name

inputspec.motion_correct : string (func/rest file or a list of func/rest nifti file)
    Path to motion corrected functional data

inputspec.mask : string (nifti file)
    Path to field containing brain-only mask for the functional data

inputspec.max_displacement : string (Mat file)
    maximum displacement (in mm) vector for brain voxels in each volume.
    This file is obtained in functional preprocessing step

inputspec.movement_parameters : string (Mat file)
    1D file containing six movement/motion parameters(3 Translation, 3 Rotations)
    in different columns (roll pitch yaw dS  dL  dP), obtained in functional preprocessing step

Workflow Outputs:

outputspec.FDP_1D : 1D file
    mean Framewise Displacement (FD)

outputspec.power_params : txt file
    Text file containing various power parameters for scrubbing

outputspec.motion_params : txt file
    Text file containing various movement parameters

Order of commands:

  • Calculate Framewise Displacement FD as per power et al., 2012

    Differentiating head realignment parameters across frames yields a six dimensional timeseries that represents instantaneous head motion. Rotational displacements are converted from degrees to millimeters by calculating displacement on the surface of a sphere of radius 50 mm.[R5]

  • Calculate Framewise Displacement FD as per jenkinson et al., 2002

  • Calculate DVARS

    DVARS (D temporal derivative of timecourses, VARS referring to RMS variance over voxels) indexes the rate of change of BOLD signal across the entire brain at each frame of data.To calculate DVARS, the volumetric timeseries is differentiated (by backwards differences) and RMS signal change is calculated over the whole brain.DVARS is thus a measure of how much the intensity of a brain image changes in comparison to the previous timepoint (as opposed to the global signal, which is the average value of a brain image at a timepoint).[R5]

  • Calculate Power parameters:

    MeanFD : Mean (across time/frames) of the absolute values for Framewise Displacement (FD),
    computed as described in Power et al., Neuroimage, 2012)
    
    rootMeanSquareFD : Root mean square (RMS; across time/frames) of the absolute values for FD
    
    rmsFD : Root mean square (RMS; across time/frames) of the absolute values for FD
    
    FDquartile(top 1/4th FD) : Mean of the top 25% highest FD values
    
    MeanDVARS : Mean of voxel DVARS
    
  • Calculate Motion Parameters

    Following motion parameters are calculated:

    Subject
    Scan
    Mean Relative RMS Displacement
    Max Relative RMS Displacement
    Movements > threshold
    Mean Relative Mean Rotation
    Mean Relative Maxdisp
    Max Relative Maxdisp
    Max Abs Maxdisp
    Max Relative Roll
    Max Relative Pitch
    Max Relative Yaw
    Max Relative dS-I
    Max Relative dL-R
    Max Relative dP-A
    Mean Relative Roll
    Mean Relative Pitch
    Mean Relative Yaw
    Mean Relative dS-I
    Mean Relative dL-R
    Mean Relative dP-A
    Max Abs Roll
    Max Abs Pitch
    Max Abs Yaw
    Max Abs dS-I
    Max Abs dL-R
    Max Abs dP-A
    Mean Abs Roll
    Mean Abs Pitch
    Mean Abs Yaw
    Mean Abs dS-I
    Mean Abs dL-R
    Mean Abs dP-A
    

Error

Unable to execute python code at exec.py:31:

No command “dot” found on host 4b880de927b2. Please check that the corresponding package is installed.

High Level Workflow Graph:

workflows/../images/generated/motion_statistics.png

Detailed Workflow Graph:

workflows/../images/generated/motion_statistics_detailed.png
>>> import generate_motion_statistics
>>> wf = generate_motion_statistics.motion_power_statistics("generate_statistics")
>>> wf.inputs.inputspec.movement_parameters = 'CPAC_outupts/sub01/func/movement_parameteres/rest_mc.1D'
>>> wf.inputs.inputspec.max_displacement = 'CPAC_outputs/sub01/func/max_dispalcement/max_disp.1D'
>>> wf.inputs.inputspec.motion_correct = 'CPAC_outputs/sub01/func/motion_correct/rest_mc.nii.gz'
>>> wf.inputs.inputspec.mask = 'CPAC_outputs/sub01/func/func_mask/rest_mask.nii.gz'
>>> wf.inputs.inputspec.transformations = 'CPAC_outputs/sub01/func/coordinate_transformation/rest_mc.aff12.1D'
>>> wf.inputs.inputspec.subject_id = 'sub01'
>>> wf.inputs.inputspec.scan_id = 'rest_1'
>>> wf.base_dir = './working_dir'
>>> wf.run()
[1]Power, J. D., Barnes, K. A., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2012). Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. NeuroImage, 59(3), 2142-2154. doi:10.1016/j.neuroimage.2011.10.018
[2]Power, J. D., Barnes, K. A., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2012). Steps toward optimizing motion artifact removal in functional connectivity MRI; a reply to Carp. NeuroImage. doi:10.1016/j.neuroimage.2012.03.017
[3]Jenkinson, M., Bannister, P., Brady, M., Smith, S., 2002. Improved optimization for the robust and accurate linear registration and motion correction of brain images. Neuroimage 17, 825-841.
CPAC.generate_motion_statistics.calculate_FD_P(in_file)[source]

Method to calculate Framewise Displacement (FD) as per Power et al., 2012

in_file : string
movement parameters vector file path
out_file : string
Frame-wise displacement mat file path
CPAC.generate_motion_statistics.calculate_FD_J(in_file)[source]

Method to calculate framewise displacement as per Jenkinson et al. 2002

in_file : string
matrix transformations from volume alignment file path
out_file : string
Frame-wise displacement file path
CPAC.generate_motion_statistics.gen_motion_parameters(subject_id, scan_id, movement_parameters, max_displacement)[source]

Method to calculate all the movement parameters

subject_id : string
subject name or id
scan_id : string
scan name or id
max_displacement : string
path of file with maximum displacement (in mm) for brain voxels in each volume
movement_parameters : string
path of 1D file containing six movement/motion parameters(3 Translation, 3 Rotations) in different columns (roll pitch yaw dS dL dP)
out_file : string
path to csv file containing various motion parameters
CPAC.generate_motion_statistics.gen_power_parameters(subject_id, scan_id, fdp, fdj, dvars)[source]

Method to generate Power parameters for scrubbing

subject_id : string
subject name or id
scan_id : string
scan name or id
FDP_1D: string
framewise displacement(FD as per power et al., 2012) file path
FDJ_1D: string
framewise displacement(FD as per jenkinson et al., 2002) file path
threshold : float
scrubbing threshold set in the configuration by default the value is set to 1.0
DVARS : string
path to numpy file containing DVARS
out_file : string (csv file)
path to csv file containing all the pow parameters
CPAC.generate_motion_statistics.calculate_DVARS(rest, mask)[source]

Method to calculate DVARS as per power’s method

rest : string (nifti file)
path to motion correct functional data
mask : string (nifti file)
path to brain only mask for functional data
out_file : string (numpy mat file)
path to file containing array of DVARS calculation for each voxel