AFNI program: @RetinoProc

Output of -help


   @RetinoProc is a script to process retinotpic FMRI data.

 It estimates visual field angles and visual field maps using AFNI's
 3dRetinoPhase, and SurfRetinMap 

The Options:
===========
+++ Latency estimation:
 -phase : Use phase of fundamental frequency to estimate latency (default)
 -delay : Use delay relative to reference time series to estimate latency
          You should be better off using the -delay option, especially in 
          noisy situations
          To graph the reference time series relative to which response
          latency is estimated you will need to run @RetinoProc command
          first. The reference time series are generated at run time.
          The reference time series are in ascii files called ECC.1D and
          POL.1D. You can easily plot them with 1dplot. You can also get
          the commands that generated them (using the program waver) from
          files called: ECC.WAVER.log and POL.WAVER.log.

+++ Stimulus, and Time Series Parameters:
 -TR TR: TR, in seconds, of retinotopic scans
 -period_ecc TECC: Period, in seconds, of eccentricity (rings) and
 -period_pol TPOL: polar angle (wedges) stimuli, respectively.
             The period is the duration the stimulus takes to complete
             a full cycle. In other terms, if you were to point at one
             part of the stimulus and follow that part with your finger, 
             the period is the duration it takes your finger to get back 
             to the starting position.
             The period is independent of the number
             of rings/wedges used. For most sane people, TECC
             and TPOL have the same value.
 -pre_ecc PREECC: PREECC and PREPOL are the durations, in sec, before the 
 -pre_pol PREPOL: each of the two stimuli began. The duration is relative
                  to the beginning of the retinotopic time series, 
                  after the pre-steadystate images have been removed.
 -on_ecc N_BLOCKS ON_ECC : Number of stimulation blocks in both directions
 -on_pol N_BLOCKS ON_POL : followed by the duration of stimulation in sec.
                           per visual location.
 -var_on_ecc N_BLOCKS MIN_ON_ECC MAX_ON_ECC STEP_ON_ECC: Use multiple 
 -var_on_pol N_BLOCKS MIN_ON_POL MAX_ON_POL STEP_ON_POL: on durations 
                           and create multiple reference time series
                           for 3dRetinoPhase. See -multi_ref_ts option
                           in 3dRetinoPhase. Leave -var_ options alone
                           If you don't know what you're doing with it.
           All ON_ values are in seconds. STEP_* must be multiple of TR.

           Options -*on* are only useful if you use -delay.

 -nwedges NWED: Number of wedges in polar stimulus, and number of rings.
 -nrings NRING: in eccentricity stimulus.

 -fwhm_pol FWPOL: Target smoothness, in mm, for the polar and for the 
 -fwhm_ecc FWECC: eccentricity stimuli. 
                  Note that the script outputs results for both smoothed
                  and unsmoothed time series.

 -ignore IGN: Ignore IGN volumes from the beginning of each time series.
              When IGN is not 0, make sure that PREECC and PREPOL values
              represents the durations AFTER IGN volumes are taken out.
              This option is useless if you input surface-based 
              time series such as with option -lh_ccw
 -no_tshift:  Do not correct for slice timing. Assume it has been done.
              This option is useless if you input surface-based 
              time series such as with option -lh_ccw

+++ Volumetric input:
    Time series datasets
 -ccw CCW_1 CCW_2 ...: Specify the retinotopic time series for each of the
 -clw CLW_1 CLW_2 ...: four stimulus types. You can have multiple runs of
 -exp EXP_1 EXP_2 ...: each type. 
 -con CON_1 CON_2 ...: 

    Reference and Anatomical Volumes
 -epi_ref EpiRef: Specify a volume from the EPI time series to which all
                EPI volumes are aligned. 
                Default is the 4th sub-brick of the first epi time series
                on the command line.
 -epi_anat_ref EpiAnatRef: Specify a volume from the EPI time series that
                is better suited for aligning the T1 to it than EpiRef 
                might be. EpiAnatRef is usually a pre-steadystate volume
                which still shows anatomical contrast. This volume is
                first registered to EpiRef, then its registered version
                is used as a targe for registering AVol. If not set, 
                EpiAnatRef is set to be EpiRef.
 -noVR: Skip time series volume registration step. There will be no
                regression of motion estimates with this option
 -no_volreg: Same as -noVR
 -anat_vol AVol: T1 volume acquired during the same session as the
                 retinotopic scans. This volume is assumed to need
                 registration to EpiRef volume. The registration
                 is carried out automatically by the script, producing
                 a dataset we will call AVol@Epi.
 -anat_vol@epi AVol@Epi: Instead of letting the script align AVol
                 to your EpiRef, you can supply AVol@Epi directly
                 and skip the registration. Of course, you should 
                 be sure that AVol@Epi is indeed aligned with  EpiRef
 -surf_vol SVol: SVol is the Surface Volume for the cortical surfaces.
                 SVol is created when you first run @SUMA_Make_Spec_*
                 scripts. This volume is eventually aligned to AVol@Epi
                 with @SUMA_AlignToExperiment in order to create SVol@Epi
 -surf_vol@epi SVol@Epi: SVol that has been aligned to the experiment's
                 EPI data. If you use this option, you would be providing
                 the output of @SUMA_AlignToExperiment step mentioned 
                 above, allowing the script to skip running it.
                 To be sure you have the right volume, you should be sure
                 the surfaces align with the EPI data.
         Check for this with AFNI and SUMA using:
         suma -spec SPL -sv SVol@Epi & ; afni -niml &
   Note this option used to be called -surf_vol_alndepi

+++ Volume --> Surface options
    Maps by gray matter intersection:
   -gm : Map voxels that intersect gray matter as defined by the bounding
         smoothed white matter and pial surfaces. (default)

    Maps by single surface intersections:
   -wm : Map voxels that intersect the smoothed white matter surface only
         This seems to give cleaner maps, perhaps by being less encumbered
         by pial voxels that may have aliased sampling.
   -pial: Map voxels that intersect the pial surface only
   -midlayer: Map voxels that intersect the surface lying midway between 
              smoothed white matter and pial surfaces
   -layer FRAC: Map voxels that intersect the surface that is a fraction 
                FRAC of the cortical thickness away from the smoothed 
                white matter surface.
            In other terms:
                -wm       ==  -layer 0.0
                -pial     ==  -layer 1.0
                -midlayer ==  -layer 0.5

+++ Surface-based input: 
    Surfaces:
 -spec_left  SPL: SPL, and SPR are the spec files for the left and
 -spec_right SPR: right hemispheres, respectively.

    Time series datasets: For use when time series have already been 
                          mapped onto the surface.
 -lh_ccw CCW_1 CCW_2 ...: Specify the datasets containing retinotopic time
 -lh_clw CLW_1 CLW_2 ...: series that have already been mapped to the 
 -lh_exp EXP_1 EXP_2 ...: surface for each of the four stimulus types. 
 -lh_con CON_1 CON_2 ...: You can have multiple runs of each type. 
                          The script assumes that nuisance parameters 
                          have already been regressed out of these time
                          series.
    For the right hemisphere, replace -lh_ in the option names with -rh_
    It makes no sense to use these options along with -ccw, -clw, -exp, 
    or -con.

+++ Misc Parameters:
 -dorts ORT1D: Detrend time series using columns in ORT1D file
               The length of the time series in ORT1D should match
               that of the time series being fed to 3dDetrend
               Also, the this option applies to all the time series
               being processed so that assumes they all have the same
               lengths.
   Alternately, you can specify a separate ORT file for each dataset on
   the command line with:
 -ccw_orts CCW_1_ORT.1D CCW_2_ORT.1D ...: These options should parallel
 -clw_orts CLW_1_ORT.1D CLW_2_ORT.1D ...: -ccw, -clw, -exp, -con options
 -exp_orts EXP_1_ORT.1D EXP_2_ORT.1D ...: from above. 
 -con_orts CON_1_ORT.1D CON_2_ORT.1D ...: 
       You don't have to specify all or none of *_orts options.
       However, any *_orts option should have as many ORT files
       as its equivalent time series option.
       For example, if you used:
          -ccw       CCW1.nii CCW2.nii CCW3.nii
       to specify orts for these three datasets you need:
          -ccw_orts   ORT_CCW1.1D ORT_CCW2.1D ORT_CCW3.1D
       If for some reason you don't need orts for CCW2.nii, 
       use the string NONE to indicate that:
           -ccw_orts   ORT_CCW1.1D NONE ORT_CCW3.1D

 -sid SID: SID is a flag identifying the subject
 -out_dir DIR: Directory where processing results are to be stored
 -echo: Turn on the command echoing to help with debugging script failure
 -echo_edu: Turn on command echoing for certain programs only 
            as opposed to the shell's echoing
 -A2E_opts 'A2E_OPTS': Pass options A2E_OPTS to @SUMA_AlignToExperiment
                       You might use for example,
                       -A2E_opts '-strip_skull surf_anat' since SVol
                       usually has a skull, but AVol@Epi does not.
                       This could help with the alignment in certain
                       difficult cases
           For details on these options see @SUMA_AlignToExperiment -help
 -AEA_opts 'AEA_OPTS': Pass options AEA_OPTS to align_epi_anat.py, which 
                       is the tool used to align T1 anat to EPI.
                       For example if 3dSkullStrip is failing to 
                       strip the epi and you can add:
                       -AEA_opts '-epi_strip 3dAutomask' 
                       or perhaps:
                       -AEA_opts '-epi_strip 3dAutomask -partial_coverage'
           For details on these options see align_epi_anat.py -help
 -fetch_demo: Get the demo archive, do not install it. 
              (see Sample Data below)
 -install_demo: Get it, install it, and start processing the 1st example

The process:
============
   The full process consists of the following steps:
   - Copy input data in the results directory
   - Time shift and register volumetric epi data to EpiRef
   - Align EpiAnatRef to EpiRef to produce a NEW EpiAnatRef
   - Align AVol to (new) EpiAnatRef to produce AVol@Epi
   - Align SVol to AVol@Epi to produce SVol@Epi
   - Detrend components of no interest from time series volumes
   - Map time series to Surfaces
   - Smooth time series on the surfaces
   - Run 3dRetinoPhase on time series to produce field angle dataset
   - Run SurfRetinoMap on field angle data to produce visual field ratio
     datasets.
   - Create a script to show the results with little pain.
     The script is named @ShowResult and is stored in DIR/ 

Sample Data:
============
You can download a test dataset, generously contributed by Peter J. Kohler
 and Sergey V. Fogelson from:
       afni.nimh.nih.gov/pub/dist/tgz/AfniRetinoDemo.tgz
A README file in the archive will point you to sample scripts that 
illustrate the usage of @RetinoProc.

You can also use -fetch_demo to have this script get it for you.

References:
===========
   [1] RW Cox. AFNI: Software for analysis and visualization of functional
                     magnetic resonance neuroimages.  
                     Computers and Biomedical Research, 29: 162-173, 1996.
   [2] Saad Z.S., et al.  SUMA: An Interface For Surface-Based Intra- And
                      Inter-Subject Analysis With AFNI.
     Proc. 2004 IEEE International Symposium on Biomed. Imaging, 1510-1513
   [3] Saad, Z.S., et al. Analysis and use of FMRI response delays. 
         Hum Brain Mapp, 2001. 13(2): p. 74-93.
   [4] Saad, Z.S., et al., Estimation of FMRI Response Delays.
         Neuroimage, 2003. 18(2): p. 494-504.
   [5] Warnking et al. FMRI Retinotopic Mapping - Step by Step.
         Neuroimage 17, (2002)

Acknowledgments:
================
   Peter J. Kohler, and Sergey V. Fogelson: for feedback and sample data
   Michael Beauchamp: for a motivating script and webpage on retintopy
   Ikuko Mukai, Masaki Fukunaga, and Li-Wei Kuo: for difficult data and
                                    making the case for a -delay option
   Jonathan Polimeni: for retinotopy trade secrets

Kvetching:
============
Questions and Comments are best posted to AFNI's message board:
   https://discuss.afni.nimh.nih.gov

      Ziad S. Saad      Aug. 2010 
This page auto-generated on Thu Apr 18 14:47:00 EDT 2024