show chart

The show chart is a complex syntax used to construct graphs that are more complex than show linechart, show scatter and show plotxy. Its main advantage is that it allows building a chart from data in multiple tables.

Introduction

Example

Here is an example that uses show chart to draw four parametric curves:

K = 1000
PI = 3.141592741
 
table T = extend.range(K)
T.Alpha = 2 * PI * ((T.N-1) / (K-1))
T.X = (cos(T.Alpha) - cos(3 * T.Alpha)^3) * 0.3 + 0.5
T.Y = (sin(T.Alpha) - sin(3 * T.Alpha)^3) * 0.3 + 0.75
T.X2 = cos(T.Alpha) - cos(T.Alpha)^3 - 0.5
T.Y2 = sin(T.Alpha) - sin(T.Alpha)^3 - 0.5
 
show chart "" a1c4 tomato with
  plotxy T.X 
    T.Y 
    T.Y2  { color: red }
    order by T.Alpha
  plotxy T.X2
    T.Y { color: blue }
    T.Y2 { color: cyan }
    order by T.Alpha

The script defines four series of numbers $X$, $X_2$, $Y$ and $Y_2$, which are then combined to produce four series $(X,Y)$, $(X,Y_2)$ (in the first plotxy block) and $(X_2, Y)$, $(X_2, Y_2)$ (in the second plotxy block).

This displays the following dashboard tile:

Syntax

The general syntax of show chart is the following:

show chart ... with // tile-level options (title, position...)
  // one level of indentation
  plotxy EXPR // block name followed by vector of horizontal 
              // coordinates for all series in the block
    // another level of indentation
    EXPR // a series in the block, given as a vector 
    EXPR as "NAME" { color: red } // another series, with formatting    
    order by EXPR // optional

In short:

• The initial line show chart follows the same rules as other show statements, and is followed by a mandatory with that introduces an indented region where the blocks will be defined.
• Blocks are introduced by a line with their name, such as plotxy and (usually) an expression providing the horizontal coordinates for that entire block. That line is followed by an even more indented region where the other block columns are provided.
• Block columns follow the same syntax as columns in other show statements. A final order by may be provided, but not group by.

Nested filtering

As an extension to the above rules, the body of a show chart also allows where statements. For example, the example below displays the same series with two filters, one in black and the other in red:

table T = extend.range(100)
T.X = T.N / 100
T.Y = random.normal(T.0, T.2)
T.D = abs(T.Y) > 1

show chart "" a1c3 with 
  where T.D 
    scatter T.X 
      T.Y { color: red }
  where not T.D
    scatter T.X
      T.Y { color: black }

This example displays the following tile:

Supported blocks

The block types allowed in show chart are the following:

• The haxis specifies the values and/or style information for the horizontal axis.
• The laxis and raxis specify the values and/or style information for the left and right vertical axes.
• A scatter draws individual points given by their $(X,Y)$ coordinates. Similar to show scatter.
• A plotxy draws a curve through points given by their $(X,Y)$ coordinates. Similar to show scatter.
• A plot is like plotxy, but always drawn left-to-right and two $(X, Y)$ coordinates may not share the same $X$ value. Series can be displayed as lines, areas, or bars. Similar to show linechart.

Axis blocks

A show chart has three axes: one horizontal, and two vertical (left and right). The axis blocks help configure the behavior of those axes. If provided, they must always appear before all other blocks, and always in the order haxis, then laxis, then raxis.

haxis

The haxis, or horizontal axis, is a fundamental element of a show chart, and comes in two different versions: a free horizontal axis lets every other block provide its own set of horizontal coordinates, wheras a constrained horizontal axis provides a finite list of values and forbids other blocks from providing horizontal coordinates that are not in that list. The choice of a free or constrained axis will impact the availability of certain blocks and axis data types:

Free horizontal axis

To use a free horizontal axis, either provide no haxis block at all, or provide one with only a StyleCode block. The example below specifies that the haxis should be displayed using € as a unit:

table T = extend.range(10)
T.X = 10 * T.N
T.Y = 30 * T.N

show chart "Free haxis" a1c3 with 
  haxis { unit: "€" }
  scatter T.X
    T.Y

This example displays the following tile. Note how the labels on the horizontal axis include the € symbol.

When using a free horizontal axis, the data type of that axis is set by the horizontal coordinates vector of the first block, and must be one of number, date, week or month. Subsequent blocks must have horizontal coordinates of the same data type (it is not possible to mix number and date horizontal coordinates, for example).

Constrained horizontal axis

The use a constrained horizontal axis, you need to provide the set of values that will be displayed on the axis. This is usually done with the haxis by EXPR syntax, which creates the horizontal axis from all the distinct values taken by EXPR.

The example below defines a horizontal axis from all products (this will be “socks” and “hats”), and displays historical sales as multiple points associated with each product:

table Sales = with 
  [| as Product, as Date, as Quantity |]
  [| "socks", month(2024, 12), 10 |]
  [| "socks", month(2024, 11),  3 |]
  [| "hats",  month(2024, 12),  4 |]
  [| "hats",  month(2024, 11), 11 |]

show chart "" a1c3 with  
  haxis by Sales.Product
  scatter Sales.Product
    Sales.Quantity

Alternatively, an axis can be created with the haxis into TABLE syntax, which uses all the values in the primary dimension of TABLE as the value for the axis.

The example below defines a Products table with the product name as its primary dimension, and displays a bar chart of the total quantity sold by product.

table Sales = with 
  [| as Product, as Date, as Quantity |]
  [| "socks", month(2024, 12), 10 |]
  [| "socks", month(2024, 11),  3 |]
  [| "hats",  month(2024, 12),  4 |]
  [| "hats",  month(2024, 11), 11 |]

table Products = by Sales.Product
Products.Quantity = sum(Sales.Quantity)

show chart "" a1c3 a3cf8c with  
  haxis into Products
  plot into Products
    Products.Quantity { seriesType: bar }

This displays the tile below:

The constrained haxis supports number, date, week, month, text and enum types. By default, the values are sorted in ascending order, but this can be overridden with an order by statement in the haxis.

Taking the example from above, but ordering the products by ascending quantity:

table Sales = with 
  [| as Product, as Date, as Quantity |]
  [| "socks", month(2024, 12), 10 |]
  [| "socks", month(2024, 11),  3 |]
  [| "hats",  month(2024, 12),  4 |]
  [| "hats",  month(2024, 11), 11 |]

table Products = by Sales.Product
Products.Quantity = sum(Sales.Quantity)

show chart "" a1c3 a3cf8c with  
  haxis into Products
    order by Products.Quantity
  plot into Products
    Products.Quantity { seriesType: bar }

This displays the tile below:

A few notes:

• It is currently not possible to use desc when ordering an haxis.
• Since enum types are not supported, it is mandatory to provide an order by when defining a horizontal axis of an enum type.
• The maximum number of elements in an haxis is 5000. Attempting to provide more will cause an error to be reported at runtime.

laxis

The laxis, or left axis, is one of the two vertical axes available in a show chart. As expected, it appears on the left side of the chart.

Vertical axes are always free, and always of type number (support for date, week and month, as well as for constrained vertical axes, will be added in the future). As such, the only puropose of providing a laxis (or raxis) block is to attach StyleCode display information to it, such as the unit or the number format.

For example, the script below uses “items” as the unit for the horizontal axis, “€” for the left axis, and percentages for the right axis.

table T = extend.range(10)
table T[X] = by [T.N - 1]
T.Y1 = sin(T.X)
T.Y2 = cos(T.X) * T.Y1

show chart "" a1d4 with 
  haxis into T { unit: " items" }
  laxis { unit: "€" }
  raxis  { numbers: percent } 
  plot into T
    T.Y1 vaxis: "left"
    T.Y2 vaxis: "right"

This displays the axes as follows:

If both laxis and raxis are provided, you can specify for every series whether that series should be drawn against the left axis (vaxis: "left") or against the right axis (vaxis: "right"). It is recommended to keep the value of vaxis: a constant, but values computed at runtime can also be used, so long as they are "left" or "right".

raxis

The raxis, or right axis, is one of the two vertical axes available in a show chart. Everything that is documented about the left axis (in the laxis section above) is also true of the right axis, with two exceptions:

• The right axis is on the right, whereas the left axis is on the left.
• If both axes are specified, and a column does not have a vaxis: option, then by default vaxis: "left" is assumed.

Data blocks

scatter

TODO. The scatter block displays a cloud of points, using the provided $(X, Y)$ coordinates.

plotxy

TODO. A plotxy draws a curve through points given by their $(X,Y)$ coordinates. Similar to show plot.

plot

TODO. A plot is like plotxy, but always drawn left-to-right and two $(X, Y)$ coordinates may not share the same $X$ value. Series can be displayed as lines, areas, or bars. Similar to show linechart. Currently requires an haxis to be defined.