Connectome harmonics

README.md

@@ -1,21 +1,41 @@
 # Surface and Connectivity Reconstruction: Imaging Pipeline for TVB Simulations
-## SCRIPTS 0.4.1
+## SCRIPTS 0.4-CH
 
 Please see the [wiki](https://github.com/ins-amu/scripts/wiki)
 
-#### New in 0.4.1:
-- Remove need for Matlab
-- new subparcellation scheme where arbitrary number of subregions can be chosen
+If using SCRIPTS, please cite this work:
+Proix T, Spiegler A, Schirner M, Rothmeier S, Ritter P, Jirsa, VK. How do parcellation size and short-range connectivity affect dynamics in large-scale brain network models? NeuroImage, 2016, 142:135-149 \[[link](https://www.sciencedirect.com/science/article/abs/pii/S1053811916302518)\]
 
-#### New in 0.4:
+If using the Connectomer Harmonics add-on, please cite:
+Naze S., Proix T., Atasoy S., Kozloski J. R. (2020) Robustness of connectome harmonics to local gray matter and long-range white matter connectivity changes. NeuroImage \[[link](https://www.sciencedirect.com/science/article/pii/S1053811920308508)\]
+
+
+#### Connectome Harmonics release:
+- Compute high-resolution connectome based on tracks - surface mesh intersections (requires MATLAB Parallel Computing Toolbox).
+- Compute eigenvalue/eigenvector pairs of combined local and long-range connectivity matrices.
+- Compute Mutual Information of 100 harmonics (of lowest eigenvalues) with the Default Mode Network.
+- To perform: after running `main_surface.sh`, run `main_CH.sh`.
+- Template connectome harmonics for surfaces *cvs\_avg35\_inMNI152*, *fsaverage4* and *fsaverage5* using the [Gibbs tractography streamlines](https://www.nitrc.org/projects/gibbsconnectome) is now [available on zenodo](https://zenodo.org/record/4027989)
+
+
+#### Connectome Harmonics dependencies
+Install the following packages in the matlab_utils folder:
+- Toolbox graph <https://www.mathworks.com/matlabcentral/fileexchange/5355-toolbox-graph>
+- CBrewer colormaps  <https://www.mathworks.com/matlabcentral/fileexchange/34087-cbrewer---colorbrewer-schemes-for-matlab>
+- Export_fig <https://www.mathworks.com/matlabcentral/fileexchange/23629-export-fig>
+- TriangleRayIntersection <https://www.mathworks.com/matlabcentral/fileexchange/33073-triangle-ray-intersection>
+- SmoothPatch <https://www.mathworks.com/matlabcentral/fileexchange/26710-smooth-triangulated-mesh>
+- Subtightplot <https://www.mathworks.com/matlabcentral/fileexchange/39664-subtightplot>
+
+#### NEW in 0.4:
 - Dockerfile for easy installation with Docker.
 - Tests. 
 - Reorganization and simplification of the code => compatibility with tvb-make.
 - 4 new parcellations: Destrieux, HCP-MMP1, Yeo7 and Yeo 17.
 
 #### Features
 - prepare data for TVB: surface reconstruction, region mapping, connectome.
-- mrtrix 3.0 RC3: SIFT/SIFT2, ACT, 3 types of registration structural/diffusion, denoising, topup/eddy corrections, bias field corrections, mask upsampling and dilatation, multi-shell multi-tissue, dhollander algo, fsl subcortical structure parcellation, tractogram and tdi generation, multi-threaded.
+- mrtrix 3.0 RC2: SIFT/SIFT2, ACT, 3 types of registration structural/diffusion, denoising, topup/eddy corrections, bias field corrections, mask upsampling and dilatation, multi-shell multi-tissue, dhollander algo, fsl subcortical structure parcellation, tractogram and tdi generation, multi-threaded.
 - automatic config checks.
 - convenience script for HCP datasets.
 - handle automatically reverse phase-encoding DWI in most cases.
@@ -27,10 +47,6 @@ Please see the [wiki](https://github.com/ins-amu/scripts/wiki)
 This poject use the MIT License.
 The full license is in LICENSE.txt in the SCRIPTS distribution.
 
-Copyright (c) [2014] [The SCRIPTS Developers]
-
-#### How to cite
+Copyright (c) [2014-2020] [The SCRIPTS Developers]
 
-When citing SCRIPTS, please cite this work:
 
-Proix T, Spiegler A, Schirner M, Rothmeier S, Ritter P, Jirsa, VK. How do parcellation size and short-range connectivity affect dynamics in large-scale brain network models? NeuroImage, 2016, 142:135-149

config_CH.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# This is the separate  config file for computing connectome harmonics
+# It assumes the main SCRIPTS config file has been set up and the main_surface.sh ran without errors.
+
+# By default, the routine compute subject specific harmonics based on all the tracks computed by the tractography
+
+
+#######################
+## Setup environment ##
+#######################
+
+# Path to SCRIPTS root directory
+export SCRIPTS_DIR=`pwd`
+
+# Path to Matlab Utils (for dependencies)
+export PMU=$SCRIPTS_DIR/matlab_utils/
+
+# number of parallel cores to compute high-resolution connectome (different than NTHREADS because more memory consuming)
+export NWORKERS=4
+
+

example_config.sh

@@ -31,6 +31,14 @@ export PRD=/path_to_root_dir/
 # this will determine the name of your subject in the final directory
 export SUBJ_ID=name_subj
 
+# Matlab path if you have it
+# export MATLAB=/path_to_matlab/
+export MATLAB=$(which matlab)
+# if you don't have matlab, download and install the MCR (linux 64 bits) here: 
+# http://www.mathworks.com/products/compiler/mcr/index.html
+# and uncomment the following line
+# export MCR=/path_to_matlab_runtime_compiler/
+# export MCR=/usr/local/MATLAB/MATLAB_Runtime/v93
 
 #### Standard options
 
@@ -83,14 +91,13 @@ export REGISTRATION="regular"
 export REGION_MAPPING_CORR="0.42"
 
 # for computing subconnectivity
-# if you want subdivided parcellations, you can a list of how many
-# regions you want for each parecellations.
-# Subparcellations will be based on subdiving the existing parcellation
-# in more regions, with the constraints of minimizing the difference between 
-# subregion sizes across all subregions
+# if you want subdivided parcellations, you can set the folowing value
+# according to the following table
+# K:                 0   1   2    3    4    5
+# Number of Nodes:  70  140 280  560  1120 2240
 # default: ""
-# Needs to be a list of even integers
-export N_SUBREGIONS_LIST="100 200"
+# Needs to be a list of integers
+export K_LIST="0 1 2 3 4 5"
 
 # number of tracks used in the tractography step.
 # default: 10.000.000

main_CH.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+source config_CH.sh
+
+#####################################
+## Convert tracks into ascii files ##
+#####################################
+if [ ! -d $PRD/connectivity/tmp_ascii_tck ]; then
+  mkdir -p $PRD/connectivity/tmp_ascii_tck
+  echo "exporting tracts in ascii... this can take a while"
+  tckconvert $PRD/connectivity/whole_brain_post.tck \
+             $PRD/connectivity/tmp_ascii_tck/output-[].txt \
+             -scanner2voxel $PRD/connectivity/brain_2_diff.nii.gz \
+             -nthreads "$NB_THREADS"
+fi
+
+#######################################
+## Run Connectome Harmonics pipeline ##
+#######################################
+echo "Run Pipeline matlab routine..."
+$MATLAB -r "run CH_pipeline_integrated.m; quit;" -nodesktop