Assignment 2 (CS 4984: Computing the Brain)
Deadline: 11:59pm, March 18, 2022

The goal of this assignment is to implement the Louvain algorithm for hierarchical partitioning of weighted, undirected graphs and apply it to connectomes. You can find a complete description of this algorithm on pages 3 and 4 of Fast unfolding of communities in large networks. Feel free to refer to the textbook as well. Note that the matrix entry \(A_{ij}\) in the paper represents the weight of the edge between node \(i\) and \(j\). Equation (2) in the paper computes the change in modularity when an isolated node \(i\) is added to a module \(C\). You will have to figure out the analogue of this equation for the case when node \(i\) becomes isolated by its removal from its community. Do not examine any other source, especially any code that implements all or part of the algorithm. It an important experience for you to take the care and trouble to implement and test the algorithm yourself. You can use any programming language you want. Feel free to use matrix or graph libraries that already implement helpful classes and functions, e.g., to read and store graphs. Work on this assignment individually.

Implementing the algorithm in stages will be helpful. First, you will need a function to compute the modularity of any partition of the nodes. Then you may want to implement a function to implement the first phase of the algorithm, i.e., that finds a high-modularity partition of the current graph. This function could use a naive way to compute the modularity. Once you have debugged and tested this version, you can make it more efficient, by implementing equation (2) and its analogue to compute the change in modularity efficiently. Finally, you can implement the second phase of the algorithm and use it to compute a hierarchical decomposition of the network.

Remember to test your code. I do not mean writing unit tests, although you are free to do so. By testing, I mean running the code on simple graphs for which you know the correct answer.

Your software should print out

1. the number of seconds your implementation took to compute the complete hierarchical decomposition.
2. the number of levels in the hierarchical decomposition,
3. the level index with the largest modularity and the modularity at that level,
4. for each level, the modularity of the partition at that level and the number of communities at that level.

Apply your implementation to the following brain connectomes:

1. the coactivation graph from "Cognitive relevance of the community structure of the human brain functional coactivation network", Crossley et al, PNAS, 2013.
2. Macaque cortex, abbreviated "MC" in The small world of the cerebral cortex.
3. The fve30 version of the macaque visual cortex, abbreviated "MVC" in The small world of the cerebral cortex.
4. Macaque large-scale visual and sensorimotor area corticocortical connectivity from Network structure of cerebral cortex shapes functional connectivity on multiple time scales by Honey et al.
5. The cj.all version of the connectome of the cat cortex abbreviated "CC" in The small world of the cerebral cortex.
6. The weighted and directed interareal connectome for the macaque cerebral cortex used in Cortical High-Density Counterstream Architectures. You can assume that this graph is undirected for this assignment.

Modularity maximisation challenge. I will award a gift certificate to the student who achieves a consistently-higher modularity, say at least 10% larger, than all the other students. To this end, you can extend the Louvain algorithm by implementing your own heuristics and optimisations, e.g., ideas we discussed in class such as splitting a partition, allowing some swaps that allow the modularity to decrease, or consider pairs of nodes \(i\) and \(j\) that are in the same module but are connected by an edge in the graph. There are literally dozens of ideas you can try, so do not go overboard. Keep in mind the admonition in Figure 9.2.1 of the textbook about the degeneracy of modularity maximisation. I reserve the right to request code, split this award, change the criterion for success, or make no award.