3dNetCorr


  Calculate correlation matrix of a set of ROIs (using mean time series of
  each). Several networks may be analyzed simultaneously, one per brick.

  Written by PA Taylor (March, 2013), part of FATCAT (Taylor & Saad,
  2013) in AFNI.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + USAGE: Input a set of 4D data and a set of ROI masks (i.e., a bunch of
         ROIs in a brik each labelled with a distinct integer), and get a
         matrix of correlation values for it.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + COMMAND: 3dNetCorr -prefix PREFIX {-mask MASK} {-fish_z} {-part_corr} \
                -inset FILE -in_rois INROIS {-ts_out} {-ts_label}         \
                {-ts_indiv} {-ts_wb_corr} {-ts_wb_Z} {-nifti}             \
                {-push_thru_many_zeros} {-ts_wb_strlabel}                 \
                {-output_mask_nonnull} {-weight_ts WTS}

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + OUTPUT:
        Output will be a simple text file, first with the number N of ROIs
        in the set, then an empty line, then a list of the ROI labels in the
        file (i.e., col/row labels), empty line, and then an NxN matrix of
        correlation values (diagonals should be unity). One can also output
        the Fisher Z-transform of the matrix (with zeros along diag).
        If multiple subbricks are entered, one gets multiple files output,
        one per subbrick/network.
        Naming convention of outputs: PREFIX_???.netcc, where `???'
        represents a zero-padded version of the network number, based on the
        number of subbricks in the `in_rois' option (i.e., 000, 001,...).
        If the `-ts_out' option is used, the mean time series per ROI, one
        line, are output in PREFIX_???.netts files.
        Labeltables are now also supported; when an '-inset FILE' contains
        a labeltable, the labels will then be passed to the *.netcc file.
        These labels may then be referred to in plotting/output, such as
        using fat_mat_sel.py.
        +NEW+ (Dec. 2014): A PREFIX_???.niml.dset is now also output
        automatically.  This NIML/SUMA-esque file is mainly for use in SUMA,
        for visualizing connectivity matrix info in a 3D brain.  It can be
        opened via, for example:
        $ suma -vol ROI_FILE  -gdset FILE.niml.dset

        It is now also possible to output whole brain correlation maps,
        generated from the average time series of each ROI,
        as either Pearson r or Fisher-transformed Z-scores (or both); see
        the '-ts_wb*' options below.

        [As of April, 2017] There is now more checking done for having any
        null time series in ROIs.  They are bad to have around, esp. when
        they fill an ROI.  A new file called 'PREFIX.roidat' is now output,
        whose columns contain information for each ROI in the used mask:
        [Nvox] [Nvox with non-null ts] [non-null frac] # [ROI number] [label]
        The program also won't run now by default if an ROI contains more
        than 10 percent null time series; one can use a '-push*' option
        (see below) to still calculate anyways, but it will definitely cease
        if any ROI is full of null time series.
        ... And the user can flag to output a binary mask of the non-null
        time series, called 'PREFIX_mask_nnull*', with the new option
        '-output_mask_nonnull'.  This might be useful to check if your data
        are well-masked, if you haven't done so already (and you know who
        you are...).

        [As of April, 2017] On a minor note, one can also apply string labels
        to the WB correlation/Z-score output files;  see the option
        '-ts_wb_strlabel', below.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + RUNNING, need to provide:
    -prefix PREFIX   :output file name part (see description below).
    -inset  FILE     :time series file (4D data set).

    -mask   MASK     :can include a whole brain mask within which to
                      calculate correlation. (Otherwise, data should be
                      masked already; the program will try to analyze.)
    -in_rois INROIS  :can input a set of ROIs, each labelled with distinct
                      integers. Multiple subbricks can be input, each will
                      be treated as a separate network.

    -fish_z          :switch to also output a matrix of Fisher Z-transform
                      values for the corr coefs (r):
                          Z = atanh(r) ,
                      (with Z=4 being output along matrix diagonals where
                      r=1, as the r-to-Z conversion is ceilinged at
                      Z = atanh(r=0.999329) = 4, which is still *quite* a
                      high Pearson-r value.
    -part_corr       :output the partial correlation matrix. It is
                      calculated from the inverse of regular Pearson
                      matrix, R, as follows: let M = R^{I} be in the inverse
                      of the Pearson cc matrix.  Then each element p_{ij} of
                      the partial correlation (PC) matrix is given as:
                      p_{ij} = -M_{ij}/sqrt( M_{ii} * M_{jj} ).
                      This will also calculate the PC-beta (PCB) matrix,
                      which is not symmetric, and whose values are given as:
                      b_{ij} = -M_{ij}/M_{ii}.
                      Use as you wish.  For both PC and PCB, the diagonals
                      should be uniformly (negative) unity.

    -ts_out          :switch to output the mean time series of the ROIs that
                      have been used to generate the correlation matrices.
                      Output filenames mirror those of the correlation
                      matrix files, with a '.netts' postfix.
    -ts_label        :additional switch when using '-ts_out'. Using this
                      option will insert the integer ROI label at the start
                      of each line of the *.netts file created. Thus, for
                      a time series of length N, each line will have N+1
                      numbers, where the first is the integer ROI label
                      and the subsequent N are scientific notation values.
    -ts_indiv        :switch to create a directory for each network that
                      contains the average time series for each ROI in
                      individual files (each file has one line).
                      The directories are labelled PREFIX_000_INDIV/,
                      PREFIX_001_INDIV/, etc. (one per network). Within each
                      directory, the files are labelled ROI_001.netts,
                      ROI_002.netts, etc., with the numbers given by the
                      actual ROI integer labels.
    -ts_wb_corr      :switch to perform whole brain correlation for each
                      ROI's average time series; this will automatically
                      create a directory for each network that contains the
                      set of whole brain correlation maps (Pearson 'r's).
                      The directories are labelled as above for '-ts_indiv'
                      Within each directory, the files are labelled
                      WB_CORR_ROI_001+orig, WB_CORR_ROI_002+orig, etc., with
                      the numbers given by the actual ROI integer labels.
    -ts_wb_Z         :same as above in '-ts_wb_corr', except that the maps
                      have been Fisher transformed to Z-scores the relation:
                      Z=atanh(r).
                      To avoid infinities in the transform, Pearson values
                      are effectively capped at |r| = 0.999329 (where
                      |Z| = 4.0;  hope that's good enough).
                      Files are labelled WB_Z_ROI_001+orig, etc.
    -weight_ts WTS   :input a 1D file WTS of weights that will be applied
                      multiplicatively to each ROI's average time series.
                      WTS can be a column- or row-file of values, but it
                      must have the same length as the input time series
                      volume.
                      If the initial average time series was A[n] for
                      n=0,..,(N-1) time points, then applying a set of
                      weights w[n] of the same length from WTS would
                      produce a new time series:  B[n] = A[n] * W[n].

    -ts_wb_strlabel  :by default, '-ts_wb_{corr,Z}' output files are named
                      using the int number of a given ROI, such as:
                        WB_Z_ROI_001+orig.
                      with this option, one can replace the int (such as
                      '001') with the string label (such as 'L-thalamus')
                      *if* one has a labeltable attached to the file.
    -nifti           :output any correlation map files as NIFTI files
                      (default is BRIK/HEAD). Only useful if using
                      '-ts_wb_corr' and/or '-ts_wb_Z'.

   -output_mask_nonnull
                     :internally, this program checks for where there are
                      nonnull time series, because we don't like those, in
                      general.  With this flag, the user can output the
                      determined mask of non-null time series.
   -push_thru_many_zeros
                     :by default, this program will grind to a halt and
                      refuse to calculate if any ROI contains >10 percent
                      of voxels with null times series (i.e., each point is
                      0), as of April, 2017.  This is because it seems most
                      likely that hidden badness is responsible. However,
                      if the user still wants to carry on the calculation
                      anyways, then this option will allow one to push on
                      through.  However, if any ROI *only* has null time
                      series, then the program will not calculate and the
                      user will really, really, really need to address
                      their masking.

    -ignore_LT       :switch to ignore any label table labels in the
                      '-in_rois' file, if there are any labels attached.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + EXAMPLE:
      3dNetCorr                                  \
         -inset REST_in_DWI.nii.gz               \
         -in_rois ROI_ICMAP_GM+orig              \
         -fish_z                                 \
         -ts_wb_corr                             \
         -mask mask_DWI+orig                     \
         -prefix FMRI/REST_corr

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  If you use this program, please reference the introductory/description
  paper for the FATCAT toolbox:
        Taylor PA, Saad ZS (2013).  FATCAT: (An Efficient) Functional
        And Tractographic Connectivity Analysis Toolbox. Brain
        Connectivity 3(5):523-535.