:orphan: .. _ahelp_3dNetCorr: ********* 3dNetCorr ********* .. contents:: :local: | Overview ======== .. code-block:: none 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 ===== .. code-block:: none 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 ====== .. code-block:: none 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 ======= .. code-block:: none 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 ======= .. code-block:: none -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 ===== Re. Allowing zero-filled ROIs ('-allow_roi_zeros') ++++++++++++++++++++++++++++++++++++++++++++++++++ .. code-block:: none 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 ======== .. code-block:: none 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.