Updated for release version: mgui-1.0.15-alpha

This tutorial will introduce graphs in the mgui environment, explaining how they can be treated both as dimensionless objects and as shapes with specific 3D geometry.

Introduction

Graphs are mathematical models which represent (somehow related) discrete entities as vertices, and relationships between these vertices as edges. Graph theory is the branch of mathematics which studies the set of problems which arise under this formalism. Given this framework, graphs can be very powerful tools for investigating complex systems, and have been applied to scientific paradigms as diverse as sociology, genetics, local and world-wide networks, and neuronal circuits. This tutorial explains how graphs are represented in mgui, as well as how it handles file I/O, 2D and 3D visualization, and other operations.

Loading a Pajek graph

We'll start with how to load graphs into the mgui workspace. At present, only graphs in the Pajek data format can be read or written. The Pajek website provides some convenient test data which we might as well use too; you can download it from here. To load our graph, go to the "Files" panel and choose "Pajek graphs (*.net)" as the input file type. Now click "Browse" and navigate to wherever you downloaded the test data. We want a file called "cvrml.net"; select that, and click the "Options" button. This brings up the following dialog box:

Make sure that "Shape?" is selected, and the target shape set is specified (these are the defaults). Click OK.

Now click "Read Data". The graph is now loaded, and should appear in the tree panel under "Graphs", as well as a shape under the target shape set. Now we can play with it, but first, a few more words about graphs…

Graphs in ModelGUI

In mgui, graphs can be represented in two ways. The dimensionless graph is simply a set of vertices and edges, with no fixed geometrical coordinates. The Graph3D object wraps a dimensionless graph as a 3D shape, complete with fixed 3D coordinates and attributes. Both are described below:

Dimensionless graph

A dimensionless graph is the pure mathematical representation of a graph. "Dimensionless" in this sense refers to a lack of fixed spatiotemporal dimensions; the graph is free to take on any form. This representation is useful for graph theoretical operations, or for visualization using specific layouts which attempt to best portray particular characteristics of the graph (e.g., its hubs, its local versus global connectivity, its modularity). The "cvrml.net" graph you just loaded is currently represented as a dimensionless graph. However, it does happen to have 3D coordinates associated with it, which we'll use later.

To have a look at our graph, we need a "Graph" window. This can be done either by right-clicking on the current window and selecting "Change type > Graph", or via the Windows panel. To display our graph, select the "Sources" category from the Windows panel, and set "CVRML" as the source for the graph window. You should see this:

Don't know about you, but I'm not a fan of the default appearance. Let's change it. Open the Tree panel, and under Display Panels, expand "Tab1", the "Graph" window, and the "Attributes" node. By changing attributes, try to make your graph look like this:

2D layouts

One of the advantages of a dimensionless graph is its flexibility for visualization. A graph layout is a means of rearranging the 2- or 3D position of a graph's vertices, with respect to some algorithm that typically accounts for both the proximity of other vertices and the arrangement of edges. To get an idea of this, let's apply some of the available Jung layouts to see how they affect the graph visualization. To do this, right-click on the graph window and select a choice from the "Layout" submenu. This is what the "KK" layout looks like:

The layouts available with the Jung library are:

Spring layout

Treats edges as "springs" with compressive and tensive forces

KK layout

Kamada-Kawai layout (see here)

ISOM layout

So-called "inverted self-organizing maps"

FR layout

Fruchterman-Reingold layout; uses parameterized attraction and repulsion forces

Coordinates

This is an mgui layout which sets the vertex location to fixed coordinates. 3D coordinates are projected onto a plane, which is the horizontal plane by default. This can be modified via the context menu… try it!

The Graph3D object

Graphs can also be given dimensions, by setting them as Graph3D objects. This is a shape wrapper for the graph object, and requires that the graph has 3D coordinates set. We have already created a Graph3D shape; now let's have a look at it. Right-click on the graph window and select "Split horizontal > Graphic3D" to create a new 3D window. Right-click the new 3D window and select the ShapeModel containing your graph (e.g. "Default Model"). You'll see a funny sight:

This is because the graph is much smaller than the default vertex scale. We need to scale it down. You can do this by going back to the Tree Panel, and expanding the "Shape Models" node until you find the attributes for the CVRML object. Let's change the "VertexScale" attribute to 0.01. Zoom in, and we can now see our 3D graph (compare to the 2D graph in "Coordinates" layout):

Feel free to play around with the attributes. The graph can be made to look as in the image below by changing "VertexScale" to 0.02, "LineColour" to grey, "EdgeCylinderMin" to 0.001, "EdgeScale" to 0.004, and "EdgeAsCylinder" to true.

Vertex Data

Like any shape in mgui, vertices can be associated with numeric or text data arrays, which can be used to determine their appearance. There is no data currently available for our graph, so let's just fabricate some. First download this text file (65 randomly generated values). Next, from the File Panel, select "Shape Data Files (*.txt, *.sdata)" as the input file type and browse to the file you downloaded. Click Options, select "Load as one column", name the column "random", and click "OK". Finally, click "Read Data" and everything should be copasetic.

We can now use this vertex-wise data to display the 3D graph in fun ways, as explained in the next section…

Visualization

This section will explain how to manipulate the appearance of your graph objects, depending on your needs. It will address both dimensionless and 3D graphs.

Labels

If your graph has labels attached, it is often desirable to render these next to their associated vertices. This can be done in mgui by selecting the "ShowVertexLabels" attribute. However, if you do this, you'll notice that the labels are ridiculously enormous relative to the graph itself. To make them more sane, we need to rescale them to fit the graph. This is done by setting the "LabelScale" attribute; in our case, 0.01 is a decent value. The font and fine-tuning of the size can also be controlled by changing the "LabelFont" attribute; below, the font is "Arial Narrow", size 4. Note that because there are no actual labels associated with the CVRML graph, the default is to use the vertex indices as labels:

Vertex scaling

Scaling vertices is a common practice in graph theory, and can be a useful means of visualizing some sort of meaningful data associated with your vertices — a graph measure such as betweenness centrality or clustering coefficient, or any data derived from whatever phenomenon it is your graph is modelling. We've already loaded some random data, for demonstration purposes, so let's pretend this represents some variable of interest. To scale vertices in the CVRML graph, you want to first set the scale data to the "random" column you just created; this is done from the drop-down menu for the "ScaleData" attribute. Now select "ScaleData", and your vertices will be rescaled:

You may want to play with the scaling; for instance to exaggerate larger values and minimize small ones. You can do this with a combination of values for the "VertexScale" and "VertexScaleExp" attributes. As their names imply, these values scale the vertex according to the equation Scale = (VertexScale * Value) ^ VertexScaleExp. Values of 0.01 and 0.7, for instance, result in this scaling:

Edge scaling

Edges can also be scaled by the weights associated with them in the Pajek file. To scale edges, you must have "EdgeAsCylinder" selected. The weight scaling of the edge is then determined by the values of the EdgeWeightScale and EdgeWeightScaleExp attributes:

Scale = (EdgeScale * (EdgeWeightScale * {weight}) ) ^ EdgeWeightScaleExp

Setting EdgeWeightScale to zero will result in no weight scaling.

Colour maps

Another useful way of visualizing data on a graph is through colour maps. Let's unselect "ScaleVertices" and use colour to display the values instead. The best way to do this is through the "Shapes Panel". Select the CVRML graph as the selected shape, and then expand the "Data Display" and "Histogram" sections. In the histogram section, select the "Use current data" box. To specify the colouring, first select the "random" column and then select a colour map; I chose "nih_grey". You can click "Reset" to set the data range for the colour map to the extents; however, since we know that the values are chosen from the range 0 to 1, we can just use this data range. Enter these values in the text boxes and then click "Apply". Both the histogram and the vertex colours will change. I made modified the histogram as well, so that it has 10 rather than 80 bins:

You can also reapply the scaling to obtain a redundant but perhaps more visually appealing visualization:

Edge weights can also be used to apply a colour map. This is very useful way to visualize a dense graph, for instance; the trick is to use alpha values at the bottom end of your colour map. Load this colour map, if it does not already exist in your version of ModelGUI: green_inv_trans.cmap (hint, do this from the "Continuous Maps" section of the Maps Panel. Next, select green_inv_trans for the EdgeWeightCmap attribute of your graph. Set EdgeWeightColour to true. Set HasAlpha to true, and set Alpha to 0.0. Now all you have to do is play with the EdgeWeightCmapMin and EdgeWeightCmapMax values to find a suitable range for your edges. Everything below the minimum will be transparent.

Exercise

Download the following Pajek format graph: exercise_graph.net
…and the vertex data: degree_centrality.net

And produce this:

Good luck :)