3dSpaceTimeCorr2


Overview

This program is the MUCH MUCH MUCH faster version of the original
3dSpaceTimeCorr program.  It uses pre-Z-score-ization (like InstaCorr)
and OpenMP-based multithreading to achieve such relativistically better
runtimes.

This program is for calculating something *similar* to the (Pearson)
correlation coefficient between corresponding voxels between two data
sets, which is what 3dTcorrelate does.  However, this is program
operates differently. Here, two data sets are loaded in, and for each
voxel in the brain:
   + for each data set, an ijk-th voxel is used as a seed to generate a
     correlation map within a user-defined mask (e.g., whole brain,
     excluding the seed location where r==1, by definition);
   + that correlation map is Fisher Z transformed;
   + the Z-correlation maps are (Pearson) correlated with each other,
     generating a single correlation coefficient;
   + the correlation coefficient is stored at the same ijk-th voxel
     location in the output data set;
and the process is repeated.  Thus, the output is a whole brain map
of r-correlation coefficients for corresponding voxels from the two data
sets, generated by temporal and spatial patterns (-> space+time
correlation!).

This could be useful when researchers *wish* that they could use
3dTcorrelate on something like resting state FMRI data.  Maybe.
Note that this program could take several minutes or more to run,
depending on the size of the data set and mask.

written by: PA Taylor (SSCC, NIMH, NIH, USA)
            with a great deal of input, helpful discussion, beta-testing
            and patience from Peter Kirk (EDB, NIMH, NIH, USA), who also
            has the distinction of finding a real _use_ for this program.

Usage

Load in two 4D datasets (e.g., FMRI volumes) and a mask.

This program makes use of multithreading, and it is best to let it use
many CPUs/threads to calculate, otherwise it can get slow-ish.

    3dSpaceTimeCorr -insetA FILEA -insetB FILEB  -mask MASK \
                    -prefix PREFIX {-out_Zcorr}

    where:

  -insetA FILEA  :one 4D data set.

  -insetB FILEB  :another 4D data set; must match spatial grid of FILEA
                  (but can have differing number of time points).

  -mask MASK     :optional mask.  Highly recommended to use for speed of
                  calcs (and probably for interpretability, too).

  -prefix PREFIX :output filename/base.

  -out_Zcorr     :switch to output Fisher Z transform of spatial map
                  correlation (default is Pearson r values).

Examples

1. Basic usage

   3dSpaceTimeCorr2                                 \
       -insetA  sub-001_task-rest_bold.nii.gz       \
       -insetB  sub-002_task-rest_bold.nii.gz       \
       -mask    mask.nii.gz                         \
       -prefix  stcorr_001_002