Download and install a copy of Octave (3.4.0 or above):
Octave should be accessible through command line from any folder (i.e., it is mandatory to add it in your PATH environment variable).
If you are not familiar with this simple task, you should visit
muxViz requires R v3.0.2 (or above). Download and install a copy of R from
Some external packages are required within the R environment. However, the main script should be able to detect the missing packages and install them, automatically. Therefore, it is likely that you do not need to install them by yourself.
You can download muxViz from Github: https://github.com/manlius/muxViz/archive/master.zip
To work properly with geographical networks, the GDAL (Geospatial Data Abstraction Library) is required and should be installed before running muxViz for the first time. GDAL should be available as an R package and should be easily installed just by typing
within the R environment. However, in a few cases it can be more complicated and some users reported problems for its installation. If this is also your case you might want to take a look at some suggestions on stackoverflow (Read on stackoverflow) or on this blog (Read on spatial.ly). In any case, it is highly recommend to visit the GDAL website and follow the hints provided there (go to GDAL official website).
Very quick installation on Linux
If you use a Linux (Ubuntu-like) distribution, you are very lucky, because the following BASH script will do the job for you.
Before installing muxViz be sure that you have the gcc suite installed. If you are not sure, do:
and then you can proceed with installation of R and Octave:
Finally, if your system has a working installation of Octave, R and GDAL, you can download the last version of muxViz, unzip it and type the following within R environment:
This should be enough. The script will check for the required packages and will try to automatically install the missing ones. The whole process might take a few minutes, the first time you run muxViz.
Please, if you have any problem during the installation of muxViz, visit the dedicated Google Group or check the TROUBLESHOOTING.md file before asking for help: you might find the solution faster.
If you find a smart solution to an installation/usage issue, feel free to send me an email and I will add your solution to the TROUBLESHOOTING.md file.
Format of an input file
The configuration file is a ASCII file including the list of layers to be included in a multiplex, the corresponding labels and the possible layout file to define node properties (e.g., ID, labels, geographic coordinates, etc).
Format of a configuration file:
- path_layer_X: [mandatory] specify the path and the filename to the edges list to be used as layer
- label_layer_X: [optional] specify the label to be used in the rendering for that layer
- layout_layer_X: [optional] specify the path and the filename to the file containing information about nodes
If the multilayer is not edge-colored (i.e., inter-links are allowed), only one line is specified in the configuration file, with format:
- path_multilayer: [mandatory] specify the path and the filename to the extended edges list to be used
- path_to_layers_info: [mandatory] specify the path and the filename to the file containing information about layers
- path_to_layers_layout: [mandatory] specify the path and the filename to the file containing information about nodes
Standard edges list
A typical edges list is expected to be a file with at most three columns, giving the list of edges from a node (first column) to other nodes (second column), possibly weighted by an integer or floating number (third column).
IDs of nodes are expected to be sequential integers (starting from 0 or 1, up to the number of nodes in the network). Nevertheless, it is possible to import label-based edges list, where the IDs of nodes are labels (arbitrary integers or strings): in this case, one should check the appropriate box before importing the networks, to let muxViz know how to interpret the format.
The edges list could look like:
In this specific case, it is mandatory to provide a layout file (see next section) reporting the sequential node ID (field nodeID) to be assigned to each node label (field nodeLabel).
This would look like:
Extended edges list
An extended edges list is a new format that allows to specify all possible types of links, intra- and inter-layer. Each line specifies the source node (first column) and the source layer (second column), the destination node (third column) and the destination layer (fourth column), possibly weighted by an integer or floating number (fifth column). For instance:
is a typical weighted extended edges list. For label-based extended edges lists, the same rules of the standard edges lists apply
Format of a layout file
The first line of the file must specify the name of the correponding node attributes. Allowed attributes:
- nodeID: [mandatory] numerical integer id to identify each node
- nodeLabel: [optional] string specifying the label attribute
- nodeX: [optional] float value specifying the Cartesian coordinate x for the layout
- nodeY: [optional] float value specifying the Cartesian coordinate x for the layout
- nodeLat: [optional] float value specifying the latitude for the geographic layout
- nodeLong: [optional] float value specifying the longitude for the geographic layout
The order of the columns should not be relevant. If nodeLat and nodeLong are specified, they will be automatically converted to Cartesian coordinates (through Mercator projection).
The properties of each node in the multilayer must be specified or default values will be used (i.e., automatic labeling and layouting). If the number of nodes in the network is different from the number of nodes provided in the layout file, it will be assumed that something is wrong with the layout file and default values will be used.
Format of a layer-info file
The first line of the file must specify the name of the correponding layer attributes. Allowed attributes:
- layerID: [mandatory] numerical integer id to identify each layer
- layerLabel: [optional] string specifying the label attribute
Format of a timeline file
This module allows to build nice animated visualizations corresponding to dynamical processes on the top of a multilayer network. For instance, one can visualize the movements of one (or more) random walker(s) in the network, or the spreading of an epidemics or of a meme in a social network, the traffic (and possible congestions) in a transport/communication network, etc.
The idea is to feed the module with a 'timeline' file where the change of the state of nodes and edges in the multilayer network are specified at each time step. The 'state' of an object can be altered by changing its color and/or its size. For instance, in the case of an epidemics spreading in a country, the size of each node (e.g., a metapopulation describing a city) can be proportional to the population and the color can encode the amount of infected people. This description allows a wide variety of dynamics to be represented and visualized: for instance, setting the size of nodes and edges to zero when required, it is possible to visualize a time-varying multilayer network where nodes and edges appear or disappear over time.
The first line of the file must specify the name of the correponding timeline attributes. Allowed attributes:
- timeStep: [mandatory] numerical integer id to identify time steps
- labelStep: [mandatory] string specifying the snapshot label
- entity: [mandatory] string specifying if the object to modify is 'node' or 'edge'
- layerID: [mandatory] numerical integer id to identify each layer
- nodeID: [mandatory] numerical integer id if entity is 'node' and string (e.g., '3-7', corresponding to the link from node 3 to node 7) if entity is 'edge'.
- color: [mandatory] string specifying the color to be assigned
- sizeFactor: [mandatory] float value specifying the relative size of the entity, scaling with respect to the default size
The order of the columns is not relevant. If the network has L layers and you want to include the aggregate network in the visualization, then use L+1 in the layerID field for it.
To keep users with the freedom to use their favorite video making software, the output of muxViz consists of png files representing the temporal snapshots of the dynamics. Snapshots are saved in the folder 'export/timeline/project_name'. Successively, users can use their favorite software to merge the sequence of snapshots into a single video. We recommend to use FFmpeg with the following parameters:
OTHER SCRIPTS INCLUDED
muxViz v0.1 (CLI)
Usage from shell command line (no support to GUI and no longer developed):
If used with the default options for the first time, muxViz will plot a multiplex with 100 nodes and 4 layers with community-like topology. The output should be a file 'muxViz.png' in the same folder, similar to 'muxViz_example.png' provided with the package.
Please, explicitly cite muxViz if you find it useful for your visualizations.
If you use muxVizGUI for your data analysis, please, cite the relevant papers where all descriptors and diagnostics are defined: you will find a quick help with references to relevant papers in all pages dedicated to data analysis.
monoxViz v0.1 (CLI)
Support the visualization of classical single-layer networks (no longer developed).
The muxViz package now includes a script for the visualization of standard networks. It supports both 2D and 3D layouting with openGL, it is fully integrated with OpenStreetMap and preserves all the features developed to customize visualizations with muxViz.
muxViz Tutorials: Learning muxViz in 10 minutes
muxViz Tutorials: Visualization of Multilayer Networks
muxViz Tutorials: Visualization of Geographic Multilayer Networks
muxViz Tutorials: Multilayer Centrality Analysis
Please, note that voice commenting the steps is still missing. We are working about that.