Transmissio

A program to visualize temporal graph data (network) combined with geographic information (node coordinates). It provides a straightforward tool for representing network data in an interactive way, in the form of static or dynamic visualization.

In addition to being an open-source project, this program has been designed using Processing to be easily and highly customizable. In this page you should find all the informations needed to download, install and use the program.

Sources of the program are available through a Git repository on GitLab: https://gitlab.com/gaelbn/transmissio. You can download or clone the project using this link.
Pre-compiled executables can be downloaded through the GitLab project repository (but without any performance guarantee, as it has not been tested on all platforms).

Two options are available, use one of the pre-compiled executables or run the program directly in Processing. The first solution is certainly the most straightforward, but the second is more likely to work properly.

Pre-compiled executables are provided for the most common OS (Linux, Mac OS X and Windows). Just choose the one that is appropriate for your system and download it. You will have to install the latest version of java 8, except for Mac Os X for which a version of the program embedding java is provided.

Install Processing (version 3.5.3 or later). You can download it from the Processing website. Then, download the sources by cloning the git repository or by downloading the archive containing the files.

The data must be provided as two separate files in csv format, corresponding to the edge list and node coordinates. A third file containing the visual parameters must be provided in order to customize the appearance of the visualization.

A multi-line adjacency list format is used for graphs representation. File must contains four columns: source_id, destination_id, date and weight, whose order must be respected. First and second columns correspond, respectively to the source and destination nodes, third column contains temporal information (date or time-step the contact occured), and the last column (the fourth) contains the edge’s weight. Take care that there is no way of representing isolated nodes unless the node has a self-loop edge. The default name for this file is network.csv, but you can choose the name you want and specify it in the configuration file.
The dates will be automatically converted into time-steps to save computation time. Five temporal scale conversion are already implemented: year, month, week number (week_num), period of seven days (seven_days) and day. You can also implement your own.
It is required to provide the dates in format ISO 8601, in the extended format. Calendar date representations are in the form ‘YYYY-MM-DD’, where [YYYY] indicates a four-digit year, 0000 through 9999. [MM] indicates a two-digit month of the year, 01 through 12. [DD] indicates a two-digit day of that month, 01 through 31. For example, ‘8 May 2019’ have to be represented as ‘2019-05-08’. You can also directly provide time-step instead of date and indicate it in the configuration file (temporal_scale, timestep), assuming you did the conversion yourself.

A csv file giving the node id, longitude and latitude of the nodes in the network. File must contains the three columns: node_id, coord_longitude, coord_latitude, whose names must be respected. The default name for this file is coord.csv, but you can choose the name you want and specify it in the configuration file.
The equirectangular projection (or equidistant cylindrical projection) is used as map projection. The nodes coordinates (WGS84/GPS, in decimal degrees ‘DD’) are transformed in Cartesian coordinates, based on the center of the area to draw. If you have data in another format or if you want to use another map projection, you will need to implement it. The use of Cartesian coordinates provided by the user is not yet implemented, but at the top of the to-do list.

A json file named viz_properties.json (name of this file must be respected). An example with all the parameters that can be adjusted is given in the main project folder.
The parameter temporal_scale can be one of the following : year / month / week_num / seven_days / day / timestep (this last one corresponding to no conversion, assuming the data is given in a time-step scale).
Colors have to be given in hexadecimal notation, for example: blue 08519C, red CB181D, orange D94801, green 238B45, purple 54278F, grey 777777, black 000000, white FFFFFF.

At launching (double-click on the pre-compiled executable file or the Run button from the Processing app), the program will ask you to choose a folder containing the files: the edge list, the node coordinates and the configuration file. Only the first two files are mandatory, the default settings will be used if the configuration file is not provided (which will probably not be appropriate for a proper rendering).

Shortcuts are not case sensitive, and can be used both in lowercase or uppercase:
O – select / change the data folder
Q – quit
N – display / hide nodes
L – display / hide edges
P – save the current visualization as PNG file
C – activate/desactivate image cropping (PNG file only)
V – save the current visualization as PDF file
R – reload the visualization properties and refresh (re-draw) the displayed graph
D – start/stop the dynamic visualization
S – activate/desactivate the record of dynamic viz (as frame images), see the processing documentation on how to make a video from this set of images using the Movie Maker tool (from the Processing app: Tools menu > Movie Maker). See this video for more informations.
A – switch between lines and arrows for the representation of edges
I – display / hide the legend informations

Here are some examples of visualizations produced using the program.

transmissio_whole_network_weeks_cropped.png
transmissio_selected_a_network_weeks_cropped.png
transmissio_selected_b_network_weeks_cropped.png

This program was designed using Processing in order to be easily and highly customizable. In particular, you might be interested in revising the nodes appearance (see the function drawTheNode in the node.pde file), the links appearance (see functions drawCurvedLine and drawCurvedArrow and the code in the networkDrawing.pde file), and legend design (see the legend.pde file).

It is always appreciated when people include a “Built with Transmissio” note with a link to the site, because it helps to create interest and attract more people to the project. It is not/can’t be required, but it makes happy because this is an open-source project and it is a way for you to help in return.

This software is governed by the CeCILL-B license under French law and abiding by the rules of distribution of free software. You can use, modify and/or redistribute the software under the terms of the CeCILL-B license as circulated by CEA, CNRS and INRIA at the following URL http://www.cecill.info.

If you have any comments or questions, just send an email to gael.beaunee@gmail.com, every effort will be made to answer it as soon as possible.

Having a problem? Hopefully the information in this section will help. If, unfortunately, this section does not contained your issue, just send an email to gael.beaunee@gmail.com and every effort will be made to answer it as soon as possible.

Take care that there is no way of representing isolated nodes unless the node has a self-loop edge. In the future, an option will be available to render isolated nodes.

Maybe provided coordinates are not WGS84/GPS, in decimal degrees ‘DD’. See section ‘3.2 – Node coordinates’ for data requirements.