View on GitHub


Community Detection Research Effort

Download this project as a .zip file Download this project as a tar.gz file

Circulo: A Community Detection Evaluation Framework


Contributors welcome! If you want to contribute, please issue a pull request.


The Framework:

Circulo is a "Community Detection" Evaluation Framework written primarily in Python. The Framework performs statistical analysis against partitions of a Graph resulting from the execution of a given community detection algorithm. The resulting quantitative measures can be used to drive experiments such as measuring algorithm efficacy against specific dataset types or comparing different algorithm execution results against the same dataset. The framework includes the following components:

The Research

Prior to building the Circulo framework, Lab41 conducted a market survey into Community Detection algorithms and metrics. The survey was used to guide the development of Circulo. The survey includes, but is not limited to, summaries of algorithms, references to academic literature, and general information about the field. The survey can be found here:

The Underlying Graph Framework

Since we did not want to reimplement the notion of a graph, we decided to pick an existing Graph Framework as a backdrop for our work. Though any of the popular graph frameworks could have been used, iGraph was chosen as our primary graph framework. iGraph offers a number of features:

Other frameworks which could be used include GraphX, GraphLab, SNAP, NetworkX.

Installation and Setup

Package Requirements


Below are instructions for using Circulo

#clone Circulo repository (note: this also clone SNAP)
git clone --recursive
#set PYTHONPATH env variable
export PYTHONPATH=/path/to/Circulo
#make the snap code base
pushd lib/snap; make; popd

Running the Evaluation Framework

At the core, the evaluation framework run various community detection algorithms against various datasets.

#To run your algorithms against the data
python circulo/setup/run_algos [parameters ...] 
#To run metrics against the results of run_algos
python circulo/setup/run_metrics [parameters ...]


Appendix A: iGraph Installation

sudo apt-get install igraph
sudo apt-get install libxml2-dev libz-dev python-dev
#using brew install igraph dylibs
brew install homebrew/science/igraph

#install Cairo
#installs the core libraries for cairo
brew install cairo 

#installs the python site-packages. NOTE: pip does not work for pycairo. 
#If you want to use pip, create sym links to the site packages in brew
brew install py3cairo

#install python igraph
pip3 install python-igraph