Contents

Creating custom visualizations

Creating Plots

To take full advantage of plot.ly’s power requires a few steps:

Here’s a simple example, where we create a ScatterPlot from two numeric columns (colX and colY). A default layout is used because we didn’t supply one.

Trace trace = ScatterTrace.builder(colX, colY).build();
Plot.show(new Figure(trace));

Not so bad, right?

Rendering in a Web page

The call to Plot.show() above opens your local browser on the plot. If you prefer to serve your plots with an engine like Jetty, or in a Web framework like Spark Java, you can call the asJavascript() method on your figure. This returns the JavaScript code as a String. Send it where you will.

Some details

Layouts

A layout controls the appearance of a figure. A simple default layout is supplied if you don’t provide one. To create one, call Layout.builder(), and then supply the builder with the options you want. I could easily spend weeks documenting Layout, but his should get you started. When you need more information, you can use the Plot.ly documentation.

Basics

The most basic layout features are setting the figure’s title and the height and width.

Layout layout = Layout.builder()
		.title("My Title")
		.height(500)
		.width(650)
		.build();

To use this layout, we again construct a figure and (for interactive use) show it:

Trace trace = ScatterTrace.builder(colX, colY).build();
Plot.show(new Figure(layout, trace));

This would show the same plot as above, but with a title and different dimensions.

Other simple options include setting background colors and margins.

Layout layout = Layout.builder()
   		.plotBgColor("blue")
		.paperBgColor("red")
		.build();

These attributes change the background color of the plot and the surrounding area (paper). Colors can be specified by name or as hex strings. Hex strings, of course, will let specify colors that aren’t so jarring as a blue plot on a red background.

Fonts

To change to font for the title, specify a titleFont. You create one with a builder

Font f = Font.builder()
		.family("Arial")
		.size("24")
		.color("green")
		.build();
Layout layout = Layout.builder()
		.title("Your plot title here")
		.titleFont(f)
		.build();

The same approach we use here to format the plot title is used to set fonts anywhere text is displayed, such as a in a legend, an axis title, for hover text, or in a tick label.

Axes

Custom axes are extremely useful, and the many options are available.

Axis xAxis = Axis.builder()
		.title("date")
		.build();

Besides customizing the axes themselves, the Axis class is used to manage the display of a grid on the plot, and any “spikes” you want to use. Spikes are the lines drawn from a point to an axis when you hover over the point.

Grids

A pale grid is displayed by default. You can turn off it for a given axis by calling showGrid(false) on the Axis builder. Here’s an example of a custom grid format:

Axis xAxis = Axis.builder()
		.gridColor("grey")
		.gridWidth(1)
		.build();
Spikes

Here we create vertical spikes. You could reuse the spikes object created in a yAxis to get horizontal spikes as well. The general process of constructing and using spikes is shown below.

Spikes spikes = Spikes.builder()
		.dash("solid")
		.color("yellow")
		.build();
// put the spikes in the xAxis so we get vertical spikes
Axis xAxis = Axis.builder()
    	.spikes(spikes)
    	.build();
// put the xAxis in the builder
Layout layout = Layout.builder()
    	.xAxis(xAxis)
    	.hoverMode(HoverMode.CLOSEST)
    	.build();
// define your trace
Trace trace = ScatterTrace.builder(xCol, yCol).build();
// put the builder in your figure
Figure plot = new Figure(layout, trace);
Ticks

Like most things, there is a good default setting for ticks, so this is only needed if you want to customize your display. When you do, they’re also very flexible. Options are available for defining the ticks and labels either by a range, or by passing an array of positions and optional labels. You can also set their visibility, length, width, color, placement (inside or outside), and many other options. See the TickSettings class for details.

TickSettings ticks = TickSettings.builder()
    	.color("red")
    	.placement(Placement.OUTSIDE)
    	.build();
Axis yAxis = Axis.builder().tickSettings(ticks).build();
// etc.

Some sample plots

Scatters

double[] x = {1, 2, 3, 4, 5, 6};
double[] y = {0, 1, 6, 14, 25, 39};
String[] labels = {"a", "b", "c", "d", "e", "f"};

ScatterTrace trace = ScatterTrace.builder(x, y)
        .text(labels)
        .build();
        
Plot.show(new Figure(trace));

Line Plots

You can make the example above a line plot by adding a mode to the trace.

ScatterTrace trace = ScatterTrace.builder(x, y)
    .mode(ScatterTrace.Mode.LINE)
    .text(labels)
    .build();

Histograms

double[] y = {1, 4, 9, 16, 11, 4, -1, 20, 4, 7, 9, 12, 8, 6};

HistogramTrace trace = HistogramTrace.builder(y).build();
Plot.show(new Figure(trace));

Note that you can overlay two histograms by adding another trace, setting opacity, and providing a simple layout:

double[] y1 = {1, 4, 9, 16, 11, 4, 0, 20, 4, 7, 9, 12, 8, 6, 28, 12};
double[] y2 = {3, 11, 19, 14, 11, 14, 5, 24, -4, 10, 15, 6, 5, 18};

HistogramTrace trace1 = 	
    HistogramTrace.builder(y1).opacity(.75).build();
HistogramTrace trace2 =
    HistogramTrace.builder(y2).opacity(.75).build();

Layout layout  = Layout.builder()
    .barMode(Layout.BarMode.OVERLAY)
    .build();
Plot.show(new Figure(layout, trace1, trace2));

2-D Histograms

3-D Scatters

Bar plots

Object[] x = {"sheep", "cows", "fish", "tree sloths"};
double[] y = {1, 4, 9, 16};

BarTrace trace = BarTrace.builder(x, y).build();
Plot.show(new Figure(trace));

To render the above plot horizontally, we modify the trace slightly:

BarTrace trace = BarTrace.builder(x, y)
	.orientation(BarTrace.Orientation.HORIZONTAL)
	.build();

Box plots

Object[] x = {"sheep", "cows", "fish", "tree sloths", 
	"sheep", "cows", "fish", "tree sloths", 
	"sheep", "cows", "fish", "tree sloths"};
double[] y = {1, 4, 9, 16, 3, 6, 8, 8, 2, 4, 7, 11};

BoxTrace trace = BoxTrace.builder(x, y).build();
Plot.show(new Figure(trace));