AFNI program: 3dNetCorr

Output of -help


Overview ~1~

  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 ~1~

  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.

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

Output ~1~

        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.

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

Command ~1~

  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}                   \
            {-weight_corr WCORR}

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

Running ~1~

    -prefix PREFIX   :(req) output file name part (see description below).

    -inset  FILE     :(req) time series file (4D data set). 


    -in_rois INROIS  :(req) can input a set of ROIs, each labelled with
                      distinct integers. Multiple subbricks can be input,
                      each will be treated as a separate network.

    -mask   MASK     :can include a whole brain mask within which to
                      calculate correlation. If no mask is input, then
                      the program will internally 'automask', based on
                      when non-uniformly-zero time series are.
                      If you want to neither put in a mask *nor* have the
                      automasking occur, see '-automask_off', below.

    -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].

  -weight_corr WCORR :input a 1D file WTS of weights that will be applied
                      to estimate a weighted Pearson Correlation.  This
                      is different than the '-weight_ts ..' weighting.

    -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.

  -allow_roi_zeros   :by default, this program will end unhappily if any ROI
                      contains only time series that are all zeros (which
                      might occur if you applied a mask to your data that
                      is smaller than your ROI map).  This is because the
                      correlation with an all-zero time series is undefined.
                      However, if you want to allow ROIs to have all-zero
                      time series, use this option; each row and column
                      element in the Pearson and Fisher-Z transformed
                      matrices for this ROI will be 0.  NB: you cannot
                      use -part_corr when this option is used, to avoid
                      of mathematical badness.
                      See the NOTE about this option, below

  -automask_off      :if you do not enter a mask, this program will
                      make an internal automask of where time series are
                      not uniformly zero.  However, if you don't want this
                      done (e.g., you have a map of N ROIs that has greater
                      extent than your masked EPI data, and you are using
                      '-allow_roi_zeros' to get a full NxN matrix, even if
                      some rows and columns are zero), then use this option.

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

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

NOTES ~1~

Re. Allowing zero-filled ROIs ('-allow_roi_zeros') ~2~

  If you use the '-allow_roi_zeros' option, you can get rows and columns
  of all zeros in the output *.netcc matrices (indeed, you are probably
  using it specifically to have the 'full' NxN matrix from N input ROIs,
  even with ROIs that only contain all-zero time series).

  Note that, at present, you should NOT put *.netcc files that contain
  such rows/columns of zeros into the fat_proc* pipeline, because 0 is a
  valid correlation (or Fisher Z-transform) value, and the pipeline is not
  designed to filter these values out (like it would for *.grid files).
  Therefore, the zeros will be included as 'real' correlation values,
  which would not be correct.

  So, these matrices could be output into OTHER analyses fine, but for
  preparing to do fat_proc_* comparisons, you would want to run this
  program without '-allow_roi_zeros'.  So, sometimes you might run it
  twice, with and without that option, which should be OK, because it
  is not a very time consuming program.

  Also note that if an average ROI time series is zero (which will occur
  when all voxel time series within it are zero and the '-allow_roi_zeros'
  is being utilized) and the user has asked for WB correlation maps with
  '-ts_wb_cor' and/or '-ts_wb_Z', no volume will be output for any ROI
  that is all-zeros.

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

Examples ~1~

  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

  3dNetCorr                                   \
      -inset REST_in_DWI.nii.gz               \
      -in_rois ROI_ICMAP_GM+orig              \
      -fish_z                                 \
      -ts_wb_corr                             \
      -automask_off                           \
      -all_roi_zeros                          \
      -prefix FMRI/out


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

  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.
____________________________________________________________________________
This page auto-generated on Thu Oct 31 09:42:20 PM EDT 2024