Usage: 3dTcorrMap [options]
For each voxel time series, computes the correlation between it
and all other voxels, and combines this set of values into the
output dataset(s) in some way.
Supposed to give a measure of how 'connected' each voxel is
to the rest of the brain. [[As if life were that simple.]]
---------
WARNINGS:
---------
** This program takes a LONG time to run.
** This program will use a LOT of memory.
** Don't say I didn't warn you about these facts, and don't whine.
--------------
Input Options:
--------------
-input dd = Read 3D+time dataset 'dd' (a mandatory option).
This provides the time series to be correlated
en masse.
** This is a non-optional 'option': you MUST supply
and input dataset!
-seed bb = Read 3D+time dataset 'bb'.
** If you use this option, for each voxel in the
-seed dataset, its time series is correlated
with every voxel in the -input dataset, and
then that collection of correlations is processed
to produce the output for that voxel.
** If you don't use -seed, then the -input dataset
is the -seed dataset [i.e., the normal usage].
** The -seed and -input datasets must have the
same number of time points and the same number
of voxels!
** Unlike the -input dataset, the -seed dataset is not
preprocessed (i.e., no detrending/bandpass or blur).
(The main purpose of this -seed option is to)
(allow you to preprocess the seed voxel time)
(series in some personalized and unique way.)
-mask mmm = Read dataset 'mmm' as a voxel mask.
-automask = Create a mask from the input dataset.
** -mask and -automask are mutually exclusive!
** If you don't use one of these masking options, then
all voxels will be processed, and the program will
probably run for a VERY long time.
** Voxels with constant time series will be automatically
excluded.
----------------------------------
Time Series Preprocessing Options: (applied only to -input, not to -seed)
[[[[ In general, it would be better to pre-process with afni_proc.py ]]]]
----------------------------------
TEMPORAL FILTERING:
-------------------
-polort m = Remove polynomial trend of order 'm', for m=-1..19.
[default is m=1; removal is by least squares].
** Using m=-1 means no detrending; this is only useful
for data/information that has been pre-processed
(e.g., using the 3dBandpass program).
-bpass L H = Bandpass the data between frequencies L and H (in Hz).
** If the input dataset does not have a time step defined,
then TR = 1 s will be assumed for this purpose.
**** -bpass and -polort are mutually exclusive!
-ort ref = 1D file with other time series to be removed from -input
(via least squares regression) before correlation.
** Each column in 'ref' will be regressed out of
each -input voxel time series.
** -ort can be used with -polort and/or -bandpass.
** You can use programs like 3dmaskave and 3dmaskSVD
to create reference files from regions of the
input dataset (e.g., white matter, CSF).
SPATIAL FILTERING: (only for volumetric input datasets)
-----------------
-Gblur ff = Gaussian blur the -input dataset (inside the mask)
using a kernel width of 'ff' mm.
** Uses the same approach as program 3dBlurInMask.
-Mseed rr = When extracting the seed voxel time series from the
(preprocessed) -input dataset, average it over a radius
of 'rr' mm prior to doing the correlations with all
the voxel time series from the -input dataset.
** This extra smoothing is said by some mystics to
improve and enhance the results. YMMV.
** Only voxels inside the mask will be used.
** A negative value for 'rr' means to treat the voxel
dimensions as all equal to 1.0 mm; thus, '-Mseed -1.0'
means to average a voxel with its 6 nearest
neighbors in the -input dataset 3D grid.
** -Mseed and -seed are mutually exclusive!
(It makes NO sense to use both options.)
---------------
Output Options: (at least one of these must be given!)
---------------
-Mean pp = Save average correlations into dataset prefix 'pp'
** As pointed out to me by CC, '-Mean' is the same
as computing the correlation map with the 1D file
that is the mean of all the normalized time series
in the mask -- that is, a form of the global signal.
Such a calculation could be done much faster with
program 3dTcorr1D.
** Nonlinear combinations of the correlations, as done by
the options below, can't be done in such a simple way.
-Zmean pp = Save tanh of mean arctanh(correlation) into 'pp'
-Qmean pp = Save RMS(correlation) into 'pp'
-Pmean pp = Save average of squared positive correlations into 'pp'
(negative correlations don't count in this calculation)
-Thresh tt pp
= Save the COUNT of how many voxels survived thresholding
at level abs(correlation) >= tt (for some tt > 0).
-VarThresh t0 t1 dt pp
= Save the COUNT of how many voxels survive thresholding
at several levels abs(correlation) >= tt, for
tt = t0, t0+dt, ..., t1. This option produces
a multi-volume dataset, with prefix 'pp'.
-VarThreshN t0 t1 dt pp
= Like '-VarThresh', but the output counts are
'Normalized' (divided) by the expected number
of such supra-threshold voxels that would occur
from white noise timeseries.
** N.B.: You can't use '-VarThresh' and '-VarThreshN'
in the same run of the program!
-CorrMap pp
Output at each voxel the entire correlation map, into
a dataset with prefix 'pp'.
** Essentially this does what 3dAutoTcorrelate would,
with some of the additional options offered here.
** N.B.: Output dataset will be HUGE and BIG in most cases.
-CorrMask
By default, -CorrMap outputs a sub-brick for EACH
input dataset voxel, even those that are NOT in
the mask (such sub-bricks will be all zero).
If you want to eliminate these sub-bricks, use
this option.
** N.B.: The label for the sub-brick that was seeded
from voxel (i,j,k) will be of the form
v032.021.003 (when i=32, j=21, k=3).
--** The following 3 options let you create a customized **--
--** method of combining the correlations, if the above **--
--** techniques do not meet your needs. (Of course, you **--
--** could also use '-CorrMap' and then process the big **--
--** output dataset yourself later, in some clever way.) **--
-Aexpr expr ppp
= For each correlation 'r', compute the calc-style
expression 'expr', and average these values to get
the output that goes into dataset 'ppp'.
-Cexpr expr ppp
= As in '-Aexpr', but only average together nonzero
values computed by 'expr'. Example:
-Cexpr 'step(r-0.3)*r' TCa03
would compute (for each voxel) the average of all
correlation coefficients larger than 0.3.
-Sexpr expr ppp
= As above, but the sum of the expressions is computed
rather than the average. Example:
-Sexpr 'step(r-0.3)' TCn03
would compute the number of voxels with correlation
coefficients larger than 0.3.
** N.B.: At most one '-?expr' option can be used in
the same run of the program!
** N.B.: Only the symbols 'r' and 'z' [=atanh(r)] have any
meaning in the expression; all other symbols will
be treated as zeroes.
-Hist N ppp
= For each voxel, save a histogram of the correlation
coefficients into dataset ppp.
** N values will be saved per voxel, with the i'th
sub-brick containing the count for the range
-1+i*D <= r < -1+(i+1)*D with D=2/N and i=0..N-1
** N must be at least 20, and at most 1000.
* N=200 is good; then D=0.01, yielding a decent resolution.
** The output dataset is short format; thus, the maximum
count in any bin will be 32767.
** The output from this option will probably require further
processing before it can be useful -- but it is fun to
surf through these histograms in AFNI's graph viewer.
----------------
Random Thoughts:
----------------
-- In all output calculations, the correlation of a voxel with itself
is ignored. If you don't understand why, step away from the keyboard.
-- This purely experimental program is somewhat time consuming.
(Of course, it's doing a LOT of calculations.)
-- For Kyle, AKA the new Pat (assuming such a thing were possible).
-- For Steve, AKA the new Kyle (which makes him the newest Pat).
-- RWCox - August 2008 et cetera.
=========================================================================
* This binary version of 3dTcorrMap is compiled using OpenMP, a semi-
automatic parallelizer software toolkit, which splits the work across
multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
by a network (e.g., OpenMP doesn't work across cluster nodes).
* For some implementation and compilation details, please see
https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
your system. You can control this value by setting environment variable
OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
using all CPUs available.
++ However, on some systems, it seems to be necessary to set variable
OMP_NUM_THREADS explicitly, or you only get one CPU.
++ On other systems with many CPUS, you probably want to limit the CPU
count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
since OpenMP queries this variable BEFORE the program actually starts.
++ You can't usefully set this variable in your ~/.afnirc file or on the
command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 1.
* The maximum number of CPUs that will be used is now set to .... 1.
=========================================================================
++ Compile date = Oct 17 2024 {AFNI_24.3.03:linux_ubuntu_24_64}
