Secondary axes (twin-Y)
A figure normally has one set of axes. To plot two quantities with very different scales against each
other — price and volume, say — put the second quantity in secondary_series and describe its axis
with y2_axis (right) or x2_axis (top).
| Field | Type | What it sets |
|---|---|---|
secondary_series | series[] | Series drawn against the secondary axis. Same shape as series. |
y2_axis | object | The right-hand y axis. |
x2_axis | object | The top x axis. |
y2_axis and x2_axis accept a subset of the axis fields:
| Field | Type | What it sets |
|---|---|---|
name | string | The axis label. |
min / max | number | Fixed bounds. |
log | boolean | A logarithmic axis. |
tick_format | string | integer | As on a primary axis. |
wrap | integer | Wrap the label after this many characters. |
label_offset | [number, number] | Shift the label by [dx, dy] pixels. |
The secondary x axis takes min and max together — giving only one is an error. And a
secondary axis is only drawn when there is something in secondary_series; y2_axis on its own is
accepted but produces a plain single-axis chart.
The right-hand axis range is inferred from the secondary_series data, so a y2_axis carrying
only a name is enough to draw the axis. min / max are optional overrides: give both for a fixed
range, or just one to pin that end while the other keeps following the data. The example below leaves
them out.
Example
Price on the left axis and volume on the right, from the same rows:
SELECT kuva_render(to_json({
'title': 'price vs volume',
'y_axis': {'name': 'close', 'min': 100, 'max': 200},
'y2_axis': {'name': 'volume', 'tick_format': 'sci'},
'legend': {'position': 'outside_right_top'},
'series': [{'type': 'line', 'data': price, 'legend': 'close', 'color': '#4c72b0'}],
'secondary_series': [{'type': 'line', 'data': vol, 'legend': 'volume', 'color': '#c44e52'}]
})) AS chart
FROM (
SELECT
array_agg({'x': epoch(CAST(date AS DATE)), 'y': close} ORDER BY date) AS price,
array_agg({'x': epoch(CAST(date AS DATE)), 'y': volume} ORDER BY date) AS vol
FROM read_csv_auto('{{DFK_BASE_URL}}data/candlestick.tsv')
);
Note
In multi-panel mode a secondary axis belongs to a single panel, so a twin-Y chart is one panel of the grid.