AFNI program: afni_restproc.py

Output of -help


  ** As of Dec 18, 2012, afni_restproc.py is (essentially) no longer being
     supported (by its author, Rayus Kuplicki of the University of Tulsa).

     Consider using afni_proc.py (written by Rick Reynolds of the NIH).


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


  ** As of Dec 18, 2012, afni_restproc.py is (essentially) no longer being
     supported (by its author, Rayus Kuplicki of the University of Tulsa).

     Consider using afni_proc.py (written by Rick Reynolds of the NIH).
This page auto-generated on Tue Jul 16 20:42:25 EDT 2024