Skip to main content

Canvas, title & axes

These top-level fields describe the drawing surface and its two primary axes. They are ignored in multi-panel mode, where each panel carries its own copy.

Canvas​

FieldTypeWhat it sets
widthnumberCanvas width in pixels.
heightnumberCanvas height in pixels.

The default canvas is 600 × 450, plus margins computed from the title, tick labels and legend — which is why a default chart comes out at about 675 × 511. Leave both unset so the chart keeps that proportion — a chart pinned into a wide, short box is squashed. Nothing else is needed in a docs page either: a "show":"svg" block grows to the SVG's own height, so the preview box is never pinned.

Title​

title is either a plain string, or an object with a subtitle and sizes:

{ "text": "Fragment length", "subtext": "bimodal distribution", "size": 22, "subtext_size": 14 }
FieldTypeWhat it sets
textstringThe title.
subtextstringA subtitle under it.
sizeintegerTitle font size.
subtext_sizeintegerSubtitle font size.
wrapintegerWrap the title after this many characters.
subtext_wrapintegerWrap the subtitle after this many characters.

Font​

Sizes for every piece of text, in one place. A theme can set the family too.

FieldTypeWhat it sets
familystringFont family for all text.
tick_familystringFont family for tick labels only, leaving titles, axis labels and legends in family.
title_sizeintegerTitle size (overridden by title.size).
label_sizeintegerAxis-label size.
tick_sizeintegerTick-label size.
body_sizeintegerBody text (legends, annotations).

tick_family is for sequence-context category labels, genomic coordinates, or any axis where a monospace face keeps the digits in a column ("monospace", "DejaVu Sans Mono", "Consolas", …). Width reservation follows the face: a monospace tick label is measured against kuva's monospace metrics, so a decimal axis is not clipped the way sans-measured margins would clip it. Tick labels are wrapped in a <g font-family> group, so output without the option is unchanged.

SELECT kuva_render(to_json({
'title': 'Monospace ticks',
'font': {'tick_family': 'monospace'},
'x_axis': {'name': 'position', 'tick_format': 'integer'},
'y_axis': {'name': 'depth'},
'series': [{
'type': 'line',
'color': 'steelblue',
'data': [{'x': 1000000, 'y': 12}, {'x': 1000250, 'y': 48},
{'x': 1000500, 'y': 31}, {'x': 1000750, 'y': 9}]
}]
})) AS chart;

Axes​

x_axis and y_axis share this shape:

FieldTypeWhat it sets
namestringThe axis label.
categoriesstring[]Category labels for a categorical axis (bar, box, …). Overrides the labels collected from the data.
min / maxnumberFixed bounds.
logbooleanA logarithmic axis.
tick_formatstring | integer"auto" · "integer" · "sci" · "percent" · "degree", or an integer for that many decimal places.
tick_stepnumberRound ticks to this interval.
wrapintegerWrap the axis label after this many characters.
label_offset[number, number]Shift the axis label by [dx, dy] pixels.
tick_rotatenumberRotate tick labels by this many degrees. x axis only.
label_overlapstring"allow" · "thin" · "stagger". x axis only.
The y axis has fewer knobs

tick_rotate and label_overlap are accepted under y_axis but have no effect: they write to the x axis. Everything else above works on both.

Text wrapping​

Long titles and axis labels can be wrapped at a character limit instead of forcing the canvas to grow. Wrapping is opt-in: nothing wraps until you set a width.

SELECT kuva_render(to_json({
'title': 'A title that would otherwise make the top margin enormous',
'x_axis': {'name': 'a long x-axis label that would push the bottom margin out'},
'grid': {'wrap': 28},
'series': [{'type': 'histogram', 'values': list(value), 'bins': 20}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/histogram.tsv');

grid.wrap sets every text element at once. The per-element fields are applied after it, so they override it: title.wrap, title.subtext_wrap, x_axis.wrap, y_axis.wrap, legend.wrap.

ElementWhat wrapping does
Title / subtitleCentred lines; the top margin grows to fit.
x-axis labelCentred lines; the bottom margin grows.
y-axis labelSeveral rotated lines stacked sideways; the left margin grows.
Legend labels and titlesContinuation lines with the swatch kept on the first; the legend box gets taller and its width is capped, so the right margin does not run away.

Wrapping breaks at whitespace, and a single word longer than the limit is hard-broken.

Colour bar​

Charts that draw a colour bar — heatmap, hexbin, 2D histogram and contour — take one more figure-level field:

FieldTypeWhat it sets
colorbar_tick_formatstring | integerColour-bar label format: "auto" (default) · "sci" · "integer" · "percent" · "degree", or a number of decimal places.

Examples​

Axis labels, a subtitle and a tick format, over one histogram:

SELECT kuva_render(to_json({
'title': {'text': 'Fragment length', 'subtext': 'two overlapping peaks'},
'x_axis': {'name': 'length (bp)', 'tick_format': 'integer'},
'y_axis': {'name': 'reads'},
'font': {'label_size': 15, 'tick_size': 12},
'series': [{'type': 'histogram', 'values': list(value), 'bins': 40}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/histogram.tsv');

A fixed range and a logarithmic y axis, from the same data the scatter page uses:

SELECT kuva_render(to_json({
'x_axis': {'name': 'x', 'min': 0, 'max': 10, 'tick_step': 2},
'y_axis': {'name': 'y', 'log': true},
'series': [{'type': 'scatter', 'data': array_agg({'x': x, 'y': y})}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/scatter.tsv');

See also​