Data visualization

The purpose of this document is not to exhaust the graphics features of the library and graphics components which are already built in. There are good reasons why such a goal would be inappropriate:

• the library it's still in working phase, even there are many components ready for production use; any careful enumeration would be incomplete as soon as another graphical features would be added
• stressing the whole features even for a single component would be time consuming since working with all the combinations of graphical aspect options would take too much space to time for everybody

The goal of this document is to illustrate the core ideas behind the graphic system and to provide enough examples to have a fast and productive feedback.

The design of the graphical components of this library is influenced by many ideas from existing popular graphical systems. Among the main inspirations there are some which deserves appropriate consideration: R standard graphical library, ggplot2 package and matplotlib from Python stack.

Brief overview

Drawing of graphical figures or text output is handled by classes which implements interface rapaio.printer.Printer. There are some built-in implementations of this interface. The default one is StandardPrinter, which allows printing text at console and drawing graphics in a Swing modal window. Another used implementation is IdeaPrinter, which is similar with standard printer for text output, but for graphics drawing implements a TCP/IP protocol with serialization which allows plug-ins like rapaio-studio to handle graphics drawing.

A printer can be instantiated by itself by a handy way of using it is by the means of the utility class called rapaio.sys.WS (which comes from Work Wpace). This is an utility class which offers static shortcut methods yo allow one to simulate a working session. This class has an instance of a printer implementation (which can be changes by WS.setPrinter method) and shortcuts for text output and drawing.

We are interested here in methods for drawing, so the workspace contains methods for this purpose. All of those methods works with a construct which contains all the indications regarding what kind of graphic should be built. This construct implements interface rapaio.graphics.base.Figure. Thus a figure is a construct which allows the printer system to obtain images which can be later drawn over graphical surfaces. Also, there are methods which allows one to obtain an image directly from a figure, or store an image directly on a disk file.

Here are the shortcut methods implemented in WS utility:

• void draw(Figure figure) - draws a figure in a printing system; the size of drawing is either adaptive of has the default size of a graphical image contained in the printer implementation.

• void draw(Figure figure, int width, int height) - draws a figure with dimensions specified by width and height

• BufferedImage buildImage(Figure figure) - builds an image from a figure with dimensions specified as default width and default height from printer system

• BufferedImage buildImage(Figure figure, int width, int height) - builds an image from a figure with specified dimensions

• void saveImage(Figure figure, int width, int height, String fileName) - builds an image with specified dimensions by width and height from a given figure, and save the image into a png file with the specified file name

• void saveImage(Figure figure, int width, int height, OutputStream os) - builds an image with specified dimensions by width and height, and send the image in png format to the specified output stream (could be a file or could be sent over network)

Now in order to build figures one can instantiate and compose figures directly in a pure Java way. Here is an example:

Plot plot = new Plot();
plot.add(new Histogram(iris.var("sepal-length"), 0, 10, 
    bins(40), color(10), prob(true)));
plot.add(new DensityLine(iris.var("sepal-length"), lwd(2), color(2)));
WS.draw(plot);

It is simple enough and structured. However graphical tools offers also a class named rapaio.graphics.Plotter which has a lot of shortcut methods to help one to simplify the above code. Here is an example:

WS.draw(hist(iris.var("sepal-length"), 0, 10, bins(40), color(10), prob(true))
        .densityLine(iris.var("sepal-length"), lwd(2), color(2)));