Plotting

The Aleph Plotting module provides the Figure class for creating publication-quality data visualizations directly from your scripts. Figures are saved as .figure files in the workspace and can be viewed in the Workshop, embedded in Markdown documents, or exported as SVG and PNG.

---

Overview

The plotting workflow follows four steps:

1. Create a Figure object.
2. Add one or more data series. Currently supported data series include line, scatter, bar and heatmap.
3. Format the figure by calling methods of Figure.
4. Save (and optionally export) the result.

1. Creating a figure

To create a figure, it suffices to call the constructor Figure() and to store the output in a variable. Figure(existing_figure) creates a copy of existing_figure. The main use case for copying a figure is to create multiple figures in the same style with minimal boiler plate code.

// Creating an empty figure
var my_figure = Figure()
// ... format the figure or add data ...

// Creating a copy 
var copied_figure = Figure(my_figure)

2. Adding data

To add data to a figure, it suffices to call one of the supported data series method, which currently include line, scatter, bar and heatmap. For each of the supported data series type, their input format is summarized in the table below.

Data Series Methods

tip

Click the name of the series to access detailed examples and documentation showcasing the available options of the data series.

Series	Signature	Description
line	line(x, y [, options])	Pass a list of x and y data and optionally options.
line	line(points [, options])	Pass a list of points [[x[0],y[0]],[x[1],y[1]], ...] and optional configurations.
line	line(options)	Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes.
scatter	scatter(x, y [, options])	Pass a list of x and y data and optional configurations.
scatter	scatter(points [, options])	Pass a list of points [[x[0],y[0]],[x[1],y[1]], ...]
scatter	scatter(options)	Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes.
bar	bar(x, y [, options])	Pass a list of x (bin positions) and y (bin heights) data.
bar	bar(points [, options])	Pass a list of points [[x[0],y[0]],[x[1],y[1]], ...].
bar	bar(options)	Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes.
heatmap	bar(points [, options])	Pass a list of points [[x[0],y[0],z[0]],[x[1],y[1],z[1]], ...] and optional configurations.
heatmap	heatmap(options)	Pass an option. Data is specified through the "data" key ["data": [[x[0],y[0]],[x[1],y[1]], ...]]. Can also be used without data for formatting purposes.

note

Arguments displayed in square brackets [, ...] in the signature column are optional for that given overload. The x and y arguments can be either a list, an array or a range. Point data is a list containing sub-lists, where each sub-list contains either the coordinates [[coordinate1], [coordinate2]] of a data point, or when available the coordinates together with addional values to enable per-point formatting capabilities [[coordinate1, f11,f12,...], [coordinate2, f21, f22, ... ], ...]. Options arguments are Aleph maps ["arg1_name": arg1, "arg2_name": arg2, ...].

Quick examples

// LINE
var line_figure = Figure().line([1, 2, 3, 4], [1, 8, 27, 64])

// SCATTER
var scatter_figure = Figure().scatter([1, 2, 3, 4], [1, 4, 9, 16])

// BAR
var bar_figure = Figure().bar([1, 2, 3], [10, 30, 20])

// HEATMAP
var heat_map_figures = Figure().heatmap([[0,0,1],[0,1,2],[1,0,3],[1,1,4]])

---

3. Formatting a figure

The next step in the creation of a figure is formatting. The Figure class provides the following global methods to be combined with the per-series formatting options.

tip

Click the name of the method to access detailed examples and documentation showcasing its use.

Method	Signature	Description
title	title(string)	Sets the figure title.
x_axis	x_axis(options)	Configures the x-axis (name, ticks, font, scale).
y_axis	y_axis(options)	Configures the y-axis (name, ticks, font, scale).
legend	legend(options)	Adds and positions a legend box.
tooltip	tooltip(options)	Enables an interactive hover tooltip.
grid	grid(options)	Controls plot-area margins and size.
data_zoom	data_zoom(options)	Adds interactive zoom/scroll controls.
animation	data_zoom(options)	Controls the animations of the figures.
marks	mark_line(options)	Marks lines or points of interest.

note

Every method of Figure, including the constructor and data series method, return a reference to the figure itself. As such, calls can be chained one after the other if desired.

Quick examples

Figure()
    .line([1, 2, 3], [1, 4, 9])
    .title("My first figure")
    .x_axis(["name": "$x$", "name_location": "middle"])
    .y_axis(["name": "$f(x)$", "name_location": "middle"])
    .legend(["top": "top", "left": "10%"])
    .tooltip()
    .grid(["left": "15%", "bottom": "15%"])
    .data_zoom(["type": "slider"])
    .save("./figures/ex_fig_options")

4. Saving and exporting

To save the produced figure, it suffices to call the save("path_to_folder/file_name") writes the figure as a .figure file in the workspace. The .figure extension is added automatically.

Figure()
    .line([1, 2, 3], [1, 4, 9])
    .save("path_to_folder/file_name")

.figure files can be exported in two ways:

• From the file explorer: right-click the .figure file, select Download, and choose SVG or PNG.
• From the figure preview: use the export button in the top-right corner of the figure preview tab and choose your format.

Figures can be exported with a light theme (white background) via the export options.

Best Practices and extra tips

1. Always name your series. Pass ["name": "..."] to every data method to create self-documenting data sets.

2. Use LaTeX for scientific labels. Wrap math in $...$ inside titles, axis and names for properly rendered equations.

3. Reuse base figures. Use the copy constructor Figure(base) to share common formatting across multiple figures to avoid duplicating formatting code.

4. Use the chained style for self-contained plots. It keeps the figure definition in a single expression and avoids accidental mutation.

5. Use the variable style for iterative construction. When data is generated in a loop, storing the figure in a variable first and calling methods incrementally is more natural.

6. Edit interactively when possible. After generating a figure, use the Workshop's Edit figure button to fine-tune the title and series names in real time without re-running the script.

7. Include figures in markdown files .figure files can be rendered directly inside Markdown previews in the Workshop. To do so, after having saved your figure simply add the following line in the markdown file: ![figure_name.figure](path_to_figure/figure_name.figure)