BRAMILA tools

After recent discussions in the literature Power et al. (Neuroimage, 2012), Satterthwaite et al. (Neuroimage, 2013), Yan et al. (Neuroimage, 2013), Power et al. (Neuroimage, 2014) reviewers have been asking more and more regarding quality control for head motion during fMRI data collection. In Power's papers, the authors propose two indices of quality control:

1. Framewise Displacement: a time series of the sum of the absolute values of the derivatives of the six realignment parameters.
2. DVARS: a time series of the RMS of the derivatives of the timecourses of all within-brain voxels for each volume

Power et al. recommend that framewise displacement should not go above 0.5mm and DVARS should not go above 0.5%. However, one has to note that the final DVARS values depend a lot on the mask/rois given, I recommend using it only for those regions that are going to be studied with functional connectivity. Furthermore, the DVARS threshold suggested by Power et al. is based on resting state. Task data will require a different threshold. I will run some rest vs task DVARS comparisons and post the results here.

MATLAB code:

    bramila_framewiseDisplacement.m (02.10.2014)
    bramila_detrend.m (28.07.2014, used by bramila_framewiseDisplacement)
    bramila_dvars.m (09.03.2014)
    bramila_bold2perc.m (10.01.2014)

From the functions' help:

% BRAMILA_FRAMEWISEDISPLACEMENT - Computes the framewise displacement
% metric as described in 
% Power et al. (2012) doi:10.1016/j.neuroimage.2011.10.018 and also 
% Power et al. (2014) doi:10.1016/j.neuroimage.2013.08.048
%   - Usage:
%   fwd = bramila_framewiseDisplacement(cfg)
%   - Input:
%   cfg is a struct with following parameters
%       cfg.motionparam = the 6 time series of motion parameters (time in 1st dimension)
%       cfg.prepro_suite = 'fsl-fs', 'spm' (default fsl-fs, fs = freesurfer)
%       cfg.radius = radius of sphere in mm to convert degrees to motion,
%       default = 50 as in Power et al 2014
%   - Output:
%       fwd = framewise displacement timeseries
%   - Notes:
%   Need to check that spm is indeed different, see end of Yan 2013 10.1016/j.neuroimage.2013.03.004 


% BRAMILA_DVARS - Computes Derivative VARiance across voxels as defined in
% Power et al. (2012) doi:10.1016/j.neuroimage.2011.10.018
%   - Usage:
%   dvars=bramila_dvars(cfg) Returns a time series 'dvars' with a value of
%   RMS for each time point. First time point is set to 0.
%   - Input:
%   cfg is a struct with following parameters
%       Possible input formats
%       cfg.nii = 'path/to/a/nifti/file' - insert the full path to a nifti
%           file with 4D fMRI data
%       cfg.vol = vol - a matlab 4D volume with fMRI data, time on the
%           4th dimension
%       cfg.ts = ts - a two dimensional vector of time series, time on the
%           1st dimension
%       cfg.plot = 0 or 1 - set to 1 if you want to output a plot like in
%           Power et al. (2014) doi:10.1016/j.neuroimage.2013.08.048 (defult 0)
%       cfg.mask = a 3D matlab volume mask of voxels to consider for RMS computation
%           (the parameter is ignored if cfg.ts is specified)
%   - Note:
%   if more than one input format is specified matlab will give
%   priority to cfg.ts > cfg.vol > cfg.nii


% BRAMILA_BOLD2PERC - Converts a time series with mean into a time series of percentage changes.
%   - Usage:
%   ts_perc = bramila_bold2perc(ts) ts is a matrix NxM where N is the
%   number of time points. Values returned are in percentages
%   - Notes:
%   If the mean is zero, then the absolute maximum is used.
%
%   The formula used follows the SPM convention, i.e. we first normalize the
%   time series so that they have 100 as mean value.