The InfoVis Toolkit

The InfoVis Toolkit is a Java library, designed to work with Java/Swing components. It requires a Java 1.4 runtime or above for running the library programs and examples. A Java compiler is required to create applications using the InfoVis Toolkit. The InfoVis Toolkit is composed of one main library jar file called infovis.jar and several supporting libraries and programs. A sample application can be run using directly from the infovis.jar library using the following command, assuming the file infovis.jar is in the current directory: "java -jar infovis.jar"

To compile applications or examples using the InfoVis Toolkit, the file infovis.jar should be added to the Java class path. This is generally done using an option of you favorite IDE for Java or by setting the shell variable CLASSPATH to the location of the file infovis.jar. Furthermore, you need to have other library files available to run the InfoVis Toolkit, all distributed with the InfoVis Toolkit in the "lib" directory:

Furthermore, some programs are used by the toolkit to layout graphs: dot, neato and twopi. These programs are provided by the GraphViz package of AT&T, available at the official site of GraphViz. These programs should be in the executable PATH because they will be called from the InfoVis Toolkit when graph layout is used.

The InfoVis Toolkit is distributed with a set of sample data files to try and test the toolkit or user applications. They are also used as examples of the file formats supported.

The InfoVis Toolkit supports a limited but extensible set of file formats. Section Chapter 6, Readers and Writers explains how file formats are read and written and how to extend the list of supported file formats.

Several sample applications of the InfoVis Toolkit are provided in the example folder in the distribution. Visualizing a table as a time-series data can be done as follows:

public class Example1 {
    public static void main(String args[]) {
        String fileName =
            (args.length == 0) ? "data/salivary.tqd" : args[0];
        DefaultTable t = new DefaultTable();
        t.setName(fileName);
        AbstractReader reader =
            TableReaderFactory.createReader(fileName, t);
        if (reader == null || !reader.load()) {
            System.err.println("cannot load " + fileName);
            return;
        }
        TimeSeriesVisualization visualization =
            new TimeSeriesVisualization(t);
        VisualizationPanel panel =
            new VisualizationPanel(visualization);
            
        JFrame frame = new JFrame(fileName);
        frame.getContentPane().add(panel);
        frame.setVisible(true);
        frame.pack();
    }
}

    

The package declarations have been omitted for clarity. The main program creates and displays a simple time series visualization from the file name specified in the first argument of the program. First, a table is created and named with the file name. Loading the file is done in two steps: finding a reader and actually loading the file from this reader. The reader is created through a factory object. Factories are used to create objects indirectly according to some specified parameters (we will describe them later in depth). Here, a reader object is created from a file name and a table object. The factory analyzes the file name and maybe the file contents to create the most suitable reader for it. If no reader is returned or the reader cannot load the file, the program is exited with an error message. Otherwise, a visualization object is created and inserted in a standard Java/Swing JFrame inside a visualization panel.

In this example, the visualization is not interactive because we haven't created any control panel associated with the visualization. We can have the control panel if we replace the creation of the visualization panel by the following code:

        ControlPanel panel =
            ControlPanelFactory.sharedInstance()
              .createControlPanel(visualization);

Factories are quite simple and very useful for extending the infovis toolkit. They are simple objects with one creator method that looks at it arguments and create an object according to them. The TableReaderFactory looks at the file name and, if it recognizes that it ends with the ".csv" extension returns a new CSVTableReader. If it receives a file name ending with ".csv.gz", it recognizes that the file is compressed by GZIP and decompress is on the fly. New file readers can then be defined by programmers and added to newer releases of the infovis toolkit and the same program will then be able to read these new file formats without modification. Other kinds of customizations are allowed by the "factory" pattern but we will describe them on a separate section.

Although the InfoVis Toolkit may seem large by the number of classes it defines, it follows a very simple structure. At the top-level, it defines the most important interfaces and classes: Column, Table, Tree, Graph, Visualization and Metadata. The first-level defines the several column classes in the column package, basic input/output classes in the io package, several metadata categories in the metadata package, control panels and interaction components in the panel package, a visualization package for the visualization internals and subpackages for the data-structures: table, tree and graph. Finally, a utils package contains utility classes that don't fit in other packages.

Each data-structure related package also contain sub-packages for their input/output components and their visualizations. This is where the default readers and writers are defined, as well as the visualizations provided by default.

To visualize a tree data-structure using the "Treemap" [] visualization technique, the code would be:

import infovis.tree.DefaultTree;
import infovis.tree.io.TreeReaderFactory;
import infovis.tree.visualization.TreemapVisualization;
import infovis.io.AbstractReader;
import infovis.panel.ControlPanel;
import infovis.panel.ControlPanelFactory;

import javax.swing.JFrame;

public class Example2 {
    public static void main(String[] args) {
        String fileName =
            (args.length == 0) ? "data/salivary.tqd" : args[0];
        DefaultTree t = new DefaultTree();
        AbstractReader reader =
            TreeReaderFactory.createReader(fileName, t);
        if (reader == null || !reader.load()) {
            System.err.println("cannot load " + fileName);
        }

        TreemapVisualization visualization =
            new TreemapVisualization(t, null, Squarified.SQUARIFIED);
        ControlPanel control =
            ControlPanelFactory.sharedInstance().createControlPanel(
                visualization);

        JFrame frame = new JFrame(fileName);
        frame.getContentPane().add(control);
        frame.setVisible(true);
        frame.pack();
    }
}

    

The package declaration for the program Example 2.1, “Simple visualization program for time series data” is:

import infovis.io.AbstractReader;
import infovis.table.DefaultTable;
import infovis.table.io.TableReaderFactory;
import infovis.table.visualization.TimeSeriesVisualization;
import infovis.panel.ControlPanel;
import infovis.panel.ControlPanelFactory;

import javax.swing.JFrame;
    
   

Each visualization technique use a layout algorithm and several visual attributes to set the color or geometric properties of the displayed items. For example, scatter plots compute the position of items based on two visual attributes: one for the X coordinate and one for the Y coordinate. Each item can have a size and a color. These visual attributes can be associated with data columns or set to default values.

Some visual attributes are generic to all visualizations and others are specific. The generic attributes are color, label and size. For example, if you know that the tree in example Example 2.2, “Simple visualization program for hierarchical data” has an column called "name", you can specify it as the label column like this:

            visualization.setVisualColumn(
                Visualization.VISUAL_LABEL,
                t.getColumn("name"));

The label will then appear with a form depending on the visualization: inside items for scatter plots or trees. If dynamic labels are enabled, they will use the content of this column for their labels.

Visualization technique may use additional visual attributes such as shape for scatter plots. Some visual attributes, such as color and stroke, are defaulted when they not specified. The default value can be set through the methods of the form: setDefault<ATTRIB>(ATTRIB default).

Allowing Fisheye Lenses is just a visualization option:

            visualization.setFisheyes(new Fisheyes());

Enabling Dynamic Labeling involves creating a new visualization layer above the main visualization. Here is the required code:

        TimeSeriesVisualization visualization =
            new TimeSeriesVisualization(t);
        ControlPanel control =
            ControlPanelFactory.sharedInstance().
                createControlPanel(excentric);

The toolkit provides higher-level mechanisms to create visualizations and display them using option panels allowing fisheye views and dynamic labeling to be enabled or disabled at will.

The InfoVis Toolkit comes with three main data types suited to visualizations: tables, trees and graphs. This section shows how to create and manage them.

Table table = new DefaultTable();
StringColumn name = new StringColumn("name");
table.addColumn(name);
LongColumn date = new LongColumn("date");
table.addColumn(date);
IntColumn size = new IntColumn("size");
table.addColumn(size);

name.add("file1");
date.add(124334);
size.add(1024);
name.add("file2");
date.add(143434);
size.add(10);

date.setFormat(new UTCDateFormat());
name.add("file1");
date.addValue("03/23/2003 15:32:10");
size.add(1024);
name.add("file2");
date.addValue("03/10/2004 10:43:21");
size.add(10);

IntColumn pollution = new IntColumn("pollution");
for (int i = 0; true; i++) {
    String line = input.readLine();
    if (line == null)
        break;
    if (line.length() != 0) {
        pollution.setValue(i, line);
    }
}

Trees are data structures based on tables. Here is an example of tree creation:

Tree tree = new DefaultTree();
StringColumn name = new StringColumn("name");
tree.addColumn(name);
LongColumn date = new LongColumn("date");
tree.addColumn(date);
IntColumn size = new IntColumn("size");
tree.addColumn(size);
date.setFormat(new UTCDateFormat());
int node = tree.addNode(Tree.ROOT);
name.setValue(node, "file1");
date.setValue(node, "03/23/2003 15:32:10");
size.setExtend(node, 1024);
node = tree.addNode(Tree.ROOT);
name.setValue(node, "file2");
date.setValue(node, "03/10/2004 10:43:21");
size.setExtend(node,10);

This example is similar to the table example but instead of adding data in columns, it uses node numbers created by the tree as indexes. Contrary to the table example, the indexes returned by the tree method addNode(int parent) can be in any order and the attribute values should be set at the node index. This explains why we used the methods setValue(int index, String v) and setExtend(int index, TYPE v) instead of addValue(String v) and add(TYPE v) in the table example.

Section the section called “Trees” prodigies all the details on manipulating trees.

Graphs data structures are based on tables. A graph is made of two tables: the vertex table and the edge table. Here is an example of graph creation:

Graph graph = new DefaultGraph();
StringColumn name = new StringColumn("name");
graph.getVertexTable().addColumn(name);
LongColumn date = new LongColumn("date");
graph.getVertexTable().addColumn(date);
IntColumn size = new IntColumn("size");
graph.getVertexTable().addColumn(size);
date.setFormat(new UTCDateFormat());
int v1 = graph.addVertex();
name.setValue(v1, "file1");
date.setValue(v1, "03/23/2003 15:32:10");
size.setExtend(v1, 1024);
int v2 = graph.addVertex();
name.setValue(v2, "file2");
date.setValue(v2, "03/10/2004 10:43:21");
size.setExtend(v2,10);

IntColumn refCount = new IntColumn("edgeCount");
graph.getEdgeTable().addColumn(refCount);
int e1 = graph.addEdge(v1, v2);
refCount.setExtend(e1, 1);

This example creates a new graph and adds the same three columns as in the previous examples to the vertex table. It also creates a column name "refCount" associated with the edge table, so the graph has both attributes associated to its vertices ("name", "date" and "size") and to its edges ("refCount").

Section the section called “Graphs” provides all the details on manipulating graphs.

A column is an index container that contains a homogeneous data structure, such as integers, floating point values or string. Columns also manage Metadata, notification and undefined values.

Column is a Java interface with several concrete implementations. There are two derivation paths for columns, one is for concrete data types and the other one is for dense versus sparse columns.

Dense columns are based on primitive array, providing a constant access time and a memory footprint linear with the number of entries. Sparse columns are based on sorted trees, providing a log(n) access time and a memory footprint linear with the number of defined entries. They come specialized for the most used data types such as int, long, float, double, String, Object, bool and some others used internally.

The interface of the Column should be described using an extended syntax with parameterized types to be complete. Each of the concrete class implementing the Column interface for storing an object of class TYPE should provide a set of methods using this concrete type. For example, the IntColumn class implements all the methods with "TYPE" replaced by int so the get method returns an int.

The Java language doesn't allow this kind of type parametrization yet — although a newer experimental version does — so the declaration doesn't express this requirement and the Java compiler doesn't enforce these methods, but we have worked hard to implement them and check them by hand. If you want to implement a new kind of Column, you will also have to implement them.

The RowComparator interface allows elements to be compared and sorted without having to know their type. It declares the compare(int,int) method for comparing the values of two rows in the column.

The basic interface specifies that column elements can always be manipulated in their textual representations. This is convenient for loading column contents from a textual file or saving them. It also provides a representation for using the columns for labeling visualizations. However, the real value stored in a concrete column can be of any type.

When the concrete type of the column is known, the concrete method, shown as parametrized in the interface, such as get orset, can be used to access the concrete values of the column elements. These methods are fast since they don't involve any allocation or transformation.

      LongColumn dateColumn = new LongColumn("date");
      dateColumn.setFormat(new UTCDateFormat());
      dateColumn.addValueOrNull("29 Oct 2003 21:47:32");

Tables are the simplest data structure of the InfoVis toolkit. A simple way to create and populate a table is:

Table table = new DefaultTable();
table.setName("Cities");
StringColumn name = StringColumn.findColumn(table, "name");
IntColumn population = IntColumn.findColumn(table, "population");
name.add("New York");
population.add(2000000);
name.add("Los Angeles");
population.add(1000000);

 public Tableimplements Metadata, TableModel {
}

The Table interface is described in Figure 3.1, “The Table interface”. A Table also manages Metadata and implements the TableModel interface, enabling its use in a standard Java Swing JTable. Table defines methods to add/remove/access columns by name or index. The getRowCount method returns the maximum number of rows of each of the columns in the table; Tables don't maintain their own row counts. The columns contained in a Table may have different row counts. This is not a problem at all considering that columns can contain undefined rows; the row count of a table is indeed the largest row count and columns with less elements are considered as having undefined values at their ends.

The default implementation of the Table interface is the DefaultTable class. Concrete implementations of Tree and Graph derive from this class.

 public Treeimplements Table {
}

The InfoVis Toolkit implements rooted trees with the interface describe in Figure 3.2, “The Tree interface”. A Tree manages a topology and associated attributes, stored in columns. Creating a file-system like tree can be done using this example program:

    Tree tree = new DefaultTree();
    StringColumn name = StringColumn.findColumn(tree, "name");
    LongColumn date = LongColumn.findColumn(tree, "date");
    date.setFormat(new UTCDateFormat());
    
    name.setValueAt(Tree.ROOT, "/");
    date.setValueAt(Tree.ROOT, "29 Oct 2003 21:47:32");

    int n1 = tree.add(Tree.ROOT); // Child of tree root
    name.setValueAt(n1, ".classpath");
    date.setValueAt(n1, "23 Feb 2004 22:46:30");

    int n2 = tree.add(Tree.ROOT); // 2nd child of tree root
    name.setValueAt(n2, "CVS");
    date.setValueAt(n2, "6 May 2003 23:32:34");

    int n3 = tree.add(n2); // child of node n2
    name.setValueAt(n3, "Entries");
    date.setValueAt(n3, "24 Feb 2003 23:30:13");

A Tree is implemented as a Table. Nodes are simply indexes. Currently, four internal columns are used to manage the topology. These columns can be read and even modified, but doing so would certainly break the structure so it should be avoided. The internal columns are all IntColumns. Here is their description:

Other internal columns can be maintained automatically by the DefaultTree implementation to speedup topological queries such as the depth of a node, its degree (number of children) or to access the children list faster. The depth column is created and maintained using the method createDepthColumn. The degree column is created and maintained using the method createDegreeColumn.

 public Graphimplements Table {
}

Graphs are composed of two tables: a vertex table and a link table. The first holds topological informations about the vertices and their associated attributes as columns. The second holds the topological information about the links. The Graph interface is described in Figure 3.3, “The Graph interface”.

Metadata is information about the data. Columns and tables can contain metadata implemented as an associative map between a key and a value, usually strings.

There are many types of metadata; well known uses include the description of the dataset in term of a title, an author, a creation date, etc. Another use could be describing the processing performed on a table or on a column to create it. The InfoVis toolkit uses the metadata for several different purposes that we describe here with no particular order.

 public Aggregation implements AggregationConstants {
  public static final short AGGREGATE_NO = 0;
  public static final short AGGREGATE_YES = 1;
  public static final short AGGREGATE_COMPATIBLE = -1;
  public short isAggregating(Column col);
  public Column aggregate(Column src,
                          Tree tree,
                          Column dst);
}

The main implementation of the Visualization interface is the DefaultVisualization class. All the specific visualizations derive from it.

When a visualization is created, it should be configured to map table columns to visual columns. Visualizations use several types of visual properties, some being standard and some being specific to a visualization technique. The standard visual properties are the following:

Other attributes can be specified using the same mechanism, although they are not "visual" attributes per se. These attributes are: