Skip to main content

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).

FieldTypeWhat it sets
secondary_seriesseries[]Series drawn against the secondary axis. Same shape as series.
y2_axisobjectThe right-hand y axis.
x2_axisobjectThe top x axis.

y2_axis and x2_axis accept a subset of the axis fields:

FieldTypeWhat it sets
namestringThe axis label.
min / maxnumberFixed bounds.
logbooleanA logarithmic axis.
tick_formatstring | integerAs on a primary axis.
wrapintegerWrap the label after this many characters.
label_offset[number, number]Shift the label by [dx, dy] pixels.
Two rules for the secondary x axis

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.