Generate Motion and Power Statistics

CPAC.generate_motion_statistics.motion_power_statistics(wf_name='gen_motion_stats')[source]

The main purpose of this workflow is to get various statistical measures from the movement/motion parameters obtained in functional preprocessing. These parameters (FD calculations) are also required to carry out scrubbing.

wf_name : workflow object
Workflow name
param_wf : workflow object
Workflow object containing various movement/motion and power parameters estimates.

Source

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 contianing 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

scrubbing_input.threshold : a float
    scrubbing threshold

scrubbing_input.remove_frames_before : an integer
    count of preceding frames to the offending time 
    frames to be removed (i.e.,those exceeding FD threshold)
    
scrubbing_input.remove_frames_after : an integer
    count of subsequent frames to the offending time
    frames to be removed (i.e., those exceeding FD threshold)

Workflow Outputs:

outputspec.FD_1D : 1D file
    mean Framewise Displacement (FD)
    
outputspec.frames_ex_1D : 1D file
    Number of frames that would be censored ("scrubbed")
    also removing the offending time frames (i.e., those exceeding the threshold), 
    the preceeding frame, and the two subsequent frames

outputspec.frames_in_1D : 1d file
    Number of frames left after removing for scrubbing

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

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

Order of commands:

  • Calculate Frame Wise 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 Frame wise Displacement FD as per jenkinson et al., 2002

  • Calculate Frames to exclude

    Remove all frames which are below the threshold

  • Calculate Frames to include

    Include all the frames which are above the threshold

  • 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
    
    NumFD >=threshold : Number of frames (time points) where movement (FD) exceeded threshold
    
    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
    
    PercentFD( > threshold) : Number of frames (time points) where movement (FD) exceeded threshold 
                              expressed as a percentage of the total number of frames (time points)
    
    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
    

High Level Workflow Graph:

workflows/../images/parameters.dot.png

Detailed Workflow Graph:

workflows/../images/parameters_detailed.dot.png
>>> import generate_motion_statistics
>>> wf = generate_motion_statistics.motion_power_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.subject_id = 'sub01'
>>> wf.inputs.inputspec.scan_id = 'rest_1'
>>> wf.inputs.scrubbing_input.threshold = 0.5
>>> wf.base_dir = './working_dir'
>>> wf.run()
>>> 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.subject_id = 'sub01'
>>> wf.inputs.inputspec.scan_id = 'rest_1'
>>> wf.inputs.scrubbing_input.threshold = 0.2
>>> wf.inputs.scrubbing_input.remove_frames_before = 1
>>> wf.inputs.scrubbing_input.remove_frames_after = 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) calculations (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]

@ Krsna May 2013 compute 1) Jenkinson FD from 3dvolreg’s *.affmat12.1D file from -1Dmatrix_save option

input: subject ID, rest_number, name of 6 parameter motion correction file (an output of 3dvolreg) output: FD_J.1D file Assumptions: 1) subject is available in BASE_DIR 2) 3dvolreg is already performed and the 1D motion parameter and 1D_matrix file file is present in sub?/rest_? called as —>’lfo_mc_affmat.1D’

CPAC.generate_motion_statistics.set_frames_ex(in_file, threshold, frames_before=1, frames_after=2)[source]

Method to calculate Number of frames that would be censored (“scrubbed”) by removing the offending time frames (i.e., those exceeding FD threshold), the preceding frame, and the two subsequent frames

in_file : a string
framewise displacement(FD) file path
threshold : a float
scrubbing threshold value set in configuration file
frames_before : an integer
number of frames preceding the offending time frame by default value is 1
frames_after : an integer
number of frames following the offending time frame by default value is 2
out_file : string
path to file containing offending time frames
CPAC.generate_motion_statistics.set_frames_in(in_file, threshold, exclude_list)[source]

Method to Calculate the frames that are left after censoring for scrubbing.

in_file : string
framewise displacement(FD) file path
threshold : float
scrubbing thereshold set in configuration file
exclude_list : string
path of file containing sensored timepoints
out_file : string
path of file containing remaining uncensored timepoints
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 contianing various motion parameters
CPAC.generate_motion_statistics.gen_power_parameters(subject_id, scan_id, FD_1D, FDJ_1D, DVARS, threshold=1.0)[source]

Method to generate Power parameters for scrubbing

subject_id : string
subject name or id
scan_id : string
scan name or id
FD_ID: string
framewise displacement(FD as per power et al., 2012) file path
FDJ_ID: 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
CPAC.generate_motion_statistics.fristons_twenty_four(wf_name='fristons_twenty_four')[source]

The main purpose of this workflow is to calculate 24 parameters including the 6 motion parameters of the current volume and the preceeding volume, plus each of these values squared.

wf_name : workflow object
Workflow name

wf : workflow object

Source

Workflow Inputs:

inputspec.movement_file : string
    path to the input movement file from motion correction

Workflow Outputs:

outputspec.movement_file : movement_file
    path to 1D file containing the friston 24 parameters

High Level Workflow Graph:

workflows/../images/fristons_twenty_four.dot.png

Detailed Workflow Graph:

workflows/../images/fristons_twenty_four_detailed.dot.png
>>> from CPAC.generate_motion_statistics import fristons_twenty_four
>>> wf = fristons_tewenty_four()
>>> wf.inputs.inputspec.movement_parameters = 'CPAC_outupts/sub01/func/movement_parameteres/rest_mc.1D'
>>> wf.run()
[1]Friston, K. J., Williams, S., Howard, R., Frackowiak, R. S., & Turner, R. (1996). Movement-related effects in fMRI time-series. Magnetic Resonance in Medicine, 35(3),346-355
CPAC.generate_motion_statistics.calc_friston_twenty_four(in_file)[source]

Method to calculate friston twenty four parameters

in_file: string
input movement parameters file from motion correction
new_file: string
output 1D file containing 24 parameter values