Perforce JViews Charts Sample: Treemap Charts

Description

This sample demonstrates a treemap chart.

Treemap charts show data attributes according to their importance.

This sample shows the world-wide energy production and consumption, from 2004 to 2007, by energy type, by country, and by year. It consists of three parts:

A tree-table, at the top left, displays the type-country-year records, grouped by type, by country, or by year. This tree-table is optimal for viewing the total consumption of energy in a more organized way.
A treemap, at the top right, displays the type-country-year records, also grouped by type, by country, or by year, in a way that some consumption records appear big and others visually insignificant - depending on the amount of energy - or some records stand out - depending on the type of energy. This treemap is optimal for getting an overview of all records and for spotting particular records with extraordinary size combined with specific attributes.
A table, at the bottom, displays the raw data. This table is optimal for viewing all the details of just one record.

The selection between the three displays is synchronized. This allows you to immediately see the details of a record (in the table) when you click on it in the treemap or in the tree-table.

A set of controls is available in the centre of the panel. They have an effect on the tree-table and the treemap below them.

How to Use the Sample

Picking a record

You can click on a record in either the tree-table, the treemap, or the table, and the record will be highlighted in all the three parts. For example, you can look for the biggest treemap rectangle: this will show the record representing the largest consumption. You can also look for the countries with the largest amount of nuclear energy. You can also use the tooltips.

Drilling down on a group of records

You can also click on a group of records (a year, or a country) in the tree-table or in the treemap. In the tree-table, you click on a non-leaf element of the tree. In the treemap, you click on the border; when the tooltip changes from a two-line display to a single-line tooltip, your mouse pointer is over such a border. In either case, the three views will show the same records highlighted.

When you press the zoom-in/drill-down button (this is the button with a downwards arrow ), the treemap shows a magnified view of only the selected records. This means that the focus of the treemap has changed.

Using the history buttons

The back (leftward arrow ) and forward (rightward arrow ) buttons can be used as in a Web browser. The zoom out (upward arrow ) will change the focus to the group of records containing the current focus.

Changing the partitioning criterion

You can change the criterion by which records are grouped in the tree-table and in the treemap. To do so, drag one of the buttons labeled with a column name to the first position.

Changing the meaning of importance

You can change the way the treemap expresses the importance of a record. The treemap shows importance through a bigger area of the rectangle on the screen. You can decide which characteristics of a record determines the area. Only numeric table columns can be used for this purpose. The choices that make most sense are the "Consumption" and the "Production" columns.

Changing the meaning of colors

You can change the way the treemap highlights particular records through colors. Both numeric and symbolic table columns can be used for this purpose. For numeric table columns, the color scheme varies from green (for high values) to red (for low values). For symbolic table columns, such as Country or Region, the color scheme is chosen to give the appropriate contrast; the colors themselves do not have a particular meaning.

How to Run the Sample as an Application

This sample can be run as an application. The installation directory contains an executable JAR file, treemap.jar, that allows you to execute the sample with a double click from a file browser. Note that if you are using Internet Explorer, you can open the installation directory and execute the JAR file from the browser. This technique may not work in other Web browsers.

Alternatively, you can run the sample application from the command line. First check that the Ant utility is properly configured. If not, see the instructions on how to configure Ant for Perforce JViews.

Then, go to the installation directory of the sample and type:

ant run

Topics Covered

Creating a treemap chart.
Connecting the treemap chart to a data source.
Reading an Excel spreadsheet into a data source.
Performing automatic partitioning in the data source.
Connecting a tree-table to the data source.
Enabling labels in the treemap.
Enabling tooltips in the treemap.
Displaying a selection in the treemap.
Synchronizing the selection between the treemap and the tree-table.
Drill-down (zoom) in the treemap.
Choosing an area column.
Choosing color column and color scheme.

Detailed Description

Creating a treemap chart

The treemap chart is created through a single statement:

      chart = new IlvChart(IlvChart.TREEMAP);

When the data source is set on the chart, the renderer of type IlvTreemapChartRenderer will be created automatically.

Connecting the treemap chart to a data source

The data is given as an instance of IlvFlatTableModel. This kind of model is very similar to the Swing , but it also has metainformation about the columns (especially the name and value type of each column).

The data source is created through this statement:

        dataSource = new IlvTreeTableDataSource(tableData);

and then connected to the chart:

        chart.setDataSource(dataSource);

Reading an Excel spreadsheet into a data source

To read the contents of an Excel spreadsheet into a Java program, the user first has to save the spreadsheet in XML format from within Excel. Then the Java program can access the contents through the usual XML APIs. The code transforming an Excel XML file to Java objects in memory is found in class Workbook.

Reading a CSV file into a data source

To read the contents of a CSV file into a Java program, the class is used.

Performing automatic partitioning in the data source

The partitioning functionality that groups together several model objects is built and parametrized in the class . In this case, the partitioning criterion depends on a column. If the column is numerical, you request a uniform scale subdivision; if the column values are strings, you let the partitioning group together all objects that have the same value for that column.

        IlvPartitionerFactorycolumn0Partitioner =
             (Number.class.isAssignableFrom(column0.getType())
             ? (IlvPartitionerFactory) new IlvUniformScalePartitionerFactory(column0, 4, 5)
             : (IlvPartitionerFactory) new IlvStringPartitionerFactory(column0));
        dataSource.setPartitionerFactories(
            new IlvPartitionerFactory[] {
                column0Partitioner
            });

Connecting a tree-table to the data source

The tree-table displays the objects of a tree, with optionally the column values in separate columns. Since there is no standard tree-table model class, a copy of Sun's tree-table implementation in the package treetable is available. You need to create an adapter from the tree model of the data source to this kind of tree model, and instantiate the class.

        IlvTreeListToTreeTableModelFactory factory =
            new IlvTreeListToTreeTableModelFactory();
        TreeTableModeltreetableModel =
            (TreeTableModel)
            factory.createAdapter(dataSource.getLastingTreeModel(),
                                  TreeTableModel.class);
        treetable = new JTreeTable(treetableModel);

Note: Due to a limited horizontal width, the sample cannot display the columns but just the tree. In this case, a JTree would be sufficient. But in general, a treemap is best combined with a tree-table.

Enabling labels in the treemap

Labels for the larger rectangles in the treemap give some broad impression about the structure displayed in the treemap. There are a few choices involved here: Which contents should be displayed in the labels? What to do if a label does not fit into the rectangle to which it belongs: show it entirely, or clip it, or hide it entirely? This is customized in these lines of code:

        IlvTreemapChartRenderer renderer = ...;
        renderer.setLabelColumnName("Name");
        renderer.setAnnotation(new IlvDataLabelAnnotation());
        renderer.setAnnotationVisibility(IlvTreemapChartRenderer.VISIBILITY_SMART);
        renderer.setClippedAnnotationVisibility(false);

Enabling tooltips on the treemap

Tooltips on the treemap allow you to identify the smaller rectangles in the treemap and to determine the identifier of groups of rectangle, without having to click on each of them.

To install the tooltips, use the following code:

        IlvTreemapChartRenderer renderer = ...;
        renderer.setLabelColumnName("Name");
        treemapChart.addInteractor(new IlvChartInfoViewInteractor());

Displaying a selection in the treemap

The IlvChart does not have a selection model by itself. To display a selected object you can adopt one of the following solutions:

Use an that modifies the rendering of the particular object. Install it through the API.
Introduce a CSS pseudoclass, for example named "selected", and define a CSS rule that displays all objects with this pseudoclass in a different way. Activate it by calling .

In this sample, you are going to use the first solution.

For convenience, the class has a getSelection/setSelection/ selectionChanged API that makes it look like a single-selection model.

Synchronizing the selection between the treemap and the tree-table

Since on the treemap, for simplicity, you have chosen to support only single selection, you will do the same on the tree-table:

        treetable.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);

Furthermore, you can add a listener that will update the treemap selection when the tree-table selection changes, and another listener for the opposite direction:

        treetable.getSelectionModel().addListSelectionListener(...);
        treemapPanel.addPropertyChangeListener("selection", ...);

Drill-down (zoom) in the treemap

The drill-down operation limits the display of the treemap to a subtree of the original tree model. The root of this subtree is called the focus of the treemap. An API for querying and setting the focus is provided in the IlvTreemapChartRenderer class. The code for drill-down is a straighforward application of this API:

        TreePath next = selection;
        TreePath current = renderer.getFocus();
        history.addLast(current);
        renderer.setFocus(next);

Choosing the area column

The table column whose values determine the area of an object is set through a simple statement:

        renderer.setAreaColumnName(columnName);

Choosing color column and color scheme

Similarly, the table column whose values determine the color of a rectangle in the treemap is set through a single statement. Together with it, you also set the color scheme: For numerical columns you choose a continuous color scheme, whereas for string-valued columns you choose a color scheme that treats the possible values simply as distinct enumerated values and attempts to maximize the contrast.

        renderer.setColorColumnName(columnName);
        renderer.setColorScheme(column.getType() == String.class
                ? IlvTreemapChartRenderer.COLORSCHEME_QUALITATIVE
                : IlvTreemapChartRenderer.COLORSCHEME_DIVERGING_RED_GREEN);

Installation Directory

The Treemap Charts sample is installed here.