This is an old revision of the document!
The documentation available for prefuse is quite sparse, it consists mainly of the JavaDoc API documentation and demo source code. Even though the demo source code provides as good starting point (cp. [Heer et al., 1995] ), in my opinion the examples are overly complex for beginners.
Therefore, this tutorial starts with the minimum source code to create a scatter plot and incrementally adds features. Further, it discusses an axis-based visualization technique, whereas the documentation of prefuse focuses on graph visualization. The demo application is inspired by Jeffrey Heer's Congress demo, but achieves its functionality in small incremental steps.
Here we create the outline of our demo application. It is designed very simple and consists of four static methods:
This shows, how we create a data table for our tutorial. We use hard coded values so that the demo application stays self-contained. It would be easy to replace this method by a call to prefuse's DelimitedTextTableReader
.
private static Table generateTable() { Table table = new Table(); // use a calendar for input of human-readable dates GregorianCalendar cal = new GregorianCalendar(); // set up table schema table.addColumn("Date", Date.class); table.addColumn("BMI", double.class); table.addColumn("NBZ", int.class); table.addColumn("Insult", String.class); table.addRows(3); cal.set(2007, 11, 23); table.set(0, 0, cal.getTime()); table.set(0, 1, 21.0); table.set(0, 2, 236); table.set(0, 3, "F"); cal.set(2008, 6, 22); table.set(1, 0, cal.getTime()); table.set(1, 1, 35.8); table.set(1, 2, 400); table.set(1, 3, "F"); cal.set(2009, 3, 8); table.set(2, 0, cal.getTime()); table.set(2, 1, 28.8); table.set(2, 2, 309); table.set(2, 3, "T"); return table; }
Next, we extend the method createVisualization(Table)
and add the minimal source code to show a scatter plot.
First, we need to create instances of Visualization and Display and link these with each other and the data table.
Visualization vis = new Visualization(); Display display = new Display(vis); vis.add("data", data);
Second, we create a AxisLayout for the x axis and another one for the y axis. When these layouts are run, they will set the x and coordinate of all visual items.
AxisLayout x_axis = new AxisLayout("data", "NBZ", Constants.X_AXIS, VisiblePredicate.TRUE); AxisLayout y_axis = new AxisLayout("data", "BMI", Constants.Y_AXIS, VisiblePredicate.TRUE);
Third, a ColorAction will set the color of all visual items to blue.
ColorAction color = new ColorAction("data", VisualItem.STROKECOLOR, ColorLib.rgb(100, 100, 255));
Fourth, these actions are combined to an ActionList and linked to the Visualization.
ActionList draw = new ActionList(); draw.add(x_axis); draw.add(y_axis); draw.add(color); vis.putAction("draw", draw);
Finally, we run this ActionList and return the Display so that it can be shown in the window.
vis.run("draw"); return display;
This is the resulting visualization:
Now, we will add some more features to the scatter plot:
First, we want smaller shapes. For this, we create a ShapeRenderer with default size 7.
vis.setRendererFactory(new DefaultRendererFactory( new ShapeRenderer(7)));
Second, we add a DataShapeAction, so that our nominal parameter is shown as star or ellipse.
int[] palette = { Constants.SHAPE_STAR, Constants.SHAPE_ELLIPSE }; DataShapeAction shape = new DataShapeAction("data", "Insult", palette);
Third, the new action needs to be included in the action list.
We also add a RepaintAction, just to make sure that the visualization is repainted after the other actions.
draw.add(shape); draw.add(new RepaintAction());
Fourth, we set the Display to high quality (anti-aliasing), and change its size.
We also add an empty border, so that visual items at the edge of the visualization are better visible.
display.setHighQuality(true); display.setSize(700, 450); display.setBorder(BorderFactory.createEmptyBorder(15, 30, 15, 30));
Finally, we add a ToolTipControl to show the values of the two numeric parameters.
String[] tooltipparams = { "NBZ", "BMI" }; ToolTipControl ttc = new ToolTipControl(tooltipparams); display.addControlListener(ttc);
This is the resulting visualization:
In this step, we will add axis labels and grid lines to the visualization.
First, we have to use a new RendererFactory. Visual items from our data table will still be rendered by the ShapeRenderer, but for axis labels we will use AxisRenderer.
vis.setRendererFactory(new RendererFactory() { AbstractShapeRenderer sr = new ShapeRenderer(7); Renderer arY = new AxisRenderer(Constants.FAR_LEFT, Constants.CENTER); Renderer arX = new AxisRenderer(Constants.CENTER, Constants.FAR_BOTTOM); public Renderer getRenderer(VisualItem item) { return item.isInGroup("ylab") ? arY : item.isInGroup("xlab") ? arX : sr; } });
Second, we create two instances of AxisLabelLayout and initialize them with the AxisLayouts.
When these layout actions are run, they generate new visual items for the axis labels.
AxisLabelLayout x_labels = new AxisLabelLayout("xlab", x_axis); AxisLabelLayout y_labels = new AxisLabelLayout("ylab", y_axis);
Third, the new layout actions needs to be included in the action list.
draw.add(x_labels); draw.add(y_labels);
Fourth, we create an ItemSorter, so that data items will be displayed in front of the grid lines.
display.setItemSorter(new ItemSorter() { public int score(VisualItem item) { int score = super.score(item); if (item.isInGroup("data")) score++; return score; } });
This is the resulting visualization:
Here we will some interactivity to our demo application.
First, we create a new ActionList with all actions that we need to update the visualization.
ActionList update = new ActionList(); update.add(x_axis); update.add(y_axis); update.add(x_labels); update.add(y_labels); update.add(new RepaintAction()); vis.putAction("update", update);
Second, we an implementation of ComponentListener to the Display, which will run the new ActionList, whenever the user changes the size of the window – and thus resizes the Display.
display.addComponentListener(new ComponentAdapter() { public void componentResized(ComponentEvent e) { vis.run("update"); } });
Third, we add three ready-made controls to the Display.
display.addControlListener(new PanControl()); display.addControlListener(new ZoomControl()); display.addControlListener(new ZoomToFitControl());
This is the resulting visualization:
Now, we add a few refinements on the display of axis.
First, we add a new column to the VisualTable, which will contain a derived value from two columns. We also insert captions and format one of the variables.
Note: In order to access the VisualTable we have to replace add
with addTable
.
VisualTable vt = vis.addTable("data", data); vt.addColumn("label", "CONCAT('NBZ: ', [NBZ], '; BMI: ', FORMAT([BMI],1))");
Second, we set the range of the y axis, so that values from 1 to 40 are visible.
y_axis.setRangeModel(new NumberRangeModel(1, 40, 1, 40));
Third, we use a square root scale for y axis.
y_axis.setScale(Constants.SQRT_SCALE); y_labels.setScale(Constants.SQRT_SCALE);
Fourth, we define a number format and use it for y axis labels.
NumberFormat nf = NumberFormat.getNumberInstance(); nf.setMaximumFractionDigits(1); nf.setMinimumFractionDigits(1); y_labels.setNumberFormat(nf);
Finally, we use the new derived column for tool tips.
ToolTipControl ttc = new ToolTipControl("label");
This is the resulting visualization:
Here we manipulate the bounding boxes for the visualization of the data and both axes. This has two effects:
Note: If AxisRenderer have the FAR_LEFT
, FAR_RIGHT
, FAR_TOP
, or FAR_BOTTOM
, the grid lines will fill the bounding box completely and labels will be placed outside the bounding box.
Warning: Be careful, prefuse will not stop you from designing misleading visualizations, if the bounding boxes of data and axes are not correctly aligned
First, we define three rectangles for the visualization of the data and both axes.
Note: The variables are final so that they are accessible from inner classes. Alternatively they could be defined as instance variables.
final Rectangle2D boundsData = new Rectangle2D.Double(); final Rectangle2D boundsLabelsX = new Rectangle2D.Double(); final Rectangle2D boundsLabelsY = new Rectangle2D.Double();
Second, we set the bounding box for data items on the AxisLayouts.
x_axis.setLayoutBounds(boundsData); y_axis.setLayoutBounds(boundsData);
Third, we add the bounding box for axes to their initialization.
AxisLabelLayout x_labels = new AxisLabelLayout("xlab", x_axis, boundsLabelsX); AxisLabelLayout y_labels = new AxisLabelLayout("ylab", y_axis, boundsLabelsY);
Fourth, instead of the empty border, we now use a titled border.
display.setBorder(BorderFactory.createTitledBorder("Demo"));
Fifth, we add the call to a new method updateBounds()
, before each call to an action list (two times).
updateBounds(display, boundsData, boundsLabelsX, boundsLabelsY); ... updateBounds(display, boundsData, boundsLabelsX, boundsLabelsY);
Finally, this is the method updateBounds()
, which sets the bounds as described above.
private static void updateBounds(Display display, Rectangle2D boundsData, Rectangle2D boundsLabelsX, Rectangle2D boundsLabelsY) { int paddingLeft = 30; int paddingTop = 15; int paddingRight = 30; int paddingBottom = 15; int axisWidth = 20; int axisHeight = 10; Insets i = display.getInsets(); int left = i.left + paddingLeft; int top = i.top + paddingTop; int innerWidth = display.getWidth() - i.left - i.right - paddingLeft - paddingRight; int innerHeight = display.getHeight() - i.top - i.bottom - paddingTop - paddingBottom; boundsData.setRect(left + axisWidth, top, innerWidth - axisWidth, innerHeight - axisHeight); boundsLabelsX.setRect(left + axisWidth, top + innerHeight - axisHeight, innerWidth - axisWidth, axisHeight); boundsLabelsY.setRect(left, top, innerWidth + paddingRight, innerHeight - axisHeight); }
This is the resulting visualization:
alex @ ieg: home about me publications research