Softwares
All of the softwares below were developed or implemented by Cheol E. Han.
All softwares here are free softwares under the terms of the GNU General Public License pubished by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. However, please acknowledge the use of this software package.
Index
  • Permutation test for projection patterns:
  • Permutation test for correlation coefficients: Permutation based multiple comparion correction for correlation coefficients. This routine includes the extreme statistics and the cluster-based statistics.
  • FindCluser library: A MatLab library for finding clusters of edges or nodes.
  • Permutation test for group comparison: Permutation based multiple comparion correction for group comparison. The significance level computation routine was adjusted for connectivity data.
  • symMat library: A MatLab library for handling symmetrical brain networks.
  • drawBrain library: A MatLab library for drawing brain networks, measures of surfaces or nodes with a transparent brain.

  • Permutation test for correlation coefficients
    (2012-2013, Last Update: March 28, 2013)
    Description
    This is a MatLab library of permutation based multiple comparion correction for correlation coefficients. This routine includes the extreme statistics and the cluster-based statistics. Here, we briefly described the method and hot wo install and use with a simple example. For the thorough description, please refer the paper below.
    (related paper: Cluster-based statistics for brain connectivity in correlation with behavioral measures, CE Han, SW Yoo, SW Seo, DL Na, JK Seong, PLoS One)
    We present a cluster-based method for identifying sub-networks of brain connectivity that are correlated with behavioral measures. Our scheme aims to control the family-wise error rate (FWER) when mass-univariate testing is performed at every connection of the network. The proposed method takes as inputs a set of connectivity matrices for all subjects in a given group and their corresponding behavioral measures.
    The proposed method consists of two parts: correlation coefficient computation and cluster-based multiple comparison correction.
    In the former part, a partial correlation coefficient is calculated for each connection of the brain network with the behavioral measures. In this step, several compounding variables are taken as covariates in order to count their effects on the correlation coefficients.
    In the latter part, we perform cluster-based correction for the multiple comparison correction of the correlation coefficients by adopting the supra-threshold cluster size test. In this approach, clusters are constructed by grouping together neighboring supra-threshold connections, and the p-values are estimated through permutation testing. The output of this step is a set of sub-networks consisting of neighboring connections that are significantly correlated with the behavioral measures and the corresponding corrected p-values.
    In order to perform the extreme statistics, the greatest magnitude of the correlation coefficients were used as a representative statistic for each permutation vector. To identify positively correlated connections, we collected the maximum of correlation coefficients for each permutation vector, while for negatively correlated connections, we used their minimum values. We selected a single global threshold based on the distribution of extreme correlation coefficient. A significance level of each supra-threshold connection was estimated by locating observed correlation coefficients on the null distribution.
    Our scheme is independent of a specific method for constructing a connectivity matrix: both structural and functional connectivity can be used according to the desired purpose.
    If you find any error or have any suggestion, please let me know (mailto:Cheol E Han).
    How to install
  • Install MatlabBGL library.
  • Download the library.
    (This includes both symMat library and findCluster library below. You don't need to run them.)
  • Unpack anywhere you prefer.
    If you're using Linux:
    mv PermTestCorr.tar.gz /home/user/matlab/
    cd /home/user/matlab/
    tar -xzvf PermTestCorr.tar.gz
  • Launch matlab.
  • Add the paths where you unpack the library by typing the following in the matlab commandline.
    Or you may use the menu of the MatLab GUI.
    addpath /home/user/matlab/findCluster/
    addpath /home/user/matlab/symMat/
    addpath /home/user/matlab/PermTestCorr/
  • How to use
    PERM_TEST_CORR permutation test for correlation between two values.

    USAGE: [p...]=perm_test_corr('action',arguments);

    There are four actions: 'init', 'test', 'extreme', and 'cbs'
    'init'
    This action generates permutation vectors. This vector is used for test. We recommended to use 5000 or 10000 for the number of permitations.

    USAGE:perm=perm_test_corr('init',no_of_sujb, no_of_permutation);
    'test'
    Permutation test for each edge, computing correlation coefficients.

    USAGE:[results_perm]=perm_test_corr('test',network,measure,perm ...
    [,type_of_correlation, covariates]);

    where m is the number of subjects, and n is the number of edges.
    network
    m by n desquared connectivity matrix (see dsqrform in symMat Library)
    measure
    m by 1 column vector of behavioral measure to be correlated with edges. The order of scores should be the same as networks.
    perm
    generated permutation vector by 'init'action.
    type of correlation
    either Pearson (default) or Spearman
    covariates
    m by k behavioral measures like age, educations. (k covariates were considered using partial correlation coefficients) The order of scores should be the same as networks.
    The result_perm is a structure contained various results, where p is the number of generated permutations.
    perm
    [m x p]
    (permutation vector)
    no_subj
    m
    (the number of subjects)
    no_perm
    p
    (the number of permutations)
    no_edges
    n
    (the nubmer of edges)
    covariate
    [m x k]
    (used covariates)
    p
    [n x 1]
    (p-value estimated by the correlation function itselt)
    p_perm
    [n x 1]
    (p-value estimated by permutation test)
    r
    [n x 1]
    (correlation coefficients for edges)
    z
    [n x p]
    (correlation coefficients for all edges and permutations)
    If you want to use false discovery rate (FDR) procedure, you can use result_perm.p. We note that if an edge is zero for all subjects, the computed correlation coefficient is NaN and its p-value is set to 1.0.
    'extreme'
    extreme statistics. After finishing 'test' action above, the results+perm will be used as a input argument. You can select the alpha-level to control (default=5%).

    USAGE:[results_ext]=perm_test_corr('extreme',results_perm ...
    [,alpha_level]);

    The results_ext is a strucuture contained various results.
    rp_dist
    [1 x p]
    (distribution of the positive extreme value for each permutations)
    rp_th
    th_p
    (threshold for positve extremes)
    survived_p
    [i x 1]
    (index of i significant edges in the desquared vector)
    rn_dist
    [1 x p]
    (distribution of the negative extreme value for each permutations)
    rn_th
    th_n
    (threshold for negative extremes)
    survived_n
    [j x 1]
    (index of i significant edges in the desquared vector)
    To interpret the survived edge, you can use print_edge of symMat Library.
    idx=results_ext.survived_p; edge=[idx2edge(idx),results_perm.r(idx),results_perm.p(idx)]; print_edge(edge, label, {'r','uncorrected p'}
    'cbs'
    cluster-based statistics. After finishing 'test' action above, the results_perm will be used as a input argument.

    USAGE: [results_cbs]=perm_test_corr('cbs',results_perm, threshold);

    You can give multiple initial thresholds at once with a vector. The results_cbs is a cell array of structured results.The example below showed the case that two distinguish clusters were identified where they contains i edges and j edges respectively.
    t
    th
    (a used initial threshold)
    cluster
    {[ix2] [jx2]}
    (edges of clusters)
    no
    [i j]
    (the number of edges for each cluster)
    extent
    [p x 1]
    (cluster extent for each permutations)
    p_extent
    [pe_1 pe_2]
    (p-value for each cluster estimated with cluster extent distribution)
    maxx
    [p x 1]
    (cluster mass for each permutations)
    p_mass
    [pm_1 pm_2]
    (p-value for each cluster estimated with cluster mass distribution)
    To check the edge list of kth cluster of the first initial threshold, you may use the following code.
    results_cbs{1}.cluster{k}
    To interpret the edge, you can use print_edge of symMat Library.
    cluster=results_cbs{1}.cluster{k};
    idx=edge2idx(cluster,number_of_nodes);
    edge=[cluster,results_perm.r(idx),results_perm.p(idx)];
    print_edge(edge, label, {'r','uncorrected p'})
    Example
    I prepared a simple example, identifying sub-networks correlaetd with age, using the structural connectivity of healthy subjects (age between 4 to 40). We extracted the structural connectivity from DTI of the public Nathan Kline Institute (NKI) dataset. The detail of network extraction method, please refer the following paper ([free download])
    1. Load the prepared dataset (type the following lines in matlab commadline)

    load example

    This contains three variables: mat (82 by 82 by 121 matrix), scores (121 by 3 matrix). and labels (82 x 1 cell array). We used Deskian atlas which has 68 cortial areas along with 14 subcortical regions. Thus the number of nodes is 82 while n is the number of subjects. The variable scores contains [age, gender, intra cranial volume(icv)]. ICV was optained from the freesurfer. labels contains the name of each node in a cell array.
    2. Generate the permutation vector using 'init' action of perm_test_corr.

    perm=perm_test_corr('init', 121, 10000);
    3. Compute Spearman's partial correlation coefficients between each edge and age, counting the other scores as covariates. ('test' action of perm_test_corr.) To convert the connectivity matrix to a desquared format, we used dsqrform of SynMat library below

    mat=dsqrform(mat);
    results_perm=perm_test_corr('test', mat, scores(:,1), perm, 'spearman', scores(:,2:3));
    4. Identifying sub-networks with 'cbs' action of perm_test_corr. We will check the initial threholds between [-0.35:0.02:-0.25 0.2:0.02:0.3].

    results_cbs=perm_test_corr('cbs', results_perm, [-0.35:0.02:-0.25 0.2:0.02:0.3]);

    Then the code will display the following output.
    t=-0.350, min(p_extent)=0.000 max(no)=3, min(p_mass)=0.000 max(mass)=1.314
    t=-0.330, min(p_extent)=0.000 max(no)=4, min(p_mass)=0.000 max(mass)=1.644
    t=-0.310, min(p_extent)=0.000 max(no)=7, min(p_mass)=0.000 max(mass)=2.618
    t=-0.290, min(p_extent)=0.000 max(no)=14, min(p_mass)=0.000 max(mass)=5.033
    t=-0.270, min(p_extent)=0.000 max(no)=23, min(p_mass)=0.000 max(mass)=8.033
    t=-0.250, min(p_extent)=0.000 max(no)=52, min(p_mass)=0.000 max(mass)=16.477
    t=0.200, min(p_extent)=0.002 max(no)=29, min(p_mass)=0.002 max(mass)=6.859
    t=0.220, min(p_extent)=0.076 max(no)=5, min(p_mass)=0.047 max(mass)=1.297
    t=0.240, min(p_extent)=0.092 max(no)=3, min(p_mass)=0.073 max(mass)=0.777
    t=0.260, min(p_extent)= max(no)=, min(p_mass)= max(mass)=
    t=0.280, min(p_extent)= max(no)=, min(p_mass)= max(mass)=

    This showed the minimum of p-value from cluster extents and from cluster mass at the same time aloog with the number of edges in the largerst cluster. We note that p-value shown as 0.000 means that p-value is smllaer than 0.001. For 0.26<=t<0=.28, the code did erport no p-value, which means that it found no cluster.
    This result implies that there is strong negative correlation between edge weight and age: as age increases, there are sub-networks of which edge weights decrease.
    5. Check the p-values and the sizes of sub-networks with the initial threshold of -0.31. Becaise p-value shown here is all corrected already, if it is below 0.05, the cluster had significant negative correlation to age.

    results_cbs{3}.p_extent % to see p-values of sub-networks
    results_cbs{3}.no % to see the size of sub-networks
    6. Check edges of the largest cluster with the initial threshold of -0.31. The clusters of results_cbs structure are sorted in desending order of cluster sizes.

    cluster=results_cbs{3}.cluster{1};
    idx=edge2idx(cluster,82);
    edge=[cluster,results_perm.r(idx),results_perm.p(idx)];
    print_edge(edge, label, {'r','uncorrected p'})

    You will see the edges like this.
    lh.cuneus - lh.precuneus (r=-0.425433, uncorrected p=0.000001)
    lh.paracentral - lh.posteriorcingulate (r=-0.537506, uncorrected p=0.000000)
    lh.paracentral - lh.precuneus (r=-0.351226, uncorrected p=0.000090)
    lh.precuneus - lh.superiorparietal (r=-0.330067, uncorrected p=0.000246)
    lh.precuneus - rh.precuneus (r=-0.319896, uncorrected p=0.000390)
    rh.cuneus - rh.precuneus (r=-0.331242, uncorrected p=0.000233)
    rh.paracentral - rh.precuneus (r=-0.322830, uncorrected p=0.000342)
    Miscellaneous
    We are wroking on the GPU boosted version of this library. We are also interested in the threshold free Cluster Estimation (TFCE) for network edges.

    findCluster (2012-2013, Last Update: Feb 1, 2013)
    Description
    A MatLab library for finding clusters of edges or nodes using Breadth First Search (BFS) through matlabBGL. (related paper: Cluster-based statistics for brain connectivity in correlation with behavioral measures, CE Han, SW Yoo, SW Seo, DL Na, JK Seong, PLoS One)
    If you find any error or have any suggestion, please let me know (mailto:Cheol E Han) .
    How to install
  • Install MatlabBGL library.
  • Download the library.
  • Unpack anywhere you prefer.
    If you're using Linux:
    mv findCluster.tar.gz /home/user/matlab/
    cd /home/user/matlab/
    tar -xzvf findCluster.tar.gz
  • Launch matlab.
  • Add the paths where you unpack the library by typing the following in the matlab commandline.
    Or you may use the menu of the MatLab GUI.
    addpath /home/user/matlab/findCluster/
  • How to use
    find_cluster_node FIND_CLUSTER_NODE cluster of findings with respect to nodes, input 'fidings' should be in the level of nodes. This requires an adjacency matrix where it contains information of lay-out, which can be connectivity network, or spatial relationship. We include its test code.

    USAGE: clusters=FIND_CLUSTER_NODE(findings, adjacency);
    find_cluster_edge FIND_CLUSTER_EDGE cluster of findings with respect to edges. The input adjacency matrix contains findings in the form of a matrix. We include its test code.

    USAGE: clusters=FIND_CLUSTER_EDGE(adjacency);

    Permutation test for group comparison
    (2012-2013, Last Update: March 28, 2013)
    Description
    Will be avaiable soon
    How to install
    Will be avaiable soon
    How to use
    Will be avaiable soon

    symMat (2011-2013, Last Update: Mar 14. 2013)
    Description
    This is a MatLab library initially designed for handling symmetric matrix memory-efficiently. This now includes various useful functions for connectivity matrix. Here are the description of the functions.
  • 1) Most of brain connectivity from MRI (except effective connectivity) are symmetric because current MR techniques cannot record the direction of connections. So, keeping only half of a connectivity matrix (upper triangle or lower triangle) is useful for saving memories, and efficient comparison of edges. A few matlab toolbox followed this philosophy (pdist, squareform). Though my implementation of dsqrform (desquareform, makes a vector which includes elements of the upper triangle) is equivalent to squareform(X,'toVector') , This library can have extended functionality: it is applicable to cell or structure and can transform collapsed connectivity at once. (dsqrform, sqrform)
  • 2) The connectivity data itself is generally in the form of adjacency matrix. However, to use the sparse matrix tricks for improved computation time , we often need a list of edges. On the same manner, in the desquared matrix the index of edge is reqired for the sparse matrix tricks. Thus, the conversion between adjacency matrix, the list of edges, the index in the desquareformed connectivity. This conversion is easy but also easy to be errorsome. The library includes convrsion functions between them to prevent such stupid errors. (mat2edge, mat2idx, edge2mat, edge2idx, idx2mat, idx2edge)
  • 3) The set operation of edge pair set is useful. As an example, how many significantly different edges between A and B are in temporal lobe? Matlab set operation with 'rows' tag works great in most case (union, setdiff, intersect, setxor, unique, ismember). However, if the matrix is symmetric, symmetric edges are redundant (e.x. 1->3 and 3->1 are identical in symmetric matrix). The library includes a code to remove them. (unique_sym_edge)
  • 4) We need to interpret results in the form of edge pairs with the node (ROI) names. (print_edge)
  • The following functions in the library work fine with asymmetric matrix.
    mat2edge, edge2mat, unique_sym_edge, print_edge
    If you find any error or have any suggestion, please let me know (mailto:Cheol E Han) .
    How to install
  • Download the library.
  • Unpack anywhere you prefer.
    If you're using Linux:
    mv symMat.tar.gz /home/user/matlab/
    cd /home/user/matlab/
    tar -xzvf symMat.tar.gz
  • Launch matlab.
  • Add the paths where you unpack the library by typing the following in the matlab commandline.
    Or you may use the menu of the MatLab GUI.
    addpath /home/user/matlab/symMat/
  • How to use
    dsqrform DSQRFORM (desquareform) generates a vector of elements of the upper triangle. It accepts cell type. and 3-dim matrix (collaped connectivity matrix) (if the matrix is not a symmetric, elements in the diagonal and of the lower triangle will be ignored.)

    USAGE: out = dsqrform (in);
    It can handle a 3D input matrix (collapsed matrix) whose size is either n by n by m or m by n by n, where n is the number of nodes and m is the number of subjects. This function will make m by p matrix, where p=n*(n-1)/2.
    sqrform An extended version of a matlab function squareform .
    It generates a square matrix from a desquared vector. It accepts 2-dim collapsed matrix.

    USAGE: out = sqrform (in);
    The input matrix should be either a vector or m by p 2D matrix, where m is the number of subjects. The ourput matrix will be n by n by m matrix, where p=n*(n-1)/2.
    edge2mat
    edge2idx
    These functions will transform edges into adjacency matrix or the index of a desquared vector. The edge pair is a set of tuples [x y w], where x is the start node, y is the end node, and w is the edge weight. To transform edges to the others, the size of matrix (the number of nodes) is required.
    EDGE2MAT fills an adjacency matrix with edges' weights.
    EDGE2IDX returns index of edges in a desquared vector. All edges will be transformed to edges in the upper triangle. (Note: Edges on the diagonal will be ignored. The weight on the third column will be ignored.)

    USAGE: [mat, [vec] ] = edge2mat (edges ,n [,flag_sym]);
    vec: desquared vector of the matrix
    n: size of the matrix (required)
    flag_sym: treats edges are symmetric unique. default=0 (treats edges as asymmetric edges)
    USAGE: idx = edge2idx (edges, n);
    mat2edge
    mat2idx
    These functions will transform an adjacency matrix into edges or the index of a desquared vector.
    MAT2EDGE finds non-zero edges in matrix. (NOTE: appliable to asymmetric matrix.)
    MAT2IDX finds index of non-zero edges in a desquared vector. Weights will be ignored. (NOTE: non-appliable to assymetric matrix. for asymmetric, use mat2edge or idx=find(edge) )

    USAGE: edges = mat2edge (mat, [flag_w, flag_sym]);
    when flag_w ~= 0, the third column of edges has the weights (default=0)
    when flag_sym ~= 0, remove symmetric edges (asymmetric edges will remain, default=0)
    USAGE: [idx [,edges] ] = mat2idx (mat);
    idx2mat
    idx2edge
    These functions will transform the index in a desquared vector to an adjacency matrix or edges.
    IDX2MAT fill matrix with index of desquared vector. The matrix would be a symmetric square matrix.
    IDX2EDGE find edges from index of desquared vector.

    USAGE: [mat, [vec] ] = idx2mat (idx, n);
    USAGE: [edge] = idx2edge (idx, n [,flag_sym]);
    vec: desquared vector of the matrix
    n: size of the matrix
    flag_sym: 1:only edges in the upper triangle.
    unique_sym_edge UNIQUE_SYM_EDGE finds unique edges without symmetric edges. Edges in upper triangles will be preferred as an output.
    Except 1) the edge is on the diagonal, 2) the edge is directional (weight-dependent, third column of edge tuples are different)

    USAGE: edges = unique_sym_edge (edges); or
    [edges, lower] = unique_sym_edge (edges);
    lower: captures whether an edge in the unique set is not in upper triangle. (useful for directed edges with weights)
    print_edge PRINT_EDGE interprets edges throgh names of each node. If the edge tupe has more than 2 columns, the value of those columns will be followed by the edge tuples with their name. For example, the the third column contains t-statistics and the fourth column contains p-values, you can set style with {'t','p'}. The result will be "location_A - location_B (t=2.5, p=0.05)"

    USAGE: print_edge(edges, labels [,style]); or
    labels: The name of each node (should be cell type).
    style: The name of each column (should be cell type)

    drawBrain
    (2011-2013, Last Update: March 14, 2013)
    Description
    This program autosaves different views of the brain networks, measures of nodes or surfaces with a transparent brain borrowed from freesurfer. You can adjust size/color of nodes, thickness/color of edges, and color/transparency of surfaces.


    Visualization of a brain network. An image from Han et al. (2013). The labels were inserted after autosaving of figures in the program.



    Visualization of measures on the surface An image from unpublished work.

    Detail description will be avaiable soon
    How to install
    Will be avaiable soon
    How to use
    Will be avaiable soon

    Copyright (C) 2013
    All programs in this webpage are free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
    All programs are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
    SCBIA Lab. Korea University. Republic of Korea.