:orphan: .. _ahelp_3dECM: ***** 3dECM ***** .. contents:: :local: | .. code-block:: none Usage: 3dECM [options] dset Computes voxelwise eigenvector centrality (ECM) and stores the result in a new 3D bucket dataset as floats to preserve their values. ECM of a voxel reflects the strength and extent of a voxel's global connectivity as well as the importance of the voxels that it is directly connected to. Conceptually the process involves: 1. Calculating the correlation between voxel time series for every pair of voxels in the brain (as determined by masking) 2. Calculate the eigenvector corresponding to the largest eigenvalue of the similarity matrix. Guaranteeing that the largest eigenvector is unique and therefore, that an ECM solution exists, requires that the similarity matrix is strictly positive. This is enforced by either adding one to the correlations as in (Lohmann et. al. 2010), or by adding one and dividing by two (Wink et al. 2012). Calculating the first eigenvector of a whole-brain similarity matrix requires a lot of system memory and time. 3dECM uses the optimizations described in (Wink et al 2012) to improve performance. It additionally provides a mechanism for limited the amount of system memory used to avoid memory related crashes. The performance can also be improved by reducing the number of connections in the similarity matrix using either a correlation or sparsity threshold. The correlation threshold simply removes all connections with a correlation less than the threshold. The sparsity threshold is a percentage and reflects the fraction of the strongest connections that should be retained for analysis. Sparsity thresholding uses a histogram approach to 'learn' a correlation threshold that would result in the desired level of sparsity. Due to ties and virtual ties due to poor precision for differentiating connections, the desired level of sparsity will not be met exactly, 3dECM will retain more connections than requested. Whole brain ECM results in very small voxel values and small differences between cortical areas. Reducing the number of connections in the analysis improves the voxel values and provides greater contrast between cortical areas . Lohmann G, Margulies DS, Horstmann A, Pleger B, Lepsien J, et al. (2010) Eigenvector Centrality Mapping for Analyzing Connectivity Patterns in fMRI Data of the Human Brain. PLoS ONE 5(4): e10232. doi: 10.1371/journal.pone.0010232 Wink, A. M., de Munck, J. C., van der Werf, Y. D., van den Heuvel, O. A., & Barkhof, F. (2012). Fast Eigenvector Centrality Mapping of Voxel-Wise Connectivity in Functional Magnetic Resonance Imaging: Implementation, Validation, and Interpretation. Brain Connectivity, 2(5), 265-274. doi:10.1089/brain.2012.0087 Options: -full = uses the full power method (Lohmann et. al. 2010). Enables the use of thresholding and calculating thresholded centrality. Uses sparse array to reduce memory requirement. Automatically selected if -thresh, or -sparsity are used. -fecm = uses a shortcut that substantially speeds up computation, but is less flexibile in what can be done the similarity matrix. i.e. does not allow thresholding correlation coefficients. based on fast eigenvector centrality mapping (Wink et. al 2012). Default when -thresh, or -sparsity are NOT used. -thresh r = exclude connections with correlation < r. cannot be used with FECM -sparsity p = only include the top p% (0 < p <= 100) connectoins in the calculation cannot be used with FECM method. (default) -do_binary = perform the ECM calculation on a binarized version of the connectivity matrix, this requires a connnectivity or sparsity threshold. -shift s = value that should be added to correlation coeffs to enforce non-negativity, s >= 0. [default = 0.0, unless -fecm is specified in which case the default is 1.0 (e.g. Wink et al 2012)]. -scale x = value that correlation coeffs should be multiplied by after shifting, x >= 0 [default = 1.0, unless -fecm is specified in which case the default is 0.5 (e.g. Wink et al 2012)]. -eps p = sets the stopping criterion for the power iteration l2|v_old - v_new| < eps*|v_old|. default = .001 (0.1%) -max_iter i = sets the maximum number of iterations to use in in the power iteration. default = 1000 -polort m = Remove polynomial trend of order 'm', for m=0..3. [default is m=1; removal is by least squares]. Using m=0 means that just the mean is removed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. -mask mmm = Mask to define 'in-brain' voxels. Reducing the number the number of voxels included in the calculation will significantly speedup the calculation. Consider using a mask to constrain the calculations to the grey matter rather than the whole brain. This is also preferable to using -autoclip or -automask. -prefix p = Save output into dataset with prefix 'p' [default prefix is 'ecm']. -memory G = Calculating eignevector centrality can consume a lot of memory. If unchecked this can crash a computer or cause it to hang. If the memory hits this limit the tool will error out, rather than affecting the system [default is 2G]. Notes: * The output dataset is a bucket type of floats. * The program prints out an estimate of its memory used when it ends. It also prints out a progress 'meter' to keep you pacified. -- RWCox - 31 Jan 2002 and 16 Jul 2010 -- Cameron Craddock - 13 Nov 2015 -- Daniel Clark - 14 March 2016 ========================================================================= * This binary version of 3dECM is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 2. * The maximum number of CPUs that will be used is now set to .... 2. ========================================================================= ++ Compile date = Apr 18 2024 {AFNI_24.1.03:linux_ubuntu_16_64}