AFNI program: 3dGroupInCorr

Output of -help

Usage: 3dGroupInCorr [options]

* Also see
  http://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/instastuff.pdf

* This program operates as a server for AFNI or SUMA.  It reads in dataset
  collections that have been prepared by 3dSetupGroupInCorr, and then
  connects to the AFNI or SUMA GUI program (via TCP/IP).  Then it waits
  for a command to be sent from AFNI/SUMA before it actually does anything.

 (-: However,  the new [Feb 2011] '-batch' option,  described far below, :-)
 (-: lets you run 3dGroupInCorr by itself, without AFNI or SUMA, writing :-)
 (-: results to disk instead of transmitting them to the client program. :-)

* At the same time as you run 3dGroupInCorr, you also have to run the
  AFNI GUI program, with a command like 'afni -niml'.  3dGroupInCorr
  by itself will only do something when AFNI sends it a command, which
  you do by using the 'InstaCorr Set' button on the [A] image viewer
  right-click popup menu, after 3dGroupInCorr has connected to AFNI.

* When AFNI sends a seed voxel command, 3dGroupInCorr will extract
  that voxel times series from each input dataset, will compute the
  correlation map of each dataset with the corresponding seed time
  series, then will compute the voxel-wise collection of t-tests of
  that bunch of correlation maps, and return the resulting 3D volumes
  to AFNI for display.
 ++ A lot of computing can be required if there are a lot of datasets
    in the input collections.  3dGroupInCorr is carefully written to
    be fast.  For example, on a Mac Pro with 8 3GHz CPUs, running
    with 1.2 GBytes of data (100 datasets each with 69K voxels), each
    group correlation map takes about 0.3 seconds to calculate and
    transmit to AFNI -- this speed is why it's called 'Insta'.

* You must start AFNI with the '-niml' option to allow it to accept
  incoming TCP/IP socket connections.
 ++ Or you can press the 'NIML+PO' button in the GUI, if you forgot
    to type the AFNI command line correctly.
 ++ If you are running 3dGroupInCorr and AFNI on separate computers,
    you also have to setup 'host trusting' correctly -- for details,
    see the description of the '-ah' option, far below.

* In the AFNI 'A' controller, once 3dGroupInCorr is connected to AFNI,
  you don't have to switch to 'GrpInCorr' on the 'Cluster' menu to
  use the 'InstaCorr Set' controls -- unlike the individual subject
  InstaCorr, which requires setup inside AFNI.  For Group InstaCorr,
  the setup is already done in 3dSetupGroupInCorr.  The only reason
  for using the 'GrpInCorr' setup controls in AFNI is to change the
  value of the '-seedrad' option' radius interactively.

* More detailed outline of processing in 3dGroupInCorr:
 ++ For each 3D+time dataset in the input dataset collections:
   -- Extract the seed voxel time series (averaging locally per 'seedrad')
        [you could do this manually with 3dmaskave]
   -- Correlate it with all other voxel time series in the same dataset
        [you could do this manually with 3dDeconvolve or 3dfim]
   -- Result is one 3D correlation map per input dataset
 ++ Then carry out the t-test between/among these 3D correlation maps,
      possibly allowing for dataset-level covariates.
   -- Actually, between the arctanh() of these maps:
       cf. RA Fisher: http://en.wikipedia.org/Fisher_transformation
       [you could do the arctanh() conversion manually via 3dcalc;]
       [then do the t-tests manually with 3dttest++;  then convert]
       [the t-statistics to Z-scores using yet another 3dcalc run.]
   -- To be overly precise, if the correlation is larger than 0.999329,
       then the arctanh is clipped to 4.0, to avoid singularities.
       If you consider this to be a problem, please go away.
 ++ The dataset returned to AFNI converts the t-statistic maps
    to Z-scores, for various reasons of convenience.
   -- Conversion is done via the same mechanism used in program
        cdf -t2z fitt TSTAT DOF
   -- The individual correlation maps that were t-test-ed are discarded.
   -- Unless you use the new [Jan 2011] '-sendall' option :-)

* When 3dGroupInCorr starts up, it has to 'page fault' all the data
  into memory.  This can take several minutes, if it is reading (say)
  10 Gbytes of data from a slow disk.  After that, if your computer
  has enough RAM, then the program should run pretty quickly.
 ++ If your computer DOESN'T have enough RAM to hold all the data,
    then this program will be very slow -- buy more memory!
 ++ Note that the .data file(s) are mapped directly into memory (mmap),
    rather than being read with standard input methods.  This operation
    may not work well on network-mounted drives, in which case you
    will have to run 3dGroupInCorr on the same computer with the data
    files.  However, 3dGroupInCorr does NOT need to be run on the same
    computer as AFNI or SUMA: see the '-ah' option (far below).

* One reason this program is a server (rather than being built in
  to AFNI) is that it can be compiled to use OpenMP, which will let
  it make use of multiple CPU cores on the computer system.
 ++ However, this binary version is not compiled with OpenMP :-(
 ++ OpenMP is supported in gcc 4.2 and above (included on Mac OS X),
    and in some commercial C compilers (e.g., Sun's, Intel's).
 ++ If at all possible, use a version/compilation of 3dGroupInCorr
    with OpenMP; the speed difference is very appreciable!

==================================================================
                       COMMAND LINE OPTIONS
==================================================================

-----------------------*** Input Files ***------------------------

 -setA AAA.grpincorr.niml
   = Give the setup file (from 3dSetupGroupInCorr) that describes
     the first dataset collection:
  ++ This 'option' is MANDATORY (you have to input SOMETHING).
  ++ Of course, 'AAA' should be replaced with the correct name of
     your input dataset collection file!
  ++ 3dGroupInCorr can use byte-valued or short-valued data as
     produced by the '-byte' or '-short' options to 3dSetupGroupInCorr.
  ++ You can also put the '.data' filename here, or leave off the '.niml';
     the program will look for these cases and patch the filename as needed.

 -setB BBB.grpincorr.niml
   = Give the setup file that describes the second dataset collection:
  ++ This option IS optional.
  ++ If you use only -setA, then the program computes a one-sample t-test.
  ++ If you use also -setB, then the program computes a two-sample t-test.
    -- The exact form of the 2-sample t-test used is controlled by one of the
       three options described below (which are mutually exclusive).
  ++ The sign of a two sample t-test is 'A-B'; that is, a positive result
     means that the A set of correlations average larger than the B set.
  ++ The output t-statistics are converted to Z-scores for transmission to AFNI,
     using the same code as the 'fitt_t2z(t,d)' function in 3dcalc:
    -- e.g, the output of the command
          ccalc 'fitt_t2z(4,15)'
       is 3.248705, showing that a t-statistic of 4 with 15 degrees-of-freedom
       (DOF) has the same p-value as a Z-score [N(0,1) deviate] of 3.248705.
    -- One reason for using Z-scores is that the DOF parameter varies between
       voxels when you choose the -unpooled option for a 2-sample t-test.

 -labelA aaa = Label to attach (in AFNI) to sub-bricks corresponding to setA.
               If you don't give this option, the label used will be the prefix
               from the -setA filename.

 -labelB bbb = Label to attach (in AFNI) to sub-bricks corresponding to setB.
              ++ At most the first 11 characters of each label will be used!

-----------------------*** Two-Sample Options ***-----------------------

 -pooled   = For a two-sample un-paired t-test, use a pooled variance estimator
            ++ This is the default, but it can be changed from the AFNI GUI.
 -unpooled = For a two-sample un-paired t-test, use an unpooled variance estimator
            ++ Statistical power declines a little, and in return,
               the test becomes a little more robust.
 -paired   = Use a two-sample paired t-test
            ++ Which is the same as subtracting the two sets of 3D correlation
               maps, then doing a one-sample t-test.
            ++ To use '-paired', the number of datasets in each collection
               must be the same, and the datasets must have been input to
               3dSetupGroupInCorr in the same relative order when each
               collection was created. (Duh.)
 -nosix    = For a 2-sample situation, the program by default computes
             not only the t-test for the difference between the samples,
             but also the individual (setA and setB) 1-sample t-tests, giving
             6 sub-bricks that are sent to AFNI.  If you don't want
             these 4 extra 1-sample sub-bricks, use the '-nosix' option.
            ++ See the Covariates discussion, below, for an example of how
               '-nosix' affects which covariate sub-bricks are computed.

 **++ None of these 'two-sample' options means anything for a 1-sample
      t-test (i.e., where you don't use -setB).

-----------------*** Dataset-Level Covariates [May 2010] ***-----------------

 -covariates cf = Read file 'cf' that contains covariates values for each dataset
                  input (in both -setA and -setB; there can only at most one
                  -covariates option).  Format of the file
     FIRST LINE  -->  subject IQ   age
     LATER LINES -->  Elvis   143   42
                      Fred     85   59
                      Ethel   109   49
                      Lucy    133   32
        This file format should be compatible with 3dMEMA.

        ++ The first column contains the labels that must match the dataset
            labels stored in the input *.grpincorr.niml files, which are
            either the dataset prefixes or whatever you supplied in the
            3dSetupGroupInCorr program via '-labels'.
            -- If you ran 3dSetupGroupInCorr before this update, its output
               .grpincorr.niml file will NOT have dataset labels included.
               Such a file cannot be used with -covariates -- Sorry.

        ++ The later columns contain numbers: the covariate values for each
            input dataset.
            -- 3dGroupInCorr does not allow voxel-level covariates.  If you
               need these, you will have to use 3dttest++ on the '-sendall'
               output (of individual dataset correlations), which might best
               be done using '-batch' mode (cf. far below).

        ++ The first line contains column headers.  The header label for the
            first column isn't used for anything.  The later header labels are
            used in the sub-brick labels sent to AFNI.

        ++ If you want to omit some columns in file 'cf' from the analysis,
            you can do so with the standard AFNI column selector '[...]'.
            However, you MUST include column #0 first (the dataset labels) and
            at least one more numeric column.  For example:
              -covariates Cov.table'[0,2..4]'
            to skip column #1 but keep columns #2, #3, and #4.

        ++ At this time, only the -paired and -pooled options can be used with
            covariates.  If you use -unpooled, it will be changed to -pooled.
            -unpooled still works with a pure t-test (no -covariates option).
            -- This restriction might be lifted in the future.  Or it mightn't.

        ++ If you use -paired, then the covariates for -setB will be the same
            as those for -setA, even if the dataset labels are different!
            -- This restriction may be lifted in the future.  Or maybe not.

        ++ By default, each covariate column in the regression matrix will have
            its mean removed (centered). If there are 2 sets of subjects, each
            set's matrix will be centered separately.
            -- See the '-center' option (below) to alter this default.

        ++ For each covariate, 2 sub-bricks are produced:
            -- The estimated slope of arctanh(correlation) vs covariate
            -- The Z-score of the t-statistic of this slope

        ++ If there are 2 sets of subjects, then each pair of sub-bricks is
            produced for the setA-setB, setA, and setB cases, so that you'll
            get 6 sub-bricks per covariate (plus 6 more for the mean, which
            is treated as a special covariate whose values are all 1).
            -- At present, there is no way to tell 3dGroupInCorr not to send
               all this information back to AFNI/SUMA.

        ++ EXAMPLE:
           If there are 2 groups of datasets (with setA labeled 'Pat', and setB
           labeled 'Ctr'), and one covariate (labeled IQ), then the following
           sub-bricks will be produced:

       # 0: Pat-Ctr_mean    = mean difference in arctanh(correlation)
       # 1: Pat-Ctr_Zscr    = Z score of t-statistic for above difference
       # 2: Pat-Ctr_IQ      = difference in slope of arctanh(correlation) vs IQ
       # 3: Pat-Ctr_IQ_Zscr = Z score of t-statistic for above difference
       # 4: Pat_mean        = mean of arctanh(correlation) for setA
       # 5: Pat_Zscr        = Z score of t-statistic for above mean
       # 6: Pat_IQ          = slope of arctanh(correlation) vs IQ for setA
       # 7: Pat_IQ_Zscr     = Z score of t-statistic for above slope
       # 8: Ctr_mean        = mean of arctanh(correlation) for setB
       # 9: Ctr_Zscr        = Z score of t-statistic for above mean
       #10: Ctr_IQ          = slope of arctanh(correlation) vs IQ for setB
       #11: Ctr_IQ_Zscr     = Z score of t-statistic for above slope

        ++ However, the single-set results (sub-bricks #4-11) will NOT be
           computed if the '-nosix' option is used.

        ++ If '-sendall' is used, the individual dataset arctanh(correlation)
           maps (labeled with '_zcorr' at the end) will be appended to this
           list.  These setA sub-brick labels will start with 'A_' and these
           setB labels with 'B_'.

        ++ If you are having trouble getting the program to read your covariates
           table file, then set the environment variable AFNI_DEBUG_TABLE to YES
           and run the program -- the messages may help figure out the problem.
           For example:
             3dGroupInCorr -DAFNI_DEBUG_TABLE=YES -covariates cfile.txt |& more

  -->>**++ A maximum of 31 covariates are allowed.  If you need more, then please
           consider the possibility that you are completely deranged or demented.

 *** CENTERING ***
 Covariates are processed using linear regression.  There is one column in the
 regression matrix for each covariate, plus a column of all 1s for the mean
 value.  'Centering' refers to the process of subtracting some value from each
 number in a covariate's column, so that the fitted model for the covariate's
 effect on the data is zero at this subtracted value; the model (1 covariate) is:
   data[i] = mean + slope * ( covariate[i] - value )
 where i is the dataset index.  The standard (default) operation is that 'value'
 is the mean of the covariate[i] numbers.

 -center NONE = Do not remove the mean of any covariate.

 -center DIFF = Each set will have the means removed separately [default].

 -center SAME = The means across both sets will be computed and subtracted.
                (This option only applies to a 2-sample unpaired test.)

 -center VALS A.1D [B.1D]
                This option (for Gang Chen) allows you to specify the
                values that will be subtracted from each covariate before
                the regression analysis.  If you use this option, then
                you must supply a 1D file that gives the values to be
                subtracted from the covariates; if there are 3 covariates,
                then the 1D file for the setA datasets should have 3 numbers,
                and the 1D file for the setB datasets (if present) should
                also have 3 numbers.
              * For example, to put these values directly on the command line,
                you could do something like this:
                  -center VALS '1D: 3 7 9' '1D: 3.14159 2.71828 0.91597'
              * As a special case, if you want the same values used for
                the B.1D file as in the A.1D file, you can use the word
                'DITTO' in place of repeating the A.1D filename.
              * Of course, you only have to give the B.1D filename if there
                is a setB collection of datasets, and you are not doing a
                paired t-test.

 Please see the discussion of CENTERING in the 3dttest++ help output.  If
 you change away from the default 'DIFF', you should really understand what
 you are doing, or an elephant may sit on your head, which no one wants.

---------------------------*** Other Options ***---------------------------

 -seedrad r = Before performing the correlations, average the seed voxel time
              series for a radius of 'r' millimeters.  This is in addition
              to any blurring done prior to 3dSetupGroupInCorr.  The default
              radius is 0, but the AFNI user can change this interactively.

 -sendall   = Send all individual subject results to AFNI, as well as the
              various group statistics.
             ++ These extra sub-bricks will be labeled like 'xxx_zcorr', where
                'xxx' indicates which dataset the results came from; 'zcorr'
                denotes that the values are the arctanh of the correlations.
             ++ If there are a lot of datasets, then the results will be VERY
                large and take up a lot of memory in AFNI.
           **++ Use this option with some judgment and wisdom, or bad things
                might happen! (e.g., your computer runs out of memory.)
             ++ This option is also known as the 'Tim Ellmore special'.

 -ah host = Connect to AFNI/SUMA on the computer named 'host', rather than
            on the current computer system 'localhost'.
     ++ This allows 3dGroupInCorr to run on a separate system than
        the AFNI GUI.
       -- e.g., If your desktop is weak and pitiful, but you have access
          to a strong and muscular multi-CPU server (and the network
          connection is fast).
     ++ Note that AFNI must be setup with the appropriate
        'AFNI_TRUSTHOST_xx' environment variable, so that it will
        allow the external socket connection (for the sake of security):
      -- Example: AFNI running on computer 137.168.0.3 and 3dGroupInCorr
         running on computer 137.168.0.7
      -- Start AFNI with a command like
           afni -DAFNI_TRUSTHOST_01=137.168.0.7 -niml ...
      -- Start 3dGroupInCorr with a command like
           3dGroupInCorr -ah 137.168.0.3 ...
      -- You may use hostnames in place of IP addresses, but numerical
         IP addresses may work more reliably.
      -- If you are very trusting, you can set NIML_COMPLETE_TRUST to YES
         to allow NIML socket connections from anybody. (This only affects
         AFNI programs, not any other software on your computer.)
      -- You might also need to adjust your firewall settings to allow
         the reception of TCP/IP socket connections from outside computers.
         Firewalls are a separate issue from setting up AFNI host 'trusting',
         and the mechanics of how you can setup your firewall permissions is
         not something about which we can give you advice.

   -np PORT_OFFSET: Provide a port offset to allow multiple instances of
                    AFNI <--> SUMA, AFNI <--> 3dGroupIncorr, or any other
                    programs that communicate together to operate on the same
                    machine. 
                    All ports are assigned numbers relative to PORT_OFFSET.
         The same PORT_OFFSET value must be used on all programs
           that are to talk together. PORT_OFFSET is an integer in
           the inclusive range [1025 to 65500]. 
         When you want to use multiple instances of communicating programs, 
           be sure the PORT_OFFSETS you use differ by about 50 or you may
           still have port conflicts. A BETTER approach is to use -npb below.
   -npq PORT_OFFSET: Like -np, but more quiet in the face of adversity.
   -npb PORT_OFFSET_BLOC: Simliar to -np, except it is easier to use.
                          PORT_OFFSET_BLOC is an integer between 0 and
                          MAX_BLOC. MAX_BLOC is around 4000 for now, but
                          it might decrease as we use up more ports in AFNI.
                          You should be safe for the next 10 years if you 
                          stay under 2000.
                          Using this function reduces your chances of causing
                          port conflicts.

         See also afni and suma options: -list_ports and -port_number for 
            information about port number assignments.

         You can also provide a port offset with the environment variable
            AFNI_PORT_OFFSET. Using -np overrides AFNI_PORT_OFFSET.

   -max_port_bloc: Print the current value of MAX_BLOC and exit.
                   Remember this value can get smaller with future releases.
                   Stay under 2000.
   -max_port_bloc_quiet: Spit MAX_BLOC value only and exit.
   -num_assigned_ports: Print the number of assigned ports used by AFNI 
                        then quit.
   -num_assigned_ports_quiet: Do it quietly.

     Port Handling Examples:
     -----------------------
         Say you want to run three instances of AFNI <--> SUMA.
         For the first you just do: 
            suma -niml -spec ... -sv ...  &
            afni -niml &
         Then for the second instance pick an offset bloc, say 1 and run
            suma -niml -npb 1 -spec ... -sv ...  &
            afni -niml -npb 1 &
         And for yet another instance:
            suma -niml -npb 2 -spec ... -sv ...  &
            afni -niml -npb 2 &
         etc.

         Since you can launch many instances of communicating programs now,
            you need to know wich SUMA window, say, is talking to which AFNI.
            To sort this out, the titlebars now show the number of the bloc 
            of ports they are using. When the bloc is set either via 
            environment variables AFNI_PORT_OFFSET or AFNI_PORT_BLOC, or  
            with one of the -np* options, window title bars change from 
            [A] to [A#] with # being the resultant bloc number.
         In the examples above, both AFNI and SUMA windows will show [A2]
            when -npb is 2.


 -NOshm = Do NOT reconnect to AFNI using shared memory, rather than TCP/IP,
          when using 'localhost' (i.e., AFNI and 3dGroupInCorr are running
          on the same system).
       ++ The default is to use shared memory for communication when
          possible, since this method of transferring large amounts of
          data between programs on the same computer is much faster.
       ++ If you have a problem with the shared memory communication,
          use '-NOshm' to use TCP/IP for all communications.
       ++ If you use '-VERB', you will get a very detailed progress report
          from 3dGroupInCorr as it computes, including elapsed times for
          each stage of the process.

 -suma = Talk to suma instead of afni, using surface-based i/o data.
 -sdset_TYPE = Set the output format in surface-based batch mode to
               TYPE. For allowed values of TYPE, search for option
               called -o_TYPE in ConvertDset -help.
               Typical values would be: 
                  -sdset_niml, -sdset_1D, or -sdset_gii
 -quiet = Turn off the 'fun fun fun in the sun sun sun' informational messages.
 -verb  = Print out extra informational messages for more fun!
 -VERB  = Print out even more informational messages for even more fun fun!!
 -debug = Do some internal testing (slows things down a little)

---------------*** Talairach (+trlc) vs. Original (+orig) ***---------------

Normally, AFNI assigns the dataset sent by 3dGroupInCorr to the +tlrc view.
However, you can tell AFNI to assign it to the +orig view instead.
To do this, set environment variable AFNI_GROUPINCORR_ORIG to YES when
starting AFNI; for example:

  afni -DAFNI_GROUPINCORR_ORIG=YES -niml

This feature might be useful to you if you are doing a longitudinal study on
some subject, comparing resting state maps before and after some treatment.

-----------*** Group InstaCorr and AFNI's Clusterize function ***-----------

At this moment in history, you can't use Clusterize in the AFNI A controller at
the same time that 3dGroupInCorr is actively connected.  If you also want to
Clusterize the maps from this program, there are 2 slightly clumsy methods
that work reasonably well:

(1) In the A controller, you can switch between 'Clusters' and 'GrpInCorr':
   -- When 'Clusters' is active, you can Clusterize, but you can't do a
      new 'InstaCorr Set' operation
   -- When 'GrpInCorr' is active, then you can do 'InstaCorr Set', but
      the new result won't be Clusterize-d, until you switch back to
      'Clusters' and then press 'Clusterize' again.
   -- This is clumsy because you have to keep switching between GrpInCorr
      and Clusterize, which quickly becomes very annoying.

(2) Alternatively, you can open up the B controller (with the 'New' button),
    and then view the A_GRP_ICORR dataset as the Overlay in a separate
    set of image viewers, which you can Clusterize.
   -- However, since you also have to view the un-Clusterize-d A_GRP_ICORR
      dataset in the AFNI A controller, it is necessary to un-Lock the
      viewing controls of the two controllers.  Otherwise, the 2 controllers
     'fight' for who controls the way the dataset is edited for presentation,
      and the Clusterize-ation in controller B can appear and disappear
      as you scroll around.
   -- To turn off the Lock between the A and B controllers, use the
      Datamode->Lock menu and select 'Clear All'.  Or start AFNI with
      the command line option '-DAFNI_ALWAYS_LOCK=NO' (to override the
      default where all controllers are locked together at startup).
   -- This is clumsy because you have to use two controllers, and set
      your GrpInCorr seed in the A image viewers but view the results
      you want to see in the B image viewers.  And scrolling around in
      the unlocked image viewers can also be annoying.

--------------------------*** BATCH MODE [Feb 2011] ***-----------------------

* In batch mode, instead of connecting AFNI or SUMA to get commands on
  what to compute, 3dGroupInCorr computes correlations (etc.) based on
  commands from an input file.
  ++ Batch mode works to produce 3D (AFNI, or NIfTI) or 2D surface-based 
     (SUMA or GIFTI format) datasets. 

* Each line in the command file specifies the prefix for the output dataset
  to create, and then the set of seed vectors to use.
  ++ Each command line produces a distinct dataset.
  ++ If you want to put results from multiple commands into one big dataset,
     you will have to do that with something like 3dbucket or 3dTcat after
     running this program.
  ++ If an error occurs with one command line (e.g., a bad seed location is
     given), the program will not produce an output dataset, but will try
     to continue with the next line in the command file.
  ++ Note that I say 'seed vectors', since a distinct one is needed for
     each dataset comprising the inputs -setA (and -setB, if used).

* Batch mode is invoked with the following option:

   -batch METHOD COMMANDFILENAME

  where METHOD specifies how the seed vectors are to be computed, and
  where COMMANDFILENAME specifies the file with the commands.
  ++ As a special case, if COMMANDFILENAME contains a space character,
     then instead of being interpreted as a filename, it will be used
     as the contents of a single line command file; for example:
       -batch IJK 'something.nii 33 44 55'
     could be used to produce a single output dataset named 'something.nii'.
  ++ Only one METHOD can be used per batch mode run of 3dGroupInCorr!
     You can't mix up 'IJK' and 'XYZ' modes, for example.
  ++ Note that this program WILL overwrite existing datasets, unlike most
     AFNI programs, so be careful.

* METHOD must be one of the following strings (not case sensitive):

  ++ IJK     ==> the 3D voxel grid index triple (i,j,k) is given in FILENAME,
 or  IJKAVE      which tells the program to extract the time series from
                 each input dataset at that voxel and use that as the seed
                 vector for that dataset (if '-seedrad' is given, then the
                 seed vector will be averaged as done in interactive mode).
              ** This is the same mode of operation as the interactive seed
                 picking via AFNI's 'InstaCorr Set' menu item.
             -- FILE line format:  prefix i j k

  ++ XYZ     ==> very similar to 'IJK', but instead of voxel indexes being
 or  XYZAVE      given to specify the seed vectors, the RAI (DICOM) (x,y,z)
                 coordinates are given ('-seedrad' also applies).
              ** If you insist on using LPI (neurological) coordinates, as
                 Some other PrograMs (which are Fine Software tooLs) do,
                 set environmentment variable AFNI_INSTACORR_XYZ_LPI to YES,
                 before running this program.
             -- FILE line format:  prefix x y z

  ++ NODE    ==> the index of the surface node where the seed is located.
                 A simple line would contain a prefix and a node number.
                 The prefix sets the output name and the file format, 
                 if you include the extension. See also -sdset_TYPE option.
                 for controlling output format.
                 The node number specifies the seed node. Because you might
                 have two surfaces (-LRpairs option in 3dSetupGroupInCorr)
                 you can add 'L', or 'R' to the node index to specify its
                 hemisphere.
                 For example:
                     OccipSeed1 L720
                     OccipSeed2 R2033
                 If you don't specify the side in instances where you are
                 working with two hemispheres, the default is 'L'.

  ++ MASKAVE ==> each line on the command file specifies a mask dataset;
                 the nonzero voxels in that dataset are used to define
                 the list of seed voxels that will be averaged to give
                 the set of seed vectors.
              ** You can use the usual '[..]' and '<..>' sub-brick and value
                 range selectors to modify the dataset on input.  Do not
                 put these selectors inside quotes in the command file!
             -- FILE line format:  prefix maskdatasetname

  ++ IJKPV   ==> very similar to IJKAVE, XYZAVE, and MASKAVE (in that order),
  ++ XYZPV       but instead of extracting the average over the region
  ++ MASKPV      indicated, extracts the Principal Vector (in the SVD sense;
                 cf. program 3dLocalPV).
              ** Note that IJKPV and XYZPV modes only work if seedrad > 0.
              ** In my limited tests, the differences between the AVE and PV
                 methods are very small.  YMMV.

  ++ VECTORS ==> each line on the command file specifies an ASCII .1D
                 file which contains the set of seed vectors to use.
                 There must be as many columns in the .1D file as there
                 are input datasets in -setA and -setB combined.  Each
                 column must be as long as the maximum number of time
                 points in the longest dataset in -setA and -setB.
              ** This mode is for those who want to construct their own
                 set of reference vectors in some clever way.
              ** N.B.: This method has not yet been tested!
             -- FILE line format:  prefix 1Dfilename

 =========================================================================
* This binary version of 3dGroupInCorr is NOT compiled using OpenMP, a
   semi-automatic parallelizer software toolkit, which splits the work
   across multiple CPUs/cores on the same shared memory computer.
* However, the source code is modified for OpenMP, and can be compiled
   with an OpenMP-capable compiler, such as gcc 4.2+, Intel's icc, and
   Sun Studio.
* If you wish to compile this program with OpenMP, see the man page for
   your C compiler, and (if needed) consult the AFNI message board, and
   http://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
++ Authors: Bob Cox and Ziad Saad

++ Compile date = May  2 2012
This page auto-generated on Thu May 3 04:28:16 EDT 2012