Plotting and Saving Figures

Visualizing data is an incredibly important step that can be time consuming. Our plotting module follows a similar pattern to other plotting libraries:

1. Make a Figure object.
2. Add data.
3. Format the plot to your liking.
4. View and/or save the plot.

In Aleph, the above is done by creating the Figure object and then simply chaining methods that modify the plot. Currently all files must be saved before viewing, but they can be viewed within the workshop and included directly into markdown files as images.

The goal of this tutorial is to explain how to make, edit, view and export figures.

The Figure Class and Its Methods

To make a figure we create a Figure object with a simple call to the constructor Figure() inline. To populate the figure with data and edit it, methods need to be chained onto the object.

Figure().method1().method2() // chain in the same line.
// Or equivalently 
Figure()                     // chain on separate lines.  
.method1()
.method2()

Alternatively, one can also store the figure in a variable and call methods one line at a time.

var f = Figure()             // create and store into f
f.method1()                  // chain methods one at a time. 
f.method2()

In this tutorial we will stick with the first method, but both styles are equivalent and can be used as well. The methods follow the same option system as other classes in aleph, namely they are supplied by an option Map of the form

var options = ["option1": option1_value, "option2": option2_value]

We suggest strongly to consult the option documentation for each method to ensure the syntax is correct.

There are two kinds of methods for the Figure class: formatting methods and data plotting methods. The first kind are for editing text, moving labels around, and changing the layout of the plot. Examples of methods that will be used the most are included in the table below.

Method Name	Used To
title	set title of the figure.
x_axis	set the x-axis properties like axes names, ticks, font size.
y_axis	set the y-axis properties like axes names, ticks, font size.
legend	modify the legend location, size, text size.
save	save the figure in the workspace.

The second kind of methods relate to how the data itself is organized, i.e. how the data (also called a series) is plotted. The currently supported list of types is

Plot Type	Description
line	plot that connects two lists of $x,y$ data with a line.
scatter	plot of two list of disconnected points $x,y$ .
bar	plot of vertical bars from $x,y$ lists.
heatmap	2D heatmap from a list of points $[x,y,z]$.

Making Simple Plots

To begin plotting data, we follow the prescription above: create a figure and add some data to it. We can make a simple scatter plot with the following code:

Figure().scatter([1,2,3,4],[1,4,9,16]).save("my_first_figure")

Now let's give names to our axes and add a title.
Figure text supports LaTeX math formulas, which can be included inline using $...$.

Figure()
    .scatter([1,2,3,4],[1,4,9,16])    // Plot the data
    .title("Quadratic Growth")        // Set the title
    .x_axis(["name": "Input $n$"])    // Provide options to the x_axis
    .y_axis(["name": "Output $n^2$"]) // Provide options to the y_axis
    .save("my_first_figure")          // Save the figure

Here we added a title by passing a string to the title method while the axis formatting has been updated by passing options to the x_axis and y_axis methods. We set the name of the axes by passing the "name" key a string, this is the string we would like to identify the axes in the plot. Lastly we save the file just like before.

tip

Some edits can also be made interactively after the figure has been created. In the top-right corner of the figure window in the workshop you can click on the "Edit figure" button and then modify the figure title and the series names in the legend.

We can make the figure a bit cleaner by first centering the axis names, as well as increasing the size of the font of each of the names.

Figure()
    .scatter([1,2,3,4],[1,4,9,16])
    .title("Quadratic Growth")
    .x_axis([
        "name": "Input $n$",
        "name_location": "middle",  
        "axis_label": ["font_size": 12],
        "name_text_style": ["font_size": 25]])
    .y_axis([
        "name": "Output $n^2$",
        "name_location": "middle",  
        "axis_label": ["font_size": 12],
        "name_text_style": ["font_size": 25]])
    .save("my_first_figure")

In the above code we supplied an explicit location for the axis names by setting the name_location while also modifying name_text_style. We also increased the axis_label font size explicitly. Many options are available to suit your various editing needs, you can learn more about them here

Lastly, we can also add more data to this plot and display a legend to identify both of the data series.

Figure()
    .scatter([1,2,3,4],[1,4,9,16], ["name": "scatter"])           
    .line([1,2,3,4],[1,2,3,4], ["name": "line"])        // Another plot in the same figure
    .title("Multiple plots")
    .legend(["left": "10%", "top": "top"])              // Add legend
    .x_axis([
        "name": "Input $n$",
        "name_location": "middle",  
        "axis_label": ["font_size": 18],
        "name_text_style": ["font_size": 25]])
    .y_axis([
        "name": "Output $n^2$",
        "name_location": "middle",  
        "axis_label": ["font_size": 18],
        "name_text_style": ["font_size": 25]])
    .save("my_first_figure")

We added in another plot in the figure using line and passed data to it, as well as scatter, and a name so that we can identify them. Then we included a legend by chaining legend and set its location with the options map. The left option key is the location of the left side of the legend which we set to be at 10% of the "left" side of the figure. Similarly, the top option key is the location of the top of the legend which we set to be the "top" of the figure. This is an example of how locations are chosen in the plotting module: individual figure items, like the legend, have option keys that specify the location of the extremities of the item boxes, and take in option values that are relative to the entire figure.

Exporting figures

As we mentioned above, all figures are saved in the workshop as a .figure file. However, they can be exported to two formats: svg and png. This can be done in the file explorer by right-clicking the .figure file, selecting "download" and then choosing your file format. Figures can also be downloaded in the figure preview window in the top-right corner and selecting your export format.

What To Do Next

• Try using different symbols for the markers.
• Try changing the color of the lines.
• Try all the plotting types, we only used 2 of the available 4 kinds.
• Remove the grid lines.
• Play with the axis scales.

Documentation Contributors

Sebastien J. Avakian

Julien Blin