AFNI program: afni_restproc.py

Output of -help


afni_restproc.py 

This script takes care of preprocessing commonly done prior to resting state
analyses. The process is similar to ANATICOR and RETROICOR and consists of 
removing a number of regressors of noninterest. Some regressors need to be
computed prior to running this script, others do not. These regressors include
all or a subset of (with requirements in parentheses):

 motion parameters (-align on, default)
 local or global WM signal (supply appropriate mask or segmentation file)
 average ventricle signal (supply appropriate mask or segmentation file)
 average whole brain signal (-includebrain)
 RVT signal (compute first using RetroTS.m)
 arbitrary ROI average regressors (supply masks)
 other arbitrary regressors supplied by the user (compute first)

Additionally, this script takes care of alignment, registration, and slice
timing correction via align_epi_anat.py.  It will also talairach the data if 
desired-either before or after processing, your choice. Additionally, this 
script implements two censoring methods.  One is based on outliers and the 
other is identical to the method used by Power et al. (Neuroimage 2012)


Required Options:
 -anat aa :aa is the high resolution anatomy file
 -epi ee  :ee is the epi timeseries to process
 
Optional Options:

 Informational Options:
  -help  :Display this help message
  -changelog :Display a log of changes to this script

 Output Options:
  -prefix p :Prepend p to each of the final output files.  
    Default is rest_proc.
  -dest d  :Put the results in directory d. Default is to
    match p.
  -tsnr  :Compute the tSNR of the EPI as described below.
  -snr n c :Compute the SNR of the EPI. n should be a scan
    collected with the RF turned off. This will look
    like static on an old TV and is used to estimate
    the variance of the noise inherent in the
    system. c should be the number of channels in 
    the coil you used and will determine a
    correction factor.
  -corrmap :Run 3dTcorrMap on the clean data.
  -corrmapt t :Use t as the threshold when computing average 
    correlation strengths. Default is 0.3. The idea
    here is that you may be interested in the
    average correlation between each voxel and all
    other voxels it is connected to, but below
    a certain threshold two voxels could be
    considered disconnected, so discard those weak
    correlations. Regardless of what t is, mean
    correlations without thresholding are also 
    stored.
  -script sc :Write all commands to a script named sc. This
    script can be modified and run later, similar
    to the output from afni_proc.py

 Alignment Options:
  -tlrc  :Do the preprocessing in talairach space.  
    Default is to stay in orig space.
  -tlrclast :Do all preprocessing in orig space, but then 
    talairach the results. Pick either -tlrc or 
    -tlrclast (or neither).
  -episize mm :Cubic voxel size of all datasets (other than 
    the anatomy) after transforming them to 
    talairach space. Default is 2. This only works
    with -tlrclast or -tlrc.
  -align [on]/off :Do the Alignment etc. step. Turn this option 
    off if all of the datasets are already aligned.
  -alignbase b :Align both the epi and anat datasets to b.  
    b should be an epi dataset and the first image
    will be used for alignment. This option makes 
    sense if you have several epi runs and you want
    all of them aligned to the same base.  Also, 
    this option only makes sense when not using 
    -tlrc or -epi2anat (-tlrclast is ok).
  -epi2anat :Align epi to anat instead of anat to epi.  
    This only makes sense when not using -tlrc.
  -uniformize :Uniformize anat before alignment.  Sometimes 
    This helps with skull stripping problems.
  -anat_has_skull [yes]/no
    :Set this option to no if the anatomy has
    already been skull stripped (useful when default
    skull stripping doesn't work right).

 Regressor Options:
  -aseg a  :a is the aseg segmentation file from 
    freesurfer. It should be aligned with the
    anatomy supplied as -anat and can be in .mgz,
    .nii, or .BRIK format.
  -wmsize w :Radius (in mm) of the sphere to use when
    computing the local white matter regressors.
    Default is 15mm
  -globalwm :Use the global wm average as a single 
    regressor instead of computing local wm 
    regressors.
  -venterode v :Number of nonmask neighbors required to cause 
    erosion in the ventricles. Default is 2
  -wmerode we :Number of nonmask neighbors required to cause 
    erosion in the WM mask. Default is 1.
  -rvt r  :r is the RVT file produced by RetroTS.m
  -includebrain :Include the whole brain average regressor.
  -dreg  :Add the derivatives of all regressors as 
    regressors.
  -regressor re :Use re as a regressor. re will be processed 
    in the same way the other regressors are
    (detrended, catenated). If you do alignment 
    and registration outside of this script, it may
    be a good idea to provide the motion parameters
    as a regressor. re can be either a 3d+t volume
    (specifying a different regressor for each
    voxel) or a .1D file (specifying a single global
    regressor).
  -globalregmask g:Use the average signal extracted from the mask
    g as a global regressor of noninterest. This 
    will produce one regressor used for all voxels.
  -localregmask rm rr
    :Use the local average signal extracted from
    rm as a regressor of noninterest. This will 
    produce a different regressor for each voxel.
    rm should be a mask defining the ROI to use
    and rr is the radius in mm to use when computing
    local average signals.
    -regressor, -globalregmask and -localregmask
    can be used multiple times to supply an
    arbitrary number of regressors.

 Censoring Options:
  -outcensor :Censor timepoints based on their number of
    outliers and head motion magnitude. Censored
    time points are cut out.
  -fraclimit f :When using -outcensor, fraction of voxels
    identified as outliers needed to censor a time
    point. Default is 0.05.
  -motlimit m :When using -outcensor, limit on rms motion to
    censor a point. Default is 0.3.
  -dvarscensor  :Create a censor file based on FD (framewise
    displacement) and DVARS as from Power et. al, 
    Neuroimage 2012. 
  -fdlimit ff :Set the FD limit to be ff
  -dvarslimit dd :Set the DVARS limit to be dd
  -censorleft s  :Censor s steps to the left of bad time points.
    Default is 1.
  -censorright ss :Censor ss steps to the right of bad time 
    points. Default is 2.
  -censorunion :Censor the union of fraclimit and motlimit or
    FD and DVARS, instead of the intersection.
  -keepuncensored :Keep a copy of the uncensored timeseries. It
    will be called 
    [prefix].cleanEPI.uncensored+[view]

 Normalization Options:
  -localnorm :Normalize based on voxelwise mean
  -globalnorm :Normalize based on global mean 
  -modenorm :Normalize based on global mode using 100 bins
  -normval n :Scale the selected attribute to be n

 Smoothing Options:
  -smooth [on]/off:Smooth the clean timeseries data.
  -smoothrad s :FWHM size of smoothing to apply after cleaning
    the data.  Default is 4mm. Smoothing is done
    using a grey/nongrey matter mask by default.
  -smoothtogether :Smooth everything inside a brain mask together,
    rather than smoothing the grey/nongrey matter 
    separately.
  -smoothfirst :Smooth the data before doing regression,
    instead of after.

 Misc. Processing Options:
  -despike[on]/off:Despike the timeseries as the fist 
    preprocessing step.
  -trcut t :Number of TRs to throw away.  Default is 4.
  -polort p :Polynomial to detrend from the regressors and 
    the timeseries.  Similar to 3dDeconvolve  
    -polort A, default is floor(1 + TR*nVOLS / 150).
  -bandpass  :Do bandpass filtering with LHz < f < HHz. 
    Default is 0.009 and 0.08.
  -setbands L H :Set L and H for bandpass filtering
  -bpassregs :Also bandpass filter the regressors.
  -exec [on]/off :Execute the commands. Turn this off and use 
    -script to get things setup without running 
    anything.

 Other Options:
  -apply_censor e c p
    :This option is used to apply a censor file to
    remove timepoints from a timeseries. If it is
    given, this is the only option that will be
    processed. e is the timeseries to censor. c is
    a 1D file consisting of a single column of
    0's and 1's which must be the same length as e.
    Time points with 1's in c will be kept, 0's will
    be discarded. p is the prefix to use for the
    output timeseries.

The following steps should be done before running this script:
 Create anatomical regressor masks:
  If you want to remove anatomical regressors or noninterest,
  the average ventricle signal, for example, you will need to 
  provide masks used to extract these signals. This can be done 
  in two different ways. Either supply the aseg file produced by
  freesurfer, which is used to extract the ventricle and white
  matter ROIs, or supply your own arbitrary masks with the 
  -globalregmask or -localregmask options.
 Align the segmentation file with the experimental anatomy:
  If given, The aseg file from freesurfer (it can be in mgz, nii,
  or BRIK format) is assumed to be in alignment with the 
  experimental anatomy.  The aseg and anat files will already be
  aligned if the anatomy is the one used by freesurfer.  If it is
  not, you may need to use something like @SUMA_AlignToExperiment.
 Create the RVT file:
  This is done by processing the experiment's cardiac and 
  respiratory files using RetroTS.m, available in the AFNI Matlab
  library. While it is probably beneficial to remove the
  estimated cardiac and respiratory signals, this step is not
  necessary and this script will run fine without them.

Processing is done in the following steps:
 Copy Files:
  The output directory (specified by -dest) is created and input
  files are copied to dest/tmp
 Despike:
  This step is done first, if at all, so that spikes are not
  'smeared around' by registration and slice timing correction
 Alignment etc.:
  This step aligns the epi and anat datasets while also taking 
  care of slice timing correction and the talairach 
  transformation, if requested. These steps are combined using
  align_epi_anat.py to minimize the number of interpolations 
  required. If processing is done in +orig space, the anat is
  aligned to the epi by default. Using -epi2anat will cause the
  epi to be aligned to the anat. The appropriate transformation
  is also applied to the aseg file and any masks provided by 
  -localregmask and -globalregmask to keep them aligned with the 
  anat.
 tcat:
  This is where the first few time points are thrown out.  This 
  step is delayed until after alignment so that the first high
  contrast epi image can be used in the alignment process.
 tSNR:
  At this stage in processing the tSNR of the EPI data is 
  computed if requested.  It is taken to be  
  mean(pEPI) / stdev(det(pEPI)) where pEPI is the processed EPI 
  (despiked, aligned, tshifted, catenated) and det represents 
  detrending with polynomial order polort.
 SNR:
  If you have collected a scan with the RF turned off (used to
  estimate the varience of the noise) the SNR can be computed
  for each voxel. It is taken to be S/(sigma*corr) where S is 
  the signal in the first frame of the epi timeseries, sigma is
  the standard deviation of the values in the noise scan, and 
  corr is a correction factor based on the number of channels in
  the coil. After computing the SNR of the original EPI volume,
  it is transformed to be aligned with and have the same voxel
  size as the final EPI. Correction factors are:
         corr1 = 1.5263997
         corr8 = 1.4257312
         corr16 = 1.4198559
         corr32 = 1.4170053
 Normalize EPI:
  If a method of normalization is chosen, it is applied here.
  Normalization is done to scale the selected attribute to be
  -normval inside a brain mask. Specifically:
  -globalnorm computes the global mean signal across time and
  space in the brain and scales accordingly. 
  normval * (voxel intensity)/(global mean)
  -modenorm computes the global mode intensity across time and
  space in the brain and scales accordingly.
  normval * (voxel intensity)/(global mode)
  -localnorm computes the temporal average for each voxel and
  scales accordingly.
  normval * (voxel intensity)/(voxel mean)
 Prep WM Mask:
  The WM mask is taken from the aseg file from freesurfer.  It is
  first taken to be all voxels with labels: 2,7,16,41,46,251,252,
  253,254,255. This mask is resampled to match the resolution of
  the epi dataset. After resampling, the mask is eroded so that
  it is less likely to contain any grey matter. By default, 
  typical erosion is done which removes voxels which have a 
  single non-mask neighbor from the mask.
 Prep Ventricle Mask:
  The ventricle mask is taken from the aseg file using labels 4 
  and 43. This mask is resampled to match the epi and then eroded.
  Erosion of the ventricle mask is by default less conservative
  than typical erosion. Voxels require two neighbors to be 
  non-mask voxels in order to be eroded. This is done because a 
  large number of subjects end up without any voxels in the 
  ventricle mask using standard erosion and a 64x64 matrix. If
  your data are higher resolution, you may want to use -venterode
  1. It is a good idea to check both the WM and ventricle masks 
  to make sure they look good.
 Prep Blurring Mask:
  The last step (after regression) is to apply gaussian smoothing.
  By default (if -aseg was specified), this smoothing is done in
  the grey and nongrey matter seperately via 3dBlurInMask. The
  blurring mask is created so that grey matter voxels are labeled 1
  and nongrey voxels (inside the brain) are labeld 2. The labeling
  is simply (automask + WM mask + Vent mask). If -aseg was not
  specified, or -smoothtogether was given, the smoothing is done
  using the whole brain as one region.
 Smoothing:
  If -smoothfirst was selected, this is where smoothing takes
  place. It is done as described below.
 Extract Regressors from masks:
  Regressor timeseries are extracted from the WM and ventricle
  masks as well as any masks supplied by the user with the
  -globalregmask and -localregmask options. A single regressor
  timeseries is computed as the average value for each supplied
  global masks and the ventricle mask. For the WM mask and any
  masks supplied with -localregmask, different regressors are
  computed for each voxel. For a single voxel, the regressor is
  defined as the average timeseries in voxels which are both
  within the supplied radius and included in the mask.
  -globalregmask and -localregmask are useful if you want to use
  software other than Freesurfer for the segmentation step. For
  example, using whatever method you like, you can create a
  ventricle mask and supply it as a global mask. Likewise, you can
  create a whitematter mask and supply it as a local regressor.
  Multiple local and global masks can be supplied.
 Differentiate Regressors:
  If desired, the temporal derivatives of each regressor are 
  computed and added to the list of regressors.
 Detrend Regressors:
  The polynomial of order -polort is removed from each of the
  regressors (RVT, WM, Vent, Motion). This is done so there are 
  no competing polynomial terms during the regression step.
 Bandpass Filtering:
  If bandpass filtering is selected, it is applied to the EPI 
  data here after regression. This is also where the regressors 
  are bandpass filtered if -bpassregs was selected.
 Regression:
  The regressors of noninterest (RVT,WM,Vent,Motion,other
  arbitrary regressors) are taken out of the epi timeseries using
  3dTfitter, which also removes the polynomial selected using
  -polort.
 Create Censor File:
  If a censoring method was chosen, the offending time points are
  identified here. 
  -outcensor:
   Make a temporal mask marking frames with more outliers
   than the threshold specified by -fraclimit. 
   Make a temporal mask marking frames with more RMS
   motion than specified by -motlimit.
   Mark frames -censorleft and -censorright steps to the 
   left and right of time points flagged in the two masks.
   Take the intersection of the two masks created above
   (or the union, if -censorunion was specified)
  -dvarscensor:
   Make a temporal mask marking frames with FD greater
   than the threshold specified by -fdlimit.
   Make a temporal mask marking frames with DVARS greater
   than the threshold specified by -dvarslimit.
   Mark frames -censorleft and -censorright steps to the 
   left and right of time points flagged in the two masks.
   Take the intersection of the two masks created above
   (or the union, if -censorunion was specified)
 Smoothing:
  By default, 3dBlurInMask is used to smooth the timeseries in 
  the grey and nongrey matter separately. Grey matter voxels are
  likely the interesting ones, but it can't hurt to apply the 
  same process to nongrey voxels to see what they look like. The 
  -smoothtogether flag can be used to apply uniform smoothing to
  all voxels in the brain instead. -smooth off skips this step.
 Censoring:
  If a censoring method was chosen, the censored time points are
  removed here.
 TcorrMap:
  At this point, the data have been preprocessed to remove
  uninteresting signals. It is now appropriate to do resting 
  state functional connectivity analysis on the clean data. One
  thing to examine is the result of running 3dTcorrMap. For a 
  full description of what this does, see the help from
  3dTcorrMap. This script uses it as follows:
   3dTcorrMap -input cleanEPI -mask automask -polort -1 
    -mean prefix.MeanCorr -Hist 400 prefix.CorHist 
    -Cexpr 'step(r-t)*r' prefix.MeanCorrGT
  where t can be specified using -corrmapt and is 0.3 by default. 

Things to check after running this script:
 Alignment:
  Make sure the various mask datasets are in good alignment with
  the anatomical dataset.
 Mask Coverage:
  Make sure the ventricle and white matter masks cover what you
  think are appropriate voxels.



Example Usage:


 #Basic usage:
 #Remove RVT, motion parameters, WM and ventricle signals from 
 #epi+orig
 #Store the results in a directory named preproc
 #Prefix each result file with subjX
 #Processing is done in orig space
 afni_restproc.py -anat mprage+orig. \
  -epi epi+orig. \
  -rvt RVT.slibase.1D \
  -aseg aseg.mgz \
  -dest preproc \
  -prefix subjX 

 #Produce a tsnr map and results from 3dTcorrMap using a threshold of .15
 #Write a script called proc.tcsh but don't execute it yet
 #This script can be modified and executed at your leisure
 afni_restproc.py -anat mprage+orig. \
  -epi epi+orig. \
  -rvt RVT.slibase.1D \
  -aseg aseg.mgz \
  -dest preproc \
  -prefix subjX \
  -corrmap \
  -corrmapt .15 \
  -tsnr \
  -script proc.tcsh \
  -exec off

 #Alignment and talairaching were done already, so skip those steps
 #Use the provided motion parameter file as a regressor
 afni_restproc.py \
  -epi epi+tlrc \
  -rvt RVT.slibase.1D \
  -anat mprage+tlrc \
  -aseg aseg+tlrc \
  -regressor epi_tsh_vr_motion.1D \
  -dest prealigned \
  -prefix subjX \
  -align off 

 #Do processing like it was done in Power et al. Neuroimage 2012
 afni_restproc.py \
  -despike off \
  -aseg aseg.mgz \
  -anat mprage+orig \
  -epi rest+orig \
  -script power_method.tcsh \
  -dest power_method_subjx \
  -prefix pm \
  -dvarscensor \
  -tlrc \
  -episize 3 \
  -dreg \
  -smoothfirst \
  -smoothrad 6 \
  -smoothtogether \
  -bandpass \
  -includebrain \
  -polort 0 \
  -globalwm \
  -censorleft 1 \
  -censorright 2 \
  -fdlimit 0.5 \
  -dvarslimit 5 \
  -modenorm 

 #Apply a censor file to a timeseries.  This will output a file called
 #epi.censored+orig that has TRs cut out wherever censor.1D is 0.
 afni_restproc.py \
  -apply_censor \
  epi+orig \
  censor.1D \
  epi.censored

Original version by Rayus Kuplicki.
University of Tulsa
Laureate Institute for Brain Research
Report problems or feature requests to rkuplicki@laureateinstitute.org.
12-18-12
This page auto-generated on Thu May 23 09:54:27 EDT 2013