Add a method

Adding a method is simply about placing the right files at the right place. First, locate your METHOD_DIR folder, methods by default. Add a folder for your method. In this folder, place whatever files are needed for your method to be run : scripts, binaries, etc. Then, add an execute.sh file in this folder. This file will be detected by the program in order to reference your method (you may update the whitelist right away). During the execution of CoDACom, execute.sh will be run from the directory of your method. It is therefore the script that will input a graph, run your method, and output a clustering.

It is advised to include template.sh, located in the method folder, at the start of your execute script. It will handle input arguments, add a help function and process options. If you prefer keeping complete control you may not include this script, but you should try to replicate its behaviour with the options (for instance, the GUI runs execute.sh -d to get the description of the method, and does not expect to actually run the method).

The template produces the INPUT_GRAPH variable, a path to the input graph in an edgelist format. It also creates the OUTPUT_CLUST variable, that is the path to the output file that the script should produce. The format of these files are described there.

If the input and/or output format of your program do not correspond to the internal format of CoDACom, a few scripts are available for format conversion in TOOLS_DIR. If those do not match your needs, you may contact us so that we can extend CoDACom to be more useful.

Note that the methods/scrap_web.sh script enables us to get implementations of community algorithms from the web without distributing them. If you want to distribute your code in that way, you can take a look at the script itself.

Add a quality function/comparison method

Since quality functions are in the large majority simpler than community detection algorithms, we used a more standard OOP-centric approach for extension. To create a new quality function, one will need to :

  • implement it in a C++ class (using the igraph library)
  • reference it in the Quality Function Provider (QFProvider)
  • add it to the build list

Implementation

The working directory is, by default, src/libquality. All the Quality Functions (QFs) are available in the quality/ subfolder. The process of creating a new QF will vary depending on its scope :

  • A global QF is the most straightforward. One only need to extend AbstractQF, and fill in the constructor (by giving a name and a description), and two functions. The first, "apply", is the main function. It imputs a graph and a related membership vector, where keys are vertex ids and values are cluster ids. The second, "single_apply", is optionnal (return -1 if it is not relevant).
  • A Single-Cluster Quality Function (SCQF) is implemented by extending AbstractSCQF. Only the constructor and the apply function need to be overwritten. The apply function recieves as input, on top of the previous ones, the cluster on which to do the computation as well as its id.
  • A Single-Vertex Quality Function (SVQF) is implemented by extending AbstarctSVQF. One again, only the constructor and the apply function need rewriting.

Referencing

Once the new class is done, one need to reference it in the provider (the class QFProvider is available in src/libquality). The constructor of QFProvider instanciates an object from all QF classes. If a SCQF was made, one need also to wrap it with an AgglomerativeQF, e. g. MeanQF or SumQF, that respectively take the mean and the sum of the cluster's value as the global quality. It it is a SVQF, the default behaviour is simply to take the average over all nodes. Warning : by default, the SVQFs are sampled, the number of samples can be set in AbstractSVQF.hpp.

Building

In order to make the class available as a binary, it needs to be be referenced by the Automake build system. Two files have to be updated (in src/libquality) : targets_libquality (referencing the .cpp files) and headers_libquality (referencing the .hpp files).

Comparison methods

Comparison methods follow the same structure, with the notable exception that multiple scopes do not exist. All the corresponding files may be found in src/libcomparison.