GraphStream Tutorials

Let’s get some coding done

Politechnika Poznańska – April 24th 2018

Outline

Installation of GraphStream

Basic steps to install GraphStream

  • Get a working java SDK installed
  • Get the GraphStream tutorial sources
  • Get Eclipse installed
  • Get GraphStream binaries

Get the tutorial workspace

  • Go to the tutorial page at github: github.com/graphstream/gs-talk
  • Get the code:
    • with the “Download Zip” button on github (will download an archive)
    • or through git:

In that project, we want the Demos/ folder.

Get Eclipse Installed

Import the project

  • When asked about a workspace, indicate a new workspace or any existing one.
  • Go to menu File > Import > Maven > Existing Maven Projects. Browse to the project (Demos/ folder), Eclipse should recognize the project.
eclipse-import-maven-projects
eclipse-import-maven-projects

Get GraphStream binaries

With Maven

  • Dependencies are automatically resolved by maven in the pom.xml file :
  • In Eclipse : nothing to do!
  • Or on the command line : mvn compile

Get GraphStream binaries

Without Maven

Binaries can be found on the GraphStream Download page graphstream-project.org/download/ :

  • gs-algo-1.3.zip, gs-core-1.3.zip, gs-ui-1.3.zip.
  • Extract those zip file, and copy gs-algo-1.3.jar, gs-core-1.3.jar, gs-ui-1.3.jar to the gs-talk-master/Demos/lib folder of the project.
  • In Eclipse, select the project in the left panel and refresh the project (F5 key).
  • Right-clic on the project (gs-talk), then properties, then Java build path (left panel), then libraries (right panel), then clic the Add Jars button, and select our 3 jar files in the gs-talk-master/Demos/lib/ folder.

Tutorial 1

Basic tasks with GraphStream

Create and display

  • Open src/org/graphstream/demo/tutorial1/Tutorial1.java
  • Right-clic on Tutorial1.java, then Run As > Java Application

Maven command line: mvn exec:java-Dexec.mainClass="org.graphstream.demo.tutorial1.Tutorial1"

#Change the Display with CSS

We can improve the display with some CSS:

#Access Elements

  • Each node, edge and attribute is identified by an unique string.
  • The node and edge elements are created for you.
  • You can access them however, when created: Node n = graph.addNode("A");
  • Or after creation: Node n = graph.getNode("A");

#Constructive API vs. Events

  • You can remove nodes and edges the same way: graph.removeNode("A");
  • You can change the graph this way at any time. Each change is considered as an “event”.
  • The sequence of changes is seen as the dynamics of the graph.
  • There are many other ways to modify the graph.

#Attributes Data stored in the graph, on nodes and edges, are called “attributes”. An attribute is a pair (name,value).

#Define Attributes

  • But you can add any kind of data on each graph element.
  • However not all attributes appear in the viewer.
  • Notice the way you can add arrays with setAttribute() and a variable number of arguments:

#Retrieve Attributes

Several ways to retrieve attributes:

Special methods are here to simplify things:

#Traversing the graph Iterating through all nodes of the graph is easy:

Equally for edges:

#Other iterators Iterators for nodes:

Iterators for edges:

#Index-based access

Indices for nodes:

Indices for edges:

⚠ indices remain the same as long as the graph is unchanged. But as soon as an addition or removal occurs, indices are no longer tied to their old node or edge ⚠

#Travers from nodes and edges

You can also travel the graph using nodes:

  • Each node and edge allow to iterate on their neighbourhood.
  • Toolkit is set of often used functions and small algorithms (see the API).

Orientation-based interaction

You can iterate on directed edges:

Or:

And get the node degree, entering or leaving:

#Tutorial 2

###A first dynamic graph

#Sinks - A graph can receive events. It is a sink. - A sink is connected to a source using the Source.addSink(Sink) method. - Events are filtered by type (Elements Events and Attributes Events) : - addElementSink(ElementSink). Nodes and edges are Elements. - addAttributeSink(AttributeSink). Data attributes are stored on every element. - A Sink is both an ElementSink and AttributeSink.

#ElementSink ElementSink is an interface

#AttributeSink An attribute sink must follow the interface:

#Source A source is an interface that only defines methods to handle a set of sinks.

#A first dynamic graph

Since Graph is a sink let’s create a graph from a set of events generated by a source.

  • A file with information about graphs (in a proper file format) can be a source of events.
  • A few graph file formats can handle dynamic.
  • GraphStream provides a file format (DGS) that allows to store and load dynamic graphs.
A graph from a file
A graph from a file

The GDS File Format

  • an for “add node”.
  • ae for “add edge”.
  • ae "AB" "A" > "B" adds a directed edge between nodes A and B.
  • cn, ce and cg change or add one or more attributes on a node, an edge or the graph.
  • dn and de allow to remove nodes, edges.

Open the example DGS file in data/tutorial2.dgs.

How to handle dynamics

  • Storing temporal information is tricky.
  • Timestamps on events is a good way to encode time
  • But some events occur at the same time.
  • Let’s define time steps within events
  • st <number>

Steps in DGS

The ability to remove nodes and edges make the format dynamic.

Add this to the data/tutorial2.dgs file:

And save it.

#Read the whole file

The file can be read entirely :

  • However this will send all events as fast as possible.
  • We have no control over the speed at which events occur.

#Read the file event by event We can read the DGS file event by event using an input source:

FileSource Pipeline
FileSource Pipeline

#Read the file step by step - We read the file event by event (line by line in the file), however it still does it as fast as it can. - Note the line while(source.nextEvents()); - Also note that we have to call the begin() and end() methods before and after reading to cleanly open and close the file. - Let’s slow down the process :

  • We can also run it step by step so that events between two step appear together

Graph Layout

  • By default the graph the spacial position of nodes on the display is automatically computed.
  • However one may want to position nodes by ourself.
  • One can do this using the x and y attributes:

Then one have to tell the viewer not to compute nodes positions: