Skip to main content

Reference & annotations

annotations draws three kinds of furniture over the data: straight reference lines, shaded bands, and text (optionally with an arrow). Each is a list and all three are optional.

Reference lines​

FieldTypeWhat it sets
orientationstring"horizontal" (default) or "vertical".
valuenumberWhere the line sits — a y value for a horizontal line, an x value for a vertical one.
colorstringLine colour.
stroke_widthnumberLine thickness.
dasharraystringAn SVG stroke-dasharray (e.g. "4 2") for a dashed line.
labelstringA text label on the line.

Shaded regions​

FieldTypeWhat it sets
orientationstring"horizontal" (default) or "vertical".
min / maxnumberThe two edges of the band.
colorstringFill colour.
opacitynumberFill opacity, 0–1.

Text and arrows​

FieldTypeWhat it sets
textstringThe label.
x / ynumberWhere the text is placed, in data coordinates.
target_x / target_ynumberIf both are given, an arrow is drawn from the text to this point.
colorstringText colour.
font_sizeintegerText size.
arrow_paddingnumberGap between the text and the start of the arrow.

Example​

A baseline, a shaded band around it, and a label, over one condition's time series:

SELECT kuva_render(to_json({
'x_axis': {'name': 'time'},
'y_axis': {'name': 'value'},
'annotations': {
'reference_lines': [
{'orientation': 'horizontal', 'value': 1.5, 'color': 'crimson', 'dasharray': '4 2', 'label': 'baseline'}
],
'shaded_regions': [
{'orientation': 'horizontal', 'min': 1.2, 'max': 1.6, 'opacity': 0.15, 'color': 'crimson'}
],
'texts': [
{'text': 'steady state', 'x': 55, 'y': 2.6}
]
},
'series': [{'type': 'line', 'data': pts, 'color': 'steelblue'}]
})) AS chart
FROM (
SELECT array_agg({'x': time, 'y': value} ORDER BY time) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/measurements.tsv')
WHERE "group" = 'Condition_A'
);

Note​

Annotations are drawn on top of the series, so a filled area (a line with fill, a band) can sit underneath them.