7.1.109. 3dNetCorrΒΆ

Link to classic view

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

    • 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 = 0.5 ln( [1+r]/[1-r] ) ,

(with zeros being output along matrix diagonals where r=1).

-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 (PBC) 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.9999999999999999 (where Z~18.71; hope that’s good enough). Files are labelled WB_Z_ROI_001+orig, etc.
-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’.
-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.


Table Of Contents

This Page