跳到主要内容

画布、标题与坐标轴

这些顶层字段描述画布本身与它的两根主轴。多面板模式下会被忽略 —— 那里每个面板各自带一份。

画布​

字段类型设置什么
widthnumber画布宽度(像素)。
heightnumber画布高度(像素)。

默认画布是 600 × 450,再加上由标题、刻度标签与图例算出来的边距 —— 这正是默认单图出来约 675 × 511 的原因。 两个都别写,图才会保持这个比例 —— 钉进一个又宽又扁的框里会被压扁。文档页里也不需要别的:"show":"svg" 的块按 SVG 自身的高度自动撑开,所以预览框同样不用钉。

标题​

title 可以直接给字符串,也可以给带副标题与字号的对象:

{ "text": "Fragment length", "subtext": "bimodal distribution", "size": 22, "subtext_size": 14 }
字段类型设置什么
textstring标题。
subtextstring标题下的副标题。
sizeinteger标题字号。
subtext_sizeinteger副标题字号。
wrapinteger标题按字符数折行。
subtext_wrapinteger副标题按字符数折行。

字体​

所有文字的字号集中在这里。字体族也可以由 theme 设置。

字段类型设置什么
familystring所有文字的字体族。
tick_familystring只给刻度标签用的字体族,标题、轴名、图例仍用 family。
title_sizeinteger标题字号(会被 title.size 覆盖)。
label_sizeinteger坐标轴标题字号。
tick_sizeinteger刻度标签字号。
body_sizeinteger正文(图例、标注)字号。

tick_family 是给序列上下文的类别标签、基因组坐标,或任何「等宽字体能让数字按列对齐」的轴用的 ("monospace"、"DejaVu Sans Mono"、"Consolas"…)。宽度预留会跟着字体走:等宽刻度按 kuva 的等宽 字宽表测量,所以小数轴不会像按无衬线测量时那样被裁掉。刻度标签会被包进一层 <g font-family>,不设这个 字段时输出完全不变。

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;

坐标轴​

x_axis 与 y_axis 的形状相同:

字段类型设置什么
namestring坐标轴标题。
categoriesstring[]类别轴的标签(柱状、箱线等)。给了就覆盖从数据自动收集的类别。
min / maxnumber固定的范围。
logboolean对数轴。
tick_formatstring | integer"auto" · "integer" · "sci" · "percent" · "degree",或一个整数表示定点小数位数。
tick_stepnumber主刻度按这个间隔取整。
wrapinteger坐标轴标题按字符数折行。
label_offset[number, number]把坐标轴标题平移 [dx, dy] 像素。
tick_rotatenumber刻度标签旋转多少度。仅 x 轴。
label_overlapstring"allow" · "thin" · "stagger"。仅 x 轴。
y 轴的旋钮更少

tick_rotate 与 label_overlap 写在 y_axis 下也能解析,但没有效果:它们作用在 x 轴上。上面其余字段 两根轴都适用。

文字折行​

很长的标题与轴标题可以按字符数折行,而不是逼着画布变宽。折行是可选的:不给宽度就什么都不折。

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 一次设好所有文字。逐元素的那几个字段在它之后套用,所以会覆盖它:title.wrap、 title.subtext_wrap、x_axis.wrap、y_axis.wrap、legend.wrap。

元素折行之后
标题 / 副标题变成居中的多行,上边距随之变大。
x 轴标题居中的多行,下边距变大。
y 轴标题若干行旋转的文字并排叠放,左边距变大。
图例标签与标题续行显示,色块留在第一行;图例框变高,宽度有上限,所以右边距不会失控。

折行在空白处断开;单个词比上限还长时会被硬断。

色条​

带色条的图 —— 热力图、六边形分箱图、 二维直方图、等高线图 —— 再多一个图级字段:

字段类型设置什么
colorbar_tick_formatstring | integer色条标签的格式:"auto"(默认)· "sci" · "integer" · "percent" · "degree",或一个整数表示小数位。

示例​

坐标轴标题、副标题与刻度格式,画一张直方图:

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');

固定范围 + 对数 y 轴,用的还是散点页那份数据:

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');

另见​