GraphStream
Documentation

SourceForge.net Logo

Note that this section will give you a quick and general vision. For a more complete introduction see the tutorials, and for a complete specification of the project please refer to the manual.

You can browse the tutorials here.

You can download the manual here.

You can browse the API docs here.

A Quick Start

Like said in the overview, GraphStream is a java library that allows the construction and the modification of graphs and elements (nodes and edges) that compose it.

With this library it is possible to :

  • Add and remove elements in a graph.
  • Add, modify and remove attributes on the elements of the graph.
  • Construct a graph from a file that contains events.
  • Write a graph to a file.

Addition, removal and modification of elements

With GraphStream it is easy and quick to construct a graph and to evolve it adding, removing and modifying its elements. The snip set of code below illustrates the idea : 

/* Creation of a graph */
Graph graph = new DefaultGraph("My Graph");

/* Add of nodes */
graph.addNode("A");
graph.addNode("B");

/* Add of an edge between the two nodes */
graph.addEdge("AB", "A", "B", false);

/* deletion of a node that involve the deletion of its edges */
graph.removeNode("A");

Modification of element's attributes

Each element in a graph has an attribute map of variable size. Each attribute is composed of its names (a String) and it's value (an Object). The following example modifies all the nodes of a graph, giving them a random "color" attribute : 

for(Node node : graph.getNodeSet())
{
	node.addAttribute("color", java.awt.Color.getHSBColor( ((float)Math.random()), 0.5f , 0.5f ));}
}

Input/output streams of events

So a dynamic graph is said to be defined by the set of events that modify it. This stream of events can come from another application but most commonly it is read from a file. The simplest way to read a file is to use the read(String) method in the Graph class. The simplest way to write a graph is to use the write(String) method in the Graph class.

However, the I/O package contains more tools. It provides a set of readers for different file formats and an easy way to manage the time at witch events occur to the graph. These readers can be easily instantiated using a GraphReaderFactory. This factory is a class that has only one static method readerFor(String fileName). This method takes the name of a file on the local file system and tries to guess the correct reader class for the format of the file. This method is smart (at least a little smart). It opens the file and tries to infer the form its beginning the type of file. Most of the time this works. If this fails, it looks at the file name extension. If this last try fails, you are so out of luck. Here is an example of use: 

GraphReader reader = GraphReaderFactory.readerFor( fileName );

This the help of this reader you can read a graph in one shot; the whole file is parsed at once and generates a graph. The next example entirely reads a file and generate the corresponding graph : 

Graph g = new Graph("My graph");
GraphReader reader = GraphReaderFactory.readerFor( fileName );
reader.read(filename);

It is also possible to add delay to the reading. In effect when considering the graph as a dynamic graph, a first set of event may define the first state of a graph, a second set may define another state for that graph an so on. The idea of step is part of to the definition of the readers. These steps allow the construction and evolution step by step of a graph. Between two steps the user is free to manipulate the graph at his will. The computing of a shortest path in the graph between two steps is an example : 

Graph g = new Graph("My graph");
GraphReader reader = GraphReaderFactory.readerFor( fileName );

/* The initialisation of the reader is made with the read method */
/* No event is read yet */
reader.begin(filename);

/* The nextStep method tries to read all the events between two steps in the file */
while(reader.nextStep())
{
	/* Do something with the graph between each step of the file ( each state of the graph),*/
	/* a shortest path algorithm for instance  */
}
/* The nextStep method returns false when the end of the file is reached. */

Although many file format can be used, a dedicate file format has been created to simply manage dynamics and the idea of steps. The DGS section bellow illustrates it.

the API

The GraphStream library is a java package (org.miv.graphstream) of classes organised in subpackages :

  • org.miv.graphstream.graph is the main package that contains all the classes related to the graph in an algorithmic point of view. Among the classes there is :
    • Graph, the main class of the package. It maintains it's own state, a list of nodes and edges and as many helper methods.
    • Node, the class that represents the nodes of a graph. It maintains a list of incoming and outgoing links.
    • Edge represents the edges of the graph. It has a reference to the 2 nodes it links.;
  • org.miv.graphstream.algorithm contains classes that try to compute algorithms from the graph theory. For instance, a class called Dijkstra tries compute the popular shortest path algorithm.
  • org.miv.graphstream.io contains all the material dedicates to the construction of streams of events (input and output stream). It contains file readers able to parse text files and create input streams of events. A particular interest is given to the DGS reader that simply implements the event base approach where one line in the file correspond to one event in the graph.
  • org.miv.graphstream.ui correspond to the visualisation part of the project. More details are given in the GUI section of the page.

Dynamic Graph Stream (DGS) File format

An example : 

DGS003
mygraph 2 8 
st 0
an "A" 
an "B" 
an "C" 
st 1
ae "AB" "A" "B" 
ae "AC" "A" "C" 
ae "BC" "B" "C" 
st 2
de "AB"
cn "A"

The complete specification.

css xhtml