Previous Up Next

2  CCVisu Tutorial

In this tutorial, we write ccvisu.sh for java -jar CCVisu-3.0.jar. If no command-line option is given, CCVisu opens a GUI to enter necessary parameters, e.g., an input file to operate on. A double-click on the jar file in a file browser should do the same.

2.1  Generating Graphs in RSF Format / CCVisu as Fact Extractor

Relational Standard Format (RSF) is a common exchange format for relations. RSF is used by many relation-based tools, for example, the relational programming tool CrocoPat and the re-engineering tool Rigi (Rigi Standard Format). RSF is based on plain text with whitespace (most common: tabs) as delimiter, which makes it easy to process data on the command line with standard Unix tools like grep, cut, and sed.

When CCVisu is used to produce layouts (visualizations), it expects input graphs in one of the following file formats: Relational Standard Format (RSF), Doxygen XML format (DOX), Subversion log format in XML (SVN), and CVS log format (CVS). Since CCVisu uses RSF as file format for data exchange, it can export (to RSF) relations that it extracted from one of the above mentioned input formats.

Open Document Spreadsheet (ODS) to RSF Converter. For example, given a file crocopat-2.1.ods, which is an ODS file that contains one table sheet named ’CO-CHANGE’ with several columns representing a relation. Then the command
ccvisu.sh -informat ODS -i crocopat-2.1.ods -outformat RSF -o crocopat-2.1.rsf
produces a file crocopat-2.1.4.rsf, which contains the co-change graph that CCVisu extracted from table sheet ’CO-CHANGE’.

Doxygen (DOX) to RSF Converter. For example, given a directory crocopat-2.1.4-dox of XML files that was produced using the command doxygen Doxyfile, where Doxyfile is an example configuration file for Doxygen. (Doxygen usually generates a directory xml which contains a file index.xml.) Then the command
ccvisu.sh -inFormat DOX -i crocopat-2.1.4-dox/index.xml -outFormat RSF -o crocopat-2.1.4.rsf
produces a file crocopat-2.1.4.rsf, which contains the relations that CCVisu extracted from the Doxygen output.

CVS to RSF Converter. For example, given a file crocopat-2.1.log, which is a CVS log file of CrocoPat and was produced using the command cvs log -Nb. Then the command
ccvisu.sh -informat CVS -i crocopat-2.1.log -outformat RSF -o crocopat-2.1.rsf
produces a file crocopat-2.1.4.rsf, which contains the co-change graph that CCVisu extracted from the CVS log file. As example for how an RSF file looks like we show an extract from the generated co-change graph of CrocoPat: 

CCG    125    src/bddSymTab.h
CCG    126    src/Makefile
CCG    126    src/relLex.l
CCG    127    src/crocopat.cpp
CCG    127    src/relExpression.h
CCG    127    src/relLex.l
CCG    127    src/relYacc.y

Subversion (SVN) to RSF Converter. TODO

Other Fact Extractors. There are many tools available for graph extraction from software systems. Examples are: cawkcg, GCT, Imagix, Rigiparse, Field, cflow, CIA, LSMEcg, Mawkcg, Portable Bookshelf (grok), Doxygen, DepFinder, java2rsf.

Comparison of Fact Extractors. A good (but somewhat outdated) comparison of fact extractors was done by Murphy et al. [MNGL98].

2.2  Generating Layouts / CCVisu as Graph-Drawing Tool

Generate a Layout. Once we have the input graph in RSF or in one of the above mentioned formats, the next step is to run CCVisu on the input graph in order to produce a (clustering) layout for the software graph. For example, consider the dependency graph of a (small) compiler system (extracted using Bauhaus) in file compiler.rsf. If we run CCVisu using the command line
ccvisu.sh -informat RSF -i compiler.rsf -outformat DISP -iter 100,
a screen display will open and show the resulting layout, running 100 iterations of the minimizer. Since RSF is the default input format, and DISP (screen DISPlay) is the default output option, and by default it runs 100 iterations, the following command does the same: ccvisu.sh -i compiler.rsf

Save a Layout. CCVisu supports several different output formats: LAY (plain text format), SVG (2D Scalable Vector Graphics), VRML (3D format). Any layout that CCVisu shows on the screen can be saved to a file in one of these formats, by opening the corresponding SAVE dialog and giving a filename to store the layout in the file. The filename extension .lay, .svg, or .wrl determines the file format.

2.3  Introduction to Force-Directed Graph Layout

Force-directed graph layout consists of two parts: an energy model that assigns an energy value to each layout for evaluation —the smaller the number, the better the layout—, and a minimizing algorithm that computes a layout with minimal energy.

A tool for force-directed graph layout takes as input a graph (undirected, connected, irreflexive). Another parameter of the tool is the energy model, which encodes the user’s requirements for ‘good’ layout, e.g., uniform edge-length or interpretable distances. The output of the tool is a layout that has minimal energy according to the energy model.

CCVisu is such a tool for force-directed layout. It uses the well-known algorithm of Barnes and Hut as minimization algorithm, and it provides several standard energy models, and lets the user define (optional, per command line) certain parameters of the energy model, in order to adapt it to the user’s application area.

2.4  Examples

Chain. Consider first a graph that forms a chain, i.e., a connected graph where the first and the last vertex has one edge and all other vertices have two edges. Figure 1 shows the graph (on the left) and the resulting layout (on the right). To produce this result, the tool CCVisu was invoked with the following command line (start java interpreter with class CCVisu of package ccvisu, read the input graph in RSF format from file simple-chain.rsf, and use the attraction exponent 3 in the energy model, cf. Section 6.2, Generic Model):
ccvisu.sh -i simple-chain.rsf -attrExp 3

An energy model usually consists of two terms, one is interpreted as the energy resulting from an attraction force, and the other is interpreted as the energy resulting from a repulsion force. In the example, the attraction force ensures that neighboring vertices in the chain have closed positions in the layout (e.g., vertices 1 and 2). The repulsion force between each two vertices ensure that vertices that are connected by a long path have distant positions (e.g., vertices 1 and 20).

R 1 2
R 2 3
R 3 4
R 4 5
R 5 6
R 6 7
R 7 8
R 8 9
R 9 10
R 10 11
R 11 12
R 12 13
R 13 14
R 14 15
R 15 16
R 16 17
R 17 18
R 18 19
R 19 20
Figure 1: Chain example

V1V2. todo

3times two. todo

CrocoPat’s Co-Change Graph. Now we consider the co-change visualization of the tool CrocoPat1. The input is the CVS log file of the version history, obtained using the command cvs log 2. The co-change visualization can be either computed and displayed in one direct step: 

ccvisu.sh -inFormat CVS -i crocopat-2.1.log -hideSource

or obtained by several steps (to store intermediate results for later reuse): 

ccvisu.sh -inFormat CVS -i crocopat-2.1.log -outFormat RSF -o crocopat-2.1.rsf

computes the co-change graph and stores it into a text file in RSF format. 

ccvisu.sh -inFormat RSF -i crocopat-2.1.rsf -outFormat LAY -o crocopat-2.1.lay -hideSource

computes the layout and writes it to a text file in LAY format. The option -hideSource hides the change transaction vertices in the visualization. 

ccvisu.sh -inFormat LAY -i crocopat-2.1.lay -outFormat SVG -o crocopat-2.1.svg

converts the layout in LAY format to a vector graphics in SVG format.

© Dirk Beyer
Previous Up Next