Multi plot

Multi plot is a powerful visualization type that lets you combine several plots in one view and configure them in detail using a JSON record. With Multi plot you can:

Use any basic or advanced plot type (Line, Bar, Scatter, Pie chart, Parallel coordinates, Audio, etc.).
Run a single plot with extra configuration options.
Show multiple plots at once in a grid layout.
Control axes, labels, memory, batch behavior, size/color axes, and more.
Route different parts of a result (dimensions or tags) to separate plots.

You select Multi plot in SA Studio by choosing Multi plot from the visualization selector.

Basic structure

A Multi plot configuration is described by a JSON record. There are two main forms:

Single plot via sa_plot:

{
  "sa_plot": "Line plot",
  "memory": 200
}

Multiple plots via sa_plots:

{
  "sa_plots": [
    "Line plot",
    { "sa_plot": "Scatter plot", "memory": 500 },
    "Bar plot"
  ],
  "labels": ["x", "y"]
}

Attributes outside sa_plot / sa_plots (such as labels) apply to all plots unless overridden inside a specific sa_plot record.

The general usage pattern in OSQL is:

//plot: Multi plot
{ /* multi-plot JSON record */ };
select ...

Using Multi plot for single plots

You can use Multi plot even when you only want one plot. This gives you access to additional parameters compared to using the simple //plot: <type> form.

Example: Single Scatter plot with explicit axes

//plot: Multi plot
{
  "sa_plot": "Scatter plot",
  "labels": ["x", "y", "size", "color"],
  "size_axis": "size",
  "color_axis": "color",
  "memory": 500
};
select [cos(x), sin(x), mod(round(x),2), cos(x)*sin(x)]
  from Number x
 where x in heartbeat(0.01)*100
 limit 500;

Here Multi plot configures a single Scatter plot and sets:

labels for the vector dimensions.
size_axis and color_axis so Scatter plot uses the right dimensions for size and color.
memory to control how many points are kept when streaming.

Multiple plots in one view

Multi plot really shines when you combine several plots in a single visualization.

Example: Line, Scatter, and Bar from the same data

//plot: Multi plot
{
  "sa_plots": [
    { "sa_plot": "Line plot"},
    { "sa_plot": "Scatter plot", "memory": 500 },
    { "sa_plot": "Bar plot", "batch": 1 }
  ],
  "labels": ["x", "y"]
};
select [simsig(x), sin(x)]
  from Number x
 where x in siota(1,200)/10;

The Line plot shows the two series over time.
The Scatter plot visualizes the same series as points.
The Bar plot buffers the data ("batch": 1) and can show a bar-based summary.
labels are applied to all plots.

By default, all outputs are sent to all plots unless you explicitly route them.

Common Multi plot parameters

Some useful attributes when configuring plots in Multi plot:

sa_plot: plot type, e.g., "Line plot", "Scatter plot", "Bar plot", "Pie chart", "p-coords", "Text", "Audio", etc.
sa_plots: list of plot definitions (strings or full sa_plot records).
labels: labels for dimensions when input is a vector; often shared across plots.
batch: 1 to buffer until end of stream and then render as a batch; 0 to stream as normal.
memory: number of points/records to keep in memory when streaming (for incremental data types).
size_axis: for Scatter plot; label, index, or "none" specifying size.
color_axis: for Scatter plot; label, index, or "none" specifying color.
grid: layout configuration (see Layout and grid).

Specific plots may support additional parameters; see their dedicated documentation.

Plotting all outputs in all plots (default)

The default behavior is that all outputs from the query are sent to all plots in sa_plots.

Example: Vector in four different plots

//plot: Multi plot
{
  "sa_plots": [
    { "sa_plot": "Line plot", "labels": ["simsig", "cos", "mod", "ratio"], "memory": 100 },
    { "sa_plot": "Scatter plot", "labels": ["simsig", "cos"], "size_axis": "mod", "color_axis": "ratio" },
    { "sa_plot": "Bar plot", "batch": 1 },
    { "sa_plot": "Pie chart"}
  ]
};
select [simsig(x), sin(x), mod(round(x),2), (sin(x)+1.1)/(cos(x)+1.1)]
  from Number x
 where x in siota(1,200)/10
 order by x;

All plots receive the same four-dimensional vector stream but visualize it differently.

Routing different parts of output to separate plots

You can route different dimensions or labels to separate plots. One common approach is:

Give each dimension a label (either by returning a record or using labels).
In each sa_plot record, specify which labels that plot should use.

Example: Two Line plots showing different dimensions

//plot: Multi plot
{
  "labels": ["x", "y"],
  "sa_plots": [
    { "sa_plot": "Line plot", "labels": ["x"] },
    { "sa_plot": "Line plot", "labels": ["y"] }
  ]
};
select [simsig(x), cos(x)]
  from Number x
 where x in siota(1,200)/10;

Conceptually:

The first Line plot visualizes the series labeled "x".
The second Line plot visualizes the series labeled "y".

The exact set of routing attributes can depend on the visualization implementation, but the general idea is to use labels and per-plot configuration to choose which parts of the output each plot should receive.

Tagged streams and separate plots

Multi plot can also split tagged streams into different plots. Tagged data is typically of the form:

["tag_name", value1, value2, ...]

A typical Multi plot definition for tagged data includes:

tagged: set to 1 to enable tagged-data handling.
tags / tag_accessor: which element holds the tag.
tag: specified per plot to indicate which tag that plot listens to.
value_accessor: specified per plot to indicate which element to plot.

Example: Three tagged streams into three Line plots (conceptual)

{
  "tagged": 1,
  "tags": ["runtime", "simstream", "sinus"],
  "tag_accessor": 0,
  "sa_plots": [
    { "sa_plot": "Line plot", "tag": "runtime",  "value_accessor": 1 },
    { "sa_plot": "Line plot", "tag": "simstream", "value_accessor": 1 },
    { "sa_plot": "Line plot", "tag": "sinus",    "value_accessor": 1 }
  ]
}

In this setup:

Input is a single merged stream of tagged vectors.
Each Line plot only receives values for its configured tag.
value_accessor tells each plot which element in the tagged vector to visualize.

The exact OSQL query will depend on how you generate and merge your tagged streams, but the pattern above shows how Multi plot routes tags to separate plots.

Layout and grid

Multi plot uses a simple grid system to position plots. Each sa_plot record can have a grid attribute:

{
  "sa_plots": [
    { "sa_plot": "Line plot",  "grid": { "w": 6, "h": 6, "x": 0 } },
    { "sa_plot": "Scatter plot", "grid": { "w": 6, "h": 6, "x": 6 } }
  ]
}

Common fields in grid:

w: width of the plot in grid units.
h: height of the plot in grid units.
x: horizontal position (column) of the plot.
(Optionally) y: vertical position (row) in more complex layouts.

By adjusting grid, you can:

Place plots side by side.
Create multi-row dashboards.
Control relative sizes of plots.

Overlays

Multi plot supports overlays: extra graphics drawn on top of a plot without changing the underlying data. Overlays are sent as regular values in the stream, using a special sa_ovr field.

An overlay value never reaches the inner plots; instead it is intercepted by Multi plot and drawn on a transparent canvas in front of the targeted plot.

Basic overlay message

The minimal overlay structure is:

{
  "sa_ovr": "any-id",
  "objects": [ /* overlay objects */ ]
}

sa_ovr: selects which plot should receive the overlay.
- If there is only one plot, the value is ignored and the overlay is applied to that plot.
- If there are multiple plots, sa_ovr must match the id field of one of the plots in sa_plots.
objects: list of drawing objects (see Overlay object types).

You send overlay messages after you have configured the Multi plot and started sending data to it.

Example: Single-plot overlay

//plot: Multi plot
{ "sa_plot": "Line plot" };

-- Stream some data first
select [x]
  from Number x
 where x in range(4);


-- Then send an overlay
{
  "sa_ovr": "anything",
  "mode": "replace",
  "objects": [
    { "type": "line",  "x1": 10, "y1": 10, "x2": 200, "y2": 10, "color": "#f00", "width": 2 },
    { "type": "text",  "text": "Hello overlay", "x": 20, "y": 100, "color": "#0a0", "size": 14 }
  ]
};

Since there is only one plot, the overlay is applied to that plot even though sa_ovr is arbitrary.

Example: Multi-plot overlay with ids

//plot: Multi plot
{
  "sa_plots": [
    { "sa_plot": "Line plot", "title": "Left",  "id": "left",  "grid": {"h": 12, "w": 50} },
    { "sa_plot": "Line plot", "title": "Right", "id": "right", "grid": {"h": 12, "w": 50} }
  ],
  "use_grid": true
};

-- Data
[[0,0.5],[1,1.2],[2,2.5],[3,2.0],[4,1.0]];

-- Overlay only on the right plot
{
  "sa_ovr": "right",
  "mode": "replace",
  "objects": [
    { "type": "circle", "x": 120, "y": 80, "r": 30, "color": "#00f", "fill": "#00f3", "alpha": 0.6 },
    { "type": "rect",   "x": 20,  "y": 50, "w": 60, "h": 30, "color": "#fa0" }
  ]
};

-- Append text overlay on the right plot
{
  "sa_ovr": "right",
  "mode": "append",
  "objects": [
    { "type": "text", "text": "Right plot", "x": 25, "y": 45, "color": "#fff", "size": 12, "bg": "#0007" }
  ]
};

-- Overlay dashed line on the left plot
{
  "sa_ovr": "left",
  "mode": "replace",
  "objects": [
    { "type": "line", "x1": 10, "y1": 10, "x2": 180, "y2": 120, "color": "#0ff", "width": 3, "dash": [6,4] }
  ]
};

Here we use id in each plot definition and match it from the overlay via sa_ovr.

Overlay modes

The overlay object can control how new overlays combine with old ones:

mode: "replace": clear previous overlay graphics for the target plot before drawing the new objects.
mode: "append": keep existing overlay graphics and add the new objects on top.

You can also force clearing by setting clear: true in the overlay payload.

Overlay object types

objects is a list where each element has a type and type-specific fields. Supported types include:

"line":
- Required: x1, y1, x2, y2 (or points as a list of points).
- Optional: color, width, dash (e.g., [6,4]), alpha.
"circle":
- Required: x, y, r.
- Optional: color, fill, alpha, rSpace (see data-space below).
"arc":
- Required: x, y, r.
- Optional: start, end, color, fill, alpha, rSpace.
"rect":
- Required: x, y, w, h.
- Optional: color, fill, alpha, wSpace, hSpace.
"text":
- Required: text, x, y.
- Optional: color, size, font, align, baseline, bg.

Instead of objects, you may also use shortcut arrays lines, arcs, or texts, which are internally converted to objects of the corresponding type.

Data-space overlays (`space: "data"`)

By default, overlay coordinates are in pixel space (canvas coordinates). Multi plot also supports data-space overlays, where you specify coordinates in the same data domain as the plot axes. This is controlled by the space field:

Omit space or set space: "pixel" to use raw pixel coordinates.
Set space: "data" to interpret coordinates in data space.

When using space: "data", Multi plot needs axis domains, which it takes from:

overlay.axis.xDomain / overlay.axis.yDomain, if provided in the overlay object; otherwise
axis_opts.xDomain / axis_opts.yDomain from the plot definition; otherwise
A default domain [0, 1] for each axis.

Example: data-space overlay on a Scatter plot:

//plot: Multi plot
{
  "sa_plot": "Scatter plot",
  "axis_opts": {"xDomain": [0,5], "yDomain": [0,3]},
  "rescale": false
};

[[0,0.5],[1,1.2],[2,2.5],[3,2.0],[4,1.0]];

{
  "sa_ovr": "anything",
  "space": "data",
  "mode": "replace",
  "objects": [
    { "type": "line",   "x1": 0, "y1": 0.5, "x2": 4,   "y2": 1.0, "color": "#f00", "width": 2 },
    { "type": "circle", "x": 2, "y": 1.5, "r": 0.2, "rSpace": "data", "color": "#00f" },
    { "type": "text",   "text": "Data point", "x": 3, "y": 2.2, "size": 12, "color": "#fff", "bg": "#0007" }
  ]
};

Here, all coordinates are specified in the data domain ([0,5] on X and [0,3] on Y), and Multi plot maps them to pixel positions.

Summary

Multi plot is a meta-visualization that configures one or more plots using a JSON record.
Use sa_plot for a single plot with advanced configuration, or sa_plots for multiple plots.
Shared attributes (like labels, batch, memory) apply to all plots unless overridden.
You can route different dimensions or tagged values to separate plots.
The grid attribute lets you arrange plots in a dashboard-style layout.

For details on plot-specific options (axes, size, color, etc.), see the individual documentation for Line plot, Bar plot, Scatter plot, Audio, Parallel coordinates, and other visualization types.

Multi plot

Basic structure​

Using Multi plot for single plots​

Example: Single Scatter plot with explicit axes​

Multiple plots in one view​

Example: Line, Scatter, and Bar from the same data​

Common Multi plot parameters​

Plotting all outputs in all plots (default)​

Example: Vector in four different plots​

Routing different parts of output to separate plots​

Example: Two Line plots showing different dimensions​

Tagged streams and separate plots​

Example: Three tagged streams into three Line plots (conceptual)​

Layout and grid​

Overlays​

Basic overlay message​

Example: Single-plot overlay​

Example: Multi-plot overlay with ids​

Overlay modes​

Overlay object types​

Data-space overlays (space: "data")​

Summary​