:orphan:

.. _ahelp_3dSpaceTimeCorr:

***************
3dSpaceTimeCorr
***************

.. contents:: :local:


| 

.. code-block:: none

    
      3dSpaceTimeCorr
      v1.2 (PA Taylor, Aug. 2019)
    
      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 someone *wishes* that s/he 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.
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
      
      + USAGE: Load in 2 data sets and a mask.  This computation can get pretty
               time consuming-- it depends on the number of voxels N like N**2.
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + COMMAND:  two 4D data sets need to be put in (order doesn't matter), 
                  and a mask also *should* be.
    
        3dSpaceTimeCorr -insetA FILEA -insetB FILEB -prefix PREFIX   \
                       {-mask MASK} {-out_Zcorr}  
                       {-freeze_insetA_ijk II JJ KK} 
                       {-freeze_insetA_xyz XX YY ZZ} 
    
        where:
    
      -insetA FILEA  :one 4D data set.
      -insetB FILEB  :another 4D data set; must have same spatial dimesions as
                      FILEA, as well as same 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).
    
    -freeze_insetA_ijk II JJ KK
                     :instead of correlating the spatial correlation maps
                      of A and B that have matching seed locations, with this
                      option you can 'freeze' the seed voxel location in 
                      the input A dset, while the seed location in B moves
                      throughout the volume or mask as normal.
                      Here, one inputs three values, the ijk indices in
                      the dataset. (See next opt for freezing at xyz location.)
    
    -freeze_insetA_xyz XX YY ZZ
                     :same behavior as using '-freeze_insetA_ijk ..', but here
                      one inputs the xyz (physical coordinate) indices.
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + OUTPUT: 
          A data set with one value at each voxel, representing the space-time 
          correlation of the two input data sets within the input mask.
    
    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
      + EXAMPLE:
        3dSpaceTimeCorr                       \
            -insetA SUB_01.nii.gz             \
            -insetB SUB_02.nii.gz             \
            -mask   mask_GM.nii.gz            \
            -prefix stcorr_01_02              \