INSTALLATION


Download and install a copy of Octave (3.4.0 or above):
http://www.gnu.org/software/octave/download.html

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
http://www.java.com/en/download/help/path.xml

muxViz requires R v3.0.2 (or above). Download and install a copy of R from
http://www.r-project.org/

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

install.packages("sp")
install.packages("rgdal")

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:

sudo apt-get g++
sudo apt-get gfortran

and then you can proceed with installation of R and Octave:

#download Octave and R from their repository
wget http://ftp.gnu.org/gnu/octave/octave-3.6.0.tar.gz
wget http://cran.es.r-project.org/src/base/R-3/R-3.2.0.tar.gz
DIR=$PWD

#install Octave
sudo apt-get build-dep octave
sudo mv octave-3.6.0.tar.gz ~
cd ~
tar xvf octave-3.6.0.tar.gz
cd octave-3.6.0
./configure
make
sudo make install
cd $DIR

#install R
sudo apt-get build-dep r-base-core
sudo mv R-3.2.0.tar.gz ~
cd ~
tar xvf R-3.2.0.tar.gz
cd R-3.2.0
./configure
make
sudo make install

#install GDAL
sudo apt-get install libgdal1-dev libproj-dev


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:

source('muxVizGUI.R')

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.


Troubleshooting

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.


USAGE


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;label_layer_X;layout_layer_X

where:

Each line in the configuration file indicates one layer, and the network format for each layer will be "standard edges list" (see below).


Non-edge-colored networks

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;path_to_layers_info;path_to_layers_layout

where:

In this case the network format will be "extended edges list" (see below).


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).
For instance:

1 2 0.5
1 3 1.4
...
18 124 0.1
is a typical weighted edges list.

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:

alice bob 0.5
alice charlie 1.4
...
john david 0.1

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:

nodeID nodeLabel
1 alice
2 bob
3 john
4 david
...


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:


1 1 2 1 0.5
1 1 3 1 1.4
...
18 2 124 2 0.1

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:

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:

The order of the columns should not be relevant.


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:

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:

ffmpeg -r 1 -i /path/xyz_%05d.png -c:v libx264 -pix_fmt yuv420p -r 25 output_file.mp4


OTHER SCRIPTS INCLUDED


muxViz v0.1 (CLI)

Usage from shell command line (no support to GUI and no longer developed):

R CMD BATCH muxViz.R

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.



VIDEO TUTORIAL



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.