Using treeMappa

There are three ways of using treeMappa: (i) from the command line as a stand-alone program; (ii) as a library via the Java API; or (iii) as a library with Processing.

This introduction focusses on using treeMappa with Processing.

Assuming you have downloaded the latest version of treeMappa and unzipped it into your Processing libraries folder, to make use of treeMappa in your Processing sketches you need to import the library:

import org.gicentre.treemappa.*;

You can check you have the latest version by adding the line

println(Version.getText());

somewhere in setup().

This should display the following message in the Processing console.

treeMappa V3.3.0, 18th April, 2016

You are also strongly advised to install the gicentreUtils library that contains the zooming and colour packages used in the examples below.

The link between TreeMappa and your sketch is handled by the PTreeMappa class. Below is a minimal example that creates a default treemap using PTreeMappa and a simple file life.csv (which can be found in the examples/ folder of the downloaded library). This file represents a simple tree of animals and plants and is rendered below as a simple treemap with default style:

import org.gicentre.treemappa.*;      // For treemappa classes
import org.gicentre.utils.colour.*;   // Colours needed by treemappa.

// Minimal example to draw a simple treemap directly in a sketch.
// Jo Wood, giCentre
// V1.3, 3rd April, 2014.

PTreeMappa pTreeMappa;                // Stores the treemap.

void setup()
{
  size(500,300);
  pTreeMappa = new PTreeMappa(this);  // Create an empty treemap.    
  pTreeMappa.readData("life.csv");    // Load the data and build the treemap. 
}

void draw()
{
  background(255);
  pTreeMappa.draw(); // Get treemappa to draw itself.
  noLoop();          // Draw once only.
}

Default rendering of simple treemap from life.csv

The default settings for a treemap produced this way labels only the 'leaves' of the tree data, that is, those values that do not enclose any further data inside them. Labels are displayed in the current processing font and leaf colours, if undefined, will use an evolutionary colour scheme that attempts to colour leaves slight variations in a randomly selected hue (blue in this example, but the selection will be random each time the treemap is generated).

Customising treemap appearance

treeMappa is highly customisable in terms of the text labels, colours, layout and borders around each data item. For full details of customisation options, see the treeMappa user guide. Most of the options detailed there have an equivalent method available from PTreeMappa. The following example shows an example of a customised version of the life treemap:

import org.gicentre.treemappa.*;     // For treemappa classes
import org.gicentre.utils.colour.*;  // Colours needed by treemappa.
import org.gicentre.utils.move.*;    // For the ZoomPan class.

// Simple example to draw a simple treemap with some appearance 
// customisation and a zoomable dispaly.
// Jo Wood, giCentre, 3rd April, 2014.

PTreeMappa pTreeMappa;
ZoomPan zoomer;

void setup()
{
  size(1000,600);
  zoomer = new ZoomPan(this);  
  
  // Display labels in a serif font
  textFont(createFont("serif",40));

  // Create an empty treemap.    
  pTreeMappa = new PTreeMappa(this);
  
  // Load the data and build the treemap.
  pTreeMappa.readData("life.csv"); 
  
  // Customise the appearance of the treemap
   
  TreeMapPanel tmPanel = pTreeMappa.getTreeMapPanel();
  tmPanel.setBorders(12);
  tmPanel.setShowLeafBorders(true);
  tmPanel.setBorder(0,0);      // No border around entire treemap.
  tmPanel.setBorder(2,6);      // Make leaf-level borders 6 pixels wide.
  tmPanel.setCurvature(10);    // Rounded rectangles.
   
  tmPanel.setShowBranchLabels(true);
  tmPanel.setLeafTextAlignment(RIGHT,BOTTOM);
  tmPanel.setBranchMaxTextSize(0,80);
  tmPanel.setBranchMaxTextSize(1,30);
  tmPanel.setLeafMaxTextSize(12);
  tmPanel.setAllowVerticalLabels(true);
  tmPanel.setBranchTextColours(color(0,50));
  tmPanel.setLeafTextColour(color(0,0,80));
  
  tmPanel.setColourTable(ColourTable.readFile(createInput("life.ctb")));
  tmPanel.setLayouts("strip");
  
  // Layout needs updating because we have changed border size and treemap layout.
  tmPanel.updateLayout();
}

void draw()
{
  background(255);
  zoomer.transform();    // Allow zooming and panning.
  pTreeMappa.draw();     // Get treemappa to draw itself.
}

Customisation of treemap appearance is handled by a TreeMapPanel which takes care of the visual representation of the treemap. This class contains many appearance customisation methods. To get access to the TreeMapPanel call the getTreeMapPanel() method of the PTreeMappa object.

In the example above, lines 29-33 set the border style of branches and leaves between adjacent branches including the spacing between rectangles and thickness of leaf and branch borders.

Lines 35-42 customise the colour and size of the text labels. Line 35 ensures that branch labels are displayed ('Life', 'Animalia' and 'Vegetabilia' in this example). Text size for leaves and branches is controlled by setting a maximum size in pixels. If the rectangle in which the label is displayed is too small for the given maximum text size, the label is shrunk until it fits inside the rectangle. Text sizes at different levels in the tree hierarchy can be set by using the two parameter versions of setBranchMaxTextSize() where the first parameter is the level of the hierarchy and the second is the text size to use. So lines 37-38 set the level 0 text ('Life') to a maximum of 80 pixels and level 1 text ('Animalia' and 'Vegetabilia') to a maximum of 30 pixels. Line 40 allows vertical text to be displayed vertically if the the label is too large to fit horizontally and rotating it provides more space. The colour of the labels is set in lines 41-42 (transparent grey for branches and a dark blue for leaves).

Treemap rectangle colours can be controlled by associating a colour table with the treemap (see the treeMappa user guide for details). The colour table is loaded in line 44 and uses the Processing command createInput() to load the file from the sketch's data folder.

TreeMappa comes with a variety of layout algorithms that control how rectangles are arranged. In the example above, line 45 gets TreeMappa to arrange rectangles in a StripMap layout (see the treeMappa user guide for details).

Finally, because the customisation has altered the layout of the rectangles in the treemap (both setting the border size and changing the layout algorithm affect layout), we have to call the updateLayout() method to ensure the new settings are applied (line 46). If you only customise the appearance of the treemap without changing layout (e.g. changing colours or text labelling), there is no need to call this method.

When displaying more complex treemaps with larger numbers of nodes and a deeper hierarchy, it is likely that not all rectangles will be visiable at once. It is easy to combine PTreeMappa with the giCentre Utilities ZoomPan class to create a zoomable treemap.

In the example below, the complex hierarchy stored in the file ontology.xml (again available in the examples/ folder of the downloaded library) is displayed. This uses the TreeML format, so requires the file format name to be specified when reading the data.

import org.gicentre.treemappa.*;     // For treemappa classes
import org.gicentre.utils.colour.*;  // Colours needed by treemappa.
import org.gicentre.utils.move.*;    // For the ZoomPan class.

// Draws a complex treemap with appearance customisation and zoomable display.
// Jo Wood, giCentre, 3rd April, 2013

PTreeMappa pTreeMappa;
ZoomPan zoomer;

void setup()
{
  size(1000,700);
  zoomer = new ZoomPan(this);  
  
  // Display labels in a serif font
  textFont(createFont("serif",40));

  // Create an empty treemap.    
  pTreeMappa = new PTreeMappa(this);
  
  // Load the data and build the treemap.
  pTreeMappa.readData("ontology.xml","treeML"); 
  
  // Customise the appearance of the treemap 
  pTreeMappa.getTreeMapPanel().setShowBranchLabels(true);
  pTreeMappa.getTreeMapPanel().setLeafMaxTextSize(4);
  pTreeMappa.getTreeMapPanel().setAllowVerticalLabels(true);
  pTreeMappa.getTreeMapPanel().setBranchTextColours(color(0,50));
   
  pTreeMappa.getTreeMapPanel().setBorders(0);
  pTreeMappa.getTreeMapPanel().setBorderColour(color(255));
  
  pTreeMappa.getTreeMapPanel().setLayouts("sliceAndDice");
  
  // Layout needs updating because we have changed border size and the
  // treemap layout algorithm.
  pTreeMappa.getTreeMapPanel().updateLayout();
}

void draw()
{
  background(255);
  
  // Allow zooming and panning.
  zoomer.transform();
  
  // Get treemappa to draw itself.
  pTreeMappa.draw();
}