The MutliTensor is a library for multilayer network tensor factorization that can be used for community detection, link prediction, and to measure layer interdependence.
The project is written in C++ and includes
- the main library
- the Python extension
- the tests
- the benchmark
- the documentations
- Boost libraries
- CMake for building the project
- Python 3.6+ and Numpy for building the Python bindings and running the benchmark
- Doxygen for generating the main documentation
- Sphinx for generating the documentation for python extension
To configure the project, simply type in:
$ cd $MULTITENSOR_SRC_DIR
$ mkdir build
$ cd build
$ cmake -DBOOST_ROOT=$BOOST_PATH -DCMAKE_BUILD_TYPE=$BUILD_TYPE ..
where
$MULTITENSOR_SRC_DIRis the root of this repository$BOOST_PATHis the location of theBoostlibraries (e.g./path/to/boost_libraries/boost_1_74_0/include)$BUILD_TYPEis the configuration you wish to build (usuallyReleaseorDebug)
Two addiotinal options can be specified for the configuration:
ENABLE_PYTHON_WRAPPERto enable the Python extension (ON/OFF, default isON)ENABLE_BENCHMARKto enable the benchmark (ON/OFF, default isON)
You can then build the targets by running from the same directory
$ make
Please, make sure that you have all the necessary dependencies installed before running the configuration. If you modify yoru environment, please re-configure the project before building the targets.
A binary Multitensor is provided to use the C++ implementation.
Use the help option to obtain more details about the binary:
$ ./Multitensor --help
You can run it against the examples provided in the data folder
in the source repository, for instance:
$ ./Multitensor --a $MULTITENSOR_SRC_DIR/data/main/adjacency.dat --k 2
By default, the results of the algorithm are written in the results folder.
A Python extension built with Cython is also provided. First, create a virtual environment and install the necessary packages:
$ python3 -m venv --copies my_venv
$ ./my_venv/bin/activate
$ pip install -U numpy cython # cython is optional
$ cmake -DBOOST_ROOT=$BOOST_PATH -DCMAKE_BUILD_TYPE=$BUILD_TYPE ..
You can then build the extension:
$ make multitensor_py
To use the extension, you can for instance do the following:
import multitensor
adjacency_file = '$MULTITENSOR_SRC_DIR/data/main/adjacency.dat'
num_groups = 2
u, v, affinity, report = multitensor.run(adjacency_file, num_groups, seed=10, nof_realizations=10)The API is described in the Sphinx documentation which can be built the following way:
$ pip install -U sphinx sphinx-bootstrap-theme
$ cmake -DBOOST_ROOT=$BOOST_PATH -DCMAKE_BUILD_TYPE=$BUILD_TYPE ..
$ make sphinx
The multilayer adjacency matrix should be formatted as an edge list with L+3 columns:
node1 node2 3 0 0 1
- The first and second are the labels source and target nodes of that edge, respectively
- The remaining columns represent the edge weight in each layer
In the example above the edge node1 --> node2 exists in layer 1 with weight 3 and in layer 4 with weight 1, but not in layer 2 and 3.
Four files will be generated inside an output folder (by default named results):`
- some information about the run of the algorithm
- the NxK membership matrix
U - the NxK membership matrix
V - the KxK layer affinity matrix
W
For the membership matrices, the first column is the node label and the following ones the membership vector entries.
As for the affinity matrix, it is organized in blocks separated by an empty line. Each block starts with the layer number followed by the matrix for that layer. For the assortative version only the diagonal entries of the affinity matrix are printed. The first entry of each row is the layer index.
The main documentation is written with Doxygen. It can be built the following way:
$ make doxygen
Once the project is built, just type
$ make test
This will run the unit tests and the functional tests, also for Python if the extension is enabled.
To run the benchmark reproducing the results in Table III from the paper,
run from the build directory:
$ cd benchmark
$ python benchmark_runner.py --help
$ python benchmark_runner.py --test $TEST_NAME
The MutliTensor implements the algorithm described in:
De Bacco, C., Power, E. A., Larremore, D. B., & Moore, C. (2017). Community detection, link prediction, and layer interdependence in multilayer networks, Physical Review E, 95(4), 042317.
If you use this code please cite this article. A preprint version can be found here or here.
GNU GPL version 3 (see LICENSE.md)
(c) 2019, Max Planck Society / Software Workshop - Max Planck Institute for Intelligent Systems