跳到主要内容

series 与通用字段

每张图都是一个 JSON 对象,它的 series 是一个列表。列表里每一项是一个 series,用 type 标明类型:

{
"series": [
{ "type": "scatter", "data": [{"x": 1, "y": 2}, {"x": 2, "y": 3}] },
{ "type": "line", "data": [{"x": 1, "y": 2}, {"x": 2, "y": 3}], "legend": "trend" }
]
}

用列表(而不是单个对象)是为了让一张图能把几种图型叠加到同一套坐标轴上;这也是规格用 JSON 而不是 DuckDB STRUCT 的原因:scatter 与 bar 的字段不同,STRUCT 的 LIST 装不下 [StructA, StructB]。

图型一览​

kuva 的 64 种图型全部已实现。侧边栏按 kuva 官方文档 的分类方式分组:

分组type 取值
分布histogram · histogram2d · density · ridgeline · ecdf · qq · box · violin · strip · raincloud · hexbin · heatmap
关系与相关scatter · line · series · band · jointplot · contour · parallel · polar · ternary · quiver
分类与对比bar · pie · waffle · funnel · pareto · pyramid · lollipop · slope · dot_plot · dice_plot · mosaic · venn · upset · radar · rose
时间序列stacked_area · streamgraph · candlestick · waterfall · horizon · calendar · gantt · bump
统计与模型评估roc · pr · survival · forest · volcano · manhattan
层级与网络treemap · sunburst · network · sankey · chord · phylo · clustermap
3Dscatter3d · surface3d
组合与工具brick · synteny · text · legend_plot

少数图型还接受一个更短的别名:dotplot、diceplot、histogram_2d、scatter_3d、surface_3d、 up_set、phylo_tree、interval(对应 band)、joint(对应 jointplot)、legend(对应 legend_plot)。

每个 series 都能用的字段​

下面这些字段(几乎)每种图型都接受;各图型页面不再重复它们:

字段类型设置什么
colorstringseries 的颜色,CSS 颜色("steelblue"、"#4c72b0"、"rgb(…)")。默认黑色;除非整张图里没有任何 series 指定颜色 —— 那时按调色板轮换。
legendstring这个 series 的图例文字。只有设了它,series 才会出现在图例里。
tooltipsboolean往 SVG 里注入悬停提示。line 未实现。
tooltip_labelsstring[]每个数据点一条提示文字,按数据顺序。
datasetstring这个 series 改从具名数据集取数,而不是内联数据。需要 kuva_render 的第二个参数;见数据集。
encodeobject角色 → 字段名:数据集的哪一列喂给哪个数据字段。省略时按名自动映射。

dataset / encode 是 series 从第二个参数取数的方式 —— 它们取代该 series 的内联数据字段,不能与内联 数据同时给。两者都不给的 series 照旧从内联数据画。

用色图编码的图型

用连续色图编码数值的图型 —— heatmap、histogram2d、hexbin、clustermap、 contour、dice_plot、calendar 等 —— 没有 color 字段,改用 color_map。以各图型页面的字段表为准。

点​

scatter、line、series 与 quiver 接受点列表。一个点是对象(可带逐点误差棒):

{ "x": 1.0, "y": 2.0, "x_err": 0.2, "y_err": {"neg": 0.3, "pos": 0.8} }

x_err / y_err 要么是一个数(对称误差,即 ± 该值),要么是一个 {"neg": …, "pos": …} 对象 (不对称误差,给出两条臂的长度)。

置信带​

阴影区域是两列与数据 x 位置对齐的上下界:

{ "lower": [0.8, 1.7, 2.4], "upper": [1.3, 2.4, 3.1] }

在 scatter 或 line series 上以 band 传入。两列长度都必须与数据一致。

趋势线​

在 scatter series 上设 trend。短写法拟合一条最小二乘直线("linear")或一条 LOESS 平滑曲线 ("loess");对象写法还能设置样式并印出拟合统计量:

{ "type": "linear", "color": "crimson", "width": 2, "equation": true, "correlation": true }
字段类型设置什么
type"linear" | "loess"拟合方式:最小二乘直线,或局部加权回归平滑。
spannumberLOESS 带宽(每次局部拟合用到的点比例,0.05–1,默认 0.5)。
colorstring线颜色(默认 "black")。
widthnumber线宽。
equationboolean在图里印出回归方程 y = mx + b(仅线性)。
correlationboolean在图里印出 Pearson R²(仅线性)。

点很密时想更干净,就别开这两个,改成把数字放进统计框。

分组值​

分布类图型 —— violin、ridgeline、raincloud、strip、ecdf 与 qq —— 的数据是一列 groups, 而不是一列平铺的数值。每组是一个标签加一列观测值,还可以给每组一个颜色:

{ "label": "Control", "values": [1.2, 0.9, 1.5], "color": "steelblue" }

每组至少要有一个值。

示例​

把折线与它的点从同一批行里叠出来,两者就不可能对不上:

SELECT kuva_render(to_json({
'x_axis': {'name': 'time'},
'y_axis': {'name': 'value'},
'series': [
{'type': 'line', 'data': pts, 'legend': 'trend'},
{'type': 'scatter', 'data': pts, 'legend': 'points'}
]
})) 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'
);

误差棒来自逐点对象;趋势线就拟合这批点:

SELECT kuva_render(to_json({
'x_axis': {'name': 'time'},
'y_axis': {'name': 'value'},
'series': [{
'type': 'scatter',
'data': pts,
'color': 'steelblue',
'trend': {'type': 'linear', 'equation': true, 'correlation': true}
}]
})) AS chart
FROM (
SELECT array_agg({'x': time, 'y': value, 'y_err': 1.5} ORDER BY time) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/measurements.tsv')
WHERE "group" = 'Condition_B'
);

说明​

  • 只有 legend 才会让 series 进图例。 不给它值,series 就画成不带标签的。
  • tooltips 需要有能跑 JavaScript 的宿主。 提示是内联的 SVG + JS,在浏览器预览和任何 HTML 页面里 能用,导出成静态图就不行。
  • 空的 series 列表是错误,某个 series 的必填数据字段为空也是。见函数的错误一节。