Skip to main content

Grid, ticks & canvas switches

The grid object controls everything that is not data: grid lines, the axis frame, ticks, and a set of switches that change how the whole canvas is drawn.

Grid, axis lines and ticks​

FieldTypeWhat it sets
show_gridbooleanDraw grid lines.
axis_linestring"open" (default: just the bottom and left edges) or "box" (a full frame).
ticksintegerHow many ticks per axis to aim for.
tick_alignstring"outside" (default) · "inside" · "center".
tick_posstring"primary" (default) · "both" (mirror the ticks onto all four edges).
grid_line_widthnumberGrid line stroke width.
axis_line_widthnumberAxis line stroke width.
tick_widthnumberTick mark stroke width.
tick_lengthnumberTick mark length in pixels.
minor_ticksintegerSub-divisions between major ticks.
show_minor_gridbooleanDraw grid lines at the minor ticks too.

Whole-canvas switches​

FieldTypeWhat it sets
clamp_axisbooleanSnap the axis ranges to the data, with no outward rounding.
clamp_y_axisbooleanThe same, for the y axis alone.
equal_aspectbooleanOne data unit is the same number of pixels on both axes (circles stay round).
scalenumberScale every piece of text and tick, without changing the canvas size.
label_backgroundbooleanDraw a background behind value labels (bars, pie slices) so they stay legible over the fill.
bw_modebooleanGrayscale, colour-blind-safe mode: the palette becomes greys and line styles / markers cycle to keep series apart. See Black & white mode.
interactivebooleanInject hover/click JavaScript into the SVG. See SVG interactivity.
wrapintegerWrap every text element (title, axis labels, legend) at this many characters; the per-element fields override it. See Text wrapping.
bw_mode and interactive belong to the canvas, not a series

Put them under grid, not on a series. bw_mode is the accessibility twin of palette; interactive makes the SVG respond to a pointer, which needs a host that runs JavaScript (a browser, not a raster export).

Examples​

A boxed frame with minor ticks and mirrored ticks, on a simple bar chart:

SELECT kuva_render(to_json({
'x_axis': {'name': 'GO term', 'tick_rotate': 60},
'y_axis': {'name': 'hits'},
'grid': {'axis_line': 'box', 'minor_ticks': 4, 'show_minor_grid': true, 'tick_pos': 'both'},
'series': [{
'type': 'bar',
'categories': list(category ORDER BY count DESC),
'values': list(count ORDER BY count DESC)
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/bar.tsv');

Grayscale mode: the same multi-series scatter, drawn for print and for colour-blind readers:

SELECT kuva_render(to_json({
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'grid': {'bw_mode': true},
'series': list({'type': 'scatter', 'data': pts, 'legend': g} ORDER BY g)
})) AS chart
FROM (
SELECT "group" AS g, array_agg({'x': x, 'y': y} ORDER BY x) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/scatter.tsv')
GROUP BY "group"
);

See also​