AFNI program: 3dSetupGroupInCorr

Output of -help

++ 3dSetupGroupInCorr: AFNI version=AFNI_24.1.03 (Apr 18 2024) [64-bit]
++ Authored by: RW Cox
Usage: 3dSetupGroupInCorr [options] dataset dataset ...

This program is used to pre-process a collection of AFNI
3D+time datasets for use with Group InstaCorr (3dGroupInCorr).

* By itself, this program just collects all its input datasets
  together for convenient processing later.  Pre-processing
  (e.g., detrending, bandpassing, despiking) must be done BEFORE
  running 3dSetupGroupInCorr -- for example, with 3dBandpass.
  The actual calculations of group t-tests of correlations is
  done AFTER running 3dSetupGroupInCorr, in program 3dGroupInCorr.

* All the datasets input here will be treated as one sample
  for the t-test performed in 3dGroupInCorr.  If you are going
  to do a 2-sample t-test, then you will need to run this
  program twice, once for each collection of datasets
  (e.g., once for 'control subjects' and once for 'patients').

* All datasets must have the same grid layout, since 3dGroupInCorr
  will do voxel-by-voxel comparisons.  Usually, this means that
  the datasets have been transformed to a standard space; for
  example, using the @auto_tlrc script.

* All the datasets use the same mask -- only voxels inside
  this mask will be stored and processed.  If you do not give the
  '-mask' option, then all voxels will be processed -- not usually
  a good idea, since non-brain voxels will use up a LOT of memory
  and CPU time in 3dGroupInCorr.
  ++ If you use '-mask', you MUST use the same mask dataset
     in all runs of 3dSetupGroupInCorr that will be input
     at the same time to 3dGroupInCorr -- otherwise, the
     computations in that program will make no sense AT ALL!
  ++ This requirement is why there is no '-automask' option.

* However, the datasets do NOT all have to have the same number
  of time points or time spacing.  But each dataset must have
  at least 9 points along the time axis!

* The ONLY pre-processing herein for each time series is to L2
  normalize it (sum of squares = 1) and scale it to 8-bit bytes
  (or to 16-bit shorts).
  ++ You almost certainly want to use 3dBandpass and/or some other
     code to pre-process the datasets BEFORE input to this program.
  ++ See the SAMPLE SCRIPT below for a semi-reasonable way to
     pre-process a collection of datasets for 3dGroupInCorr.
  ++ [10 May 2012] The '-prep' option now allows for some limited
     pre-processing operations.

* The outputs from this program are 2 files:
  ++ PREFIX.grpincorr.niml is a text file containing the header
     information that describes the data file.  This file is input
     to 3dGroupInCorr to define one sample in the t-test.
  ++ PREFIX.grpincorr.data is the data file, which contains
     all the time series (in the mask) from all the datasets.
  ++ The data file will usually be huge (gigabytes, perhaps).
     You need to be sure you have enough disk space and RAM.
  ++ If the output files already exist when you run this program,
     then 3dSetupGroupInCorr will exit without processing the datasets!

* See the help for 3dGroupInCorr for information on running that program.
* The PDF file
  https://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/afni20_instastuff.pdf
  also has some information on the Group InstaCorr process (as well as all
  the other 'Insta' functions added to AFNI).

* The program 3dExtractGroupInCorr can be used to reconstruct the
  input datasets from the .niml and .data files, if needed.

-------
OPTIONS
-------
  -mask mset     = Mask dataset [highly recommended for volumetric e data!]

  -prefix PREFIX = Set prefix name of output dataset

  -short         = Store data as 16-bit shorts [used to be the default]
                 ++ This will double the amount of disk space and RAM needed.
                 ++ For most GroupInCorr purposes, you don't need this option,
                    since there is so much averaging going on that truncation
                    noise is washed away.

  -byte          = Store data as 8-bit bytes rather than 16-bit shorts.
                 ++ This will save memory in 3dGroupInCorr (and disk space),
                    which can be important when using large collections of
                    datasets.  Results will be very slightly less accurate
                    than with '-short', but you'll have a hard time finding
                    any place where this matters.
                 ++ This option is now the default [08 Feb 2010].
                 ++ The amount of data stored is (# of voxels in the mask)
                                               * (# of time points per subject)
                                               * (# of subjects)
                    For a 3x3x3 mm^3 grid in MNI space, there are typically
                    about 70,000 voxels in the brain.  If you have an average
                    of 200 time points per scan, then one subject's scan will
                    take up 7e4*2e2 = 14 MB of space; 100 subjects would thus
                    require about 1.4 GB of space.

  -labels fff    = File 'fff' should be a list of labels, a unique one for each
                   dataset input.  These labels can be used in 3dGroupInCorr to
                   select a subset of datasets to be processed therein.
                 ++ If you don't use this option, then the list of labels will
                    comprise the list of prefixes from the input datasets.
                 ++ Labels cannot contain a space character, a comma, or a semicolon.
                 ++ When using the -LRpairs option, you should specify only
                    one label for eah pair. 
                    If you don't use the -labels option with -LRpairs the 
                    labels are taken from the 'L' only dataset names, that
                    would be the first name of each LRpair.

  -DELETE        = Delete input datasets from disk after
                   processing them one at a time into the
                   output data file -- this very highly
                   destructive option is intended to let
                   you save disk space, if absolutely
                   necessary.  *** BE CAREFUL OUT THERE! ***
                 ++ If you are setting up for 3dGroupInCorr
                    in a script that first uses 3dBandpass
                    to filter the datasets, and then uses this
                    program to finish the setup, then you
                    COULD use '-DELETE' to remove the
                    temporary 3dBandpass outputs as soon
                    as they are no longer needed.

  -prep XXX      = Prepare (or preprocess) each data time series in some
                   fashion before L2 normalization and storing, where
                   'XXX' is one of these:
                 ++ SPEARMAN ==> convert data to ranks, so that the
                                 resulting individual subject correlations
                                 in 3dGroupInCorr are Spearman correlations.
                 ++ DEMEAN   ==> remove the mean

    Variations for surface-based data:
    ----------------------------------
    If you are working with one surface, no special options are needed.
    However, it is often the case that you want to perform correlations
    on both hemispheres. So in that case, you'll want to provide volume
    pairs (Left Hemi data, Right Hemi data). To help reduce the risk of
    user errors (the only kind we know of), you should also provide the
    domain parents for each of the hemispheres.
       -LRpairs L_SURF R_SURF: This option sets the domains for the left
                               and right hemisphere surfaces, and 
                               indicates that the datasets to follow
                               are arranged in (Left, Right) pairs.
-------------
SAMPLE SCRIPT  (tcsh syntax)
-------------
* Assume datasets are named in the following scheme (sub01, sub02, ...)
 ++ T1-weighted anatomical  = sub01_anat+orig
 ++ Resting state EPI       = sub01_rest+orig
 ++ Standard space template = ~/abin/MNI_avg152T1+tlrc

#!/bin/tcsh

# MNI-ize each subject's anat, then EPIs (at 2 mm resolution)

cp -f ~/abin/MNI_avg152T1+tlrc.* .
foreach fred ( sub*_anat+orig.HEAD )
  set sub = `basename $fred _anat+orig.HEAD`
  @auto_tlrc -base MNI_avg152T1+tlrc.HEAD -input $fred
  adwarp -apar ${sub}_anat+tlrc.HEAD -dpar ${sub}_rest+orig.HEAD \
         -resam Cu -dxyz 2.0
  3dAutomask -dilate 1 -prefix ${sub}_amask ${sub}_rest+tlrc.HEAD
end

# Combine individual EPI automasks into a group mask

3dMean -datum float -prefix ALL_amaskFULL *_amask+tlrc.HEAD
3dcalc -datum byte -prefix ALL_amask5050 -a ALL_amaskFULL+tlrc -expr 'step(a-0.499)'
/bin/rm -f *_amask+tlrc.*

# Bandpass and blur each dataset inside the group mask
#  * Skip first 4 time points.
#  * If you want to remove the global mean signal, you would use the '-ort'
#    option for 3dBandpass -- but we recommend that you do NOT do this:
#    http://dx.doi.org/10.1089/brain.2012.0080

foreach fred ( sub*_rest+tlrc.HEAD )
  set sub = `basename $fred _rest+tlrc.HEAD`
  3dBandpass -mask ALL_amask5050+tlrc -blur 6.0 -band 0.01 0.10 -prefix ${sub}_BP\
             -input $fred'[4..$]'
end

# Extract data for 3dGroupInCorr

3dSetupGroupInCorr -mask ALL_amask5050 -prefix ALLshort -short *_BP+tlrc.HEAD

# OR

3dSetupGroupInCorr -mask ALL_amask5050 -prefix ALLbyte -byte *_BP+tlrc.HEAD

/bin/rm -f *_BP+tlrc.*

### At this point you could run (in 2 separate terminal windows)
###   afni -niml MNI_avg152T1+tlrc
###   3dGroupInCorr -setA ALLbyte.grpincorr.niml -verb
### And away we go ....

------------------
CREDITS (or blame)
------------------
* Written by RWCox, 31 December 2009.
* With a little help from my friends: Alex Martin, Steve Gotts, Ziad Saad.
* With encouragement from MMK.


++ Compile date = Apr 18 2024 {AFNI_24.1.03:linux_ubuntu_16_64}
This page auto-generated on Thu Apr 18 14:45:59 EDT 2024