30:T680,md`# How Vega Works _A step-by-step guide to how Vega JSON specifications become interactive views. This notebook assumes basic familiarity with Vega, at the level of the ["Let's Make a Bar Chart" tutorial](https://vega.github.io/vega/tutorials/bar-chart/)._ _本文将一步步说明 Vega JSON specifications 如何变成 interactive views。文本假设你基本熟悉 Vega, 至少在 ["Let's Make a Bar Chart" tutorial](https://vega.github.io/vega/tutorials/bar-chart/) 水平。_ The [Vega visualization grammar](https://vega.github.io/vega) is a [declarative language](https://en.wikipedia.org/wiki/Declarative_programming) for describing visualizations. The Vega runtime parses specifications in a JSON format to produce interactive web-based graphics. One unique aspect of Vega is its support for declarative interaction using a reactive model: as input events arrive and data or variables change, Vega efficiently updates the visualization. [Vega 可视化语法](https://vega.github.io/vega) 是 [声明式编程](https://en.wikipedia.org/wiki/Declarative_programming) 描述可视化。Vega 运行时解析 specifications 从 JSON 格式到基于 web 的交互式图形。Vega的一个独特方面是它支持使用反应模型的声明式交互：当定义事件触发时和数据或变量更改时，Vega 可以有效地更新视图. Let's start with a simple bar chart that includes a basic form of interaction: a slider that adjusts the amount of padding added by the x-axis scale encoding. 让我们从一个简单的条形图开始，它包含一种基本的交互形式:一个滑动器，用于调整由x轴缩放编码添加的填充量。`31:T4bf,inputSpec = { return { "width": 200, "height": 100, "data": [ { "name": "table", "values": [ {"key": "A", "value": 4}, {"key": "B", "value": 10}, {"key": "C", "value": 7} ] } ], "scales": [ { "name": "xscale", "type": "band", "domain": {"data": "table", "field": "key"}, "padding": {"signal": "scalePadding"}, "range": "width" }, { "name": "yscale", "type": "linear", "domain": {"data": "table", "field": "value"}, "range": "height" } ], "marks": [ { "type": "rect", "from": {"data": "table"}, "encode": { "update": { "x": {"scale": "xscale", "field": "key"}, "y": {"scale": "yscale", "field": "value"}, "y2": {"scale": "yscale", "value": 0}, "width": {"scale": "xscale", "band": 1}, "fill": {"value": "steelblue"} } } } ], "signals": [ { "name": "scalePadding", "value": 0.1, "bind": {"input": "range", "min": 0, "max": 0.99, "step": 0.01} } ] }; }32:T7e0,md`

## Visualizations as Reactive Dataflows ## 可视化作为反应性数据流 For a given input specification, Vega generates a _dataflow graph_ that performs the computations needed to map data to visual elements, add axes or legends, and respond to interactive updates. 对于给定的输入规范，Vega 生成一个 _dataflow graph_，它执行将数据映射到可视化元素、添加轴或图例以及响应交互式更新所需的计算。 A dataflow graph contains a set of _nodes_ (also called _operators_) that perform operations such as calculating an aggregate or creating a scale mapping. Nodes can process values from other nodes and/or streams of data objects (such as input data sources, derived data sources, or scenegraph items representing visual elements). _dataflow graph_ 包含一组 _nodes_（也称为_operators_)，它们执行诸如计算聚合或创建比例映射之类的操作。节点可以处理来自其他节点和或数据对象流的值(例如输入数据源、派生数据源或表示可视化元素的场景图项)。 Graph _edges_ represent dependencies between nodes. Each node may have an associated value. For example, a node corresponding to a Vega signal contains the signal value, whereas a node corresponding to a scale contains a [d3-scale](https://github.com/d3/d3-scale) instance. There are two types of edges: _parameter_ edges indicate that one node directly depends on the value of another node, while _pulse_ edges indicate that data objects "flow" from one node to another. 图 _edges_ 表示节点之间的依赖关系。每个节点都可能有一个关联的值。例如，对应于一个 Vega \`signal\` 的节点包含信号值，而对应于一个 \`scale\` 节点包含一个 [d3-scale](https://github.com/d3/d3-scale) 实例。边缘有两种类型：_parameter_ edges（参数边）表示一个节点直接依赖于另一个节点的值，而 _pulse_ edges（脉搏变）表示数据对象从一个节点“流”到另一个节点。 `33:T584,md`The diagram below visualizes the dataflow graph for our bar chart. Gray nodes indicate signals, red nodes indicate data sources, green nodes indicate scales, and blue nodes process visualized marks. White nodes are internal data operations that calculate needed statistics or propagate updates. Black edges indicate **pulse** dependencies, gray edges are parameter dependencies. 图例 signals
data
scales
marks
data operations：计算所需的统计信息或传播更新 **pulse edge**
parameter edge `34:Tc7a,md`Trace the dataflow graph to see how calculations are carried out. For example, given the input dataset \`table\`, an \`extent\` operator calculates the minimum and maximum values of the \`value\` field to determine the \`yscale\` \`domain\` parameter. Similarly, a chain consisting of \`aggregate\`, \`collect\`, and \`values\` operators calculates unique \`key\` field values to determine the \`xscale\` \`domain\`. The \`xscale\` operator is also parameterized by the \`scalePadding\` signal. The \`table\` dataset is encoded as rectangle marks by a sequence of operators: - A \`datajoin\` operator maps input data objects to scenegraph mark items. - A \`collect\` operator gathers the output of the data join. - A \`mark\` operator binds the generated mark items to the scenegraph. - An \`encode\` operator computes visual encodings to determine mark item properties, and is parameterized by \`xscale\` and \`yscale\`. - A \`bound\` operator computes bounding boxes for each mark item. The bounds are used for both layout and input event hit testing. - A \`render\` operator queues scenegraph updates for (re-)rendering. - Finally, a \`sieve\` operator propagates mark updates (but not the mark items themselves) to other parts of the dataflow graph, causing downstream operators to be re-evaluated if and when any mark items change. In this case, the top-level \`viewlayout\` is re-run when mark items change. The other set of visual encoding operators — starting from the \`root\` node — calculate properties and layout for the visualization's top-level group mark. `35:T468,md` The \`operators\` property is a list of dataflow nodes. Dependencies are indicated via references in a node entry's \`params\` object: \`operators[10].params.padding: {$ref: 6}\` indicates that the \`yscale\` (node \`10\`) depends on the value of the \`scalePadding\` signal (node \`6\`). The \`bindings\` property describes input bindings, here between the \`scalePadding\` signal and a slider. Other properties of the output — unused in this example — include \`streams\` (event stream definitions such as mouse move, click, _etc._), \`updates\` (expressions for updating nodes in response to events), and the overall view \`background\` color. The parser compiles encoding logic and expressions to JavaScript code. For example, the \`update\` encoding block in the input specification maps to this JavaScript code in \`operators[21].params.encoders.$encode.update\`: \`\`\`js ${parsedSpec.operators[21].params.encoders.$encode.update.$expr .replace(/if$/g, 'if (') .replace(/$\$/g, ') $') .replace(/([\=\>\-])/g, ' $1 ') .replace(/\,/g, ', ') .replace(/\;/g, ';\n ') } \`\`\` ` 36:T7ee,md`

## View & Dataflow Runtime Once an input specification has been parsed to a dataflow graph description, we can instantiate an interactive [\`View\` component](https://github.com/vega/vega/tree/master/packages/vega-view). The \`View\` takes the parsed specification as input and uses the [vega-runtime](https://github.com/vega/vega/tree/master/packages/vega-runtime) library to turn the dataflow graph description into a live [\`Dataflow\`](https://github.com/vega/vega/tree/master/packages/vega-dataflow) instance. * specification 通过 \`vega-parser\` 解析为 dataflow graph * dataflow graph 通过 \`vega-runtime\` 实例化为交互式 View Component \`Dataflow\` 实例 A Vega \`Dataflow\` evaluates nodes in topological order, ensuring that all dependencies are processed before an operator is evaluated. Internally, [\`Pulse\`](https://github.com/vega/vega/blob/master/packages/vega-dataflow/src/Pulse.js) instances are used to pass data from one node to another, tracking which data objects have been inserted, removed, or modified. Vega \`Dataflow\` 按拓扑顺序计算节点，确保在计算运算符之前处理所有依赖项。在内部，\`Pulse\` 实例用于将数据从一个节点传递到另一个节点，跟踪插入、删除或修改了哪些数据对象。 A major advantage to modeling computation as a dataflow graph is the ability to perform efficient reactive updates. When parameters change or the input data is modified, the dataflow can re-evaluate only those nodes affected by the update. 将计算建模为数据流图（dataflow graph）的一个主要优点是能够执行有效的反应性更新。当参数改变或输入数据被修改时，数据流只需要重新评估那些受更新影响的节点。 Adjust the \`stage\` drop-down below to see which nodes are re-evaluated when the \`scalePadding\` signal is updated by dragging the bound slider. 以下来展示 scalePadding 如何更新 `37:T659,md`

## Next Steps Knowing how Vega works can be helpful when debugging your own visualizations. The [Vega View API](https://vega.github.io/vega/docs/api/view/) provides access to data sources, scales, and the scenegraph. For example, \`view.scenegraph().root\` accesses the scenegraph tree. The \`view._runtime\` property provides access to the _runtime context_ of dataflow operators. The object \`view._runtime.nodes\` is a map of all dataflow operators in the top-level scope. Some more advanced aspects are not covered in this notebook. In particular, Vega supports _nested scopes_: group marks containing signal, data, and scale definitions within their own namespace. Vega implements this functionality via _subflows_, which can be thought of as recursively-defined dataflow graphs. Moreover, via _faceting_, nested groups can be defined in a data-driven way, requiring Vega to dynamically add and remove subflows in response to streaming data or user input! Nested scopes can be inspected using the \`view._runtime.subcontext\` array. To learn more about the main ideas behind Vega, including declarative specification of interaction techniques, see Arvind Satyanarayan's 2016 OpenVisConf talk ["Reactive Building Blocks: Interactive Visualizations with Vega"](https://www.youtube.com/watch?v=Y8Fp9z-9DWc), or our InfoVis 2015 paper ["Reactive Vega: A Streaming Dataflow Architecture for Declarative Interactive Visualization"](http://idl.cs.washington.edu/papers/reactive-vega-architecture/). Though those resources describe Vega 2.0 and this notebook describes Vega 3.0+, the central concepts are the same! `38:[] 2e:{"title":"How Vega Works","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":182,"value":"viewof view = {\n const div = document.createElement('div');\n div.value = new vega.View(parsedSpec)\n .initialize(div)\n .run();\n return div;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":492,"value":"md`Expand the \\`inputSpec\\` cell below to see the **Vega JSON specification** for the chart.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":105,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":254,"value":"md`The specification consists of an input data set, two scale transforms (\\`xscale\\` and \\`yscale\\`), and a \\`rect\\` mark definition that uses the scales to visually encode the data as rectangles.\nIn addition, a \\`scalePadding\\` signal is defined to parameterize the padding of \\`xscale\\`, along with a binding to a slider input widget.\n\nspecification 定义了\n* 一个输入数据集（_data_）\n* 两个 _scale_ \\`xscale\\` 和 \\`yscale\\`\n* 一个 \\`rect\\` _mark_：使用度量将数据编码为矩形 \n* 一个 \\`scalePadding\\` _single_：用于参数化 xscale 的填充，以及与滑块输入小部件的绑定\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":212,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":608,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":192,"value":"dot`${view2dot(viewHide)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":616,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":624,"value":"md`

\n## Parsing a Vega Specification\n\nThe first step in going from an input specification to a live dataflow is _parsing_. The [vega-parser](https://github.com/vega/vega/tree/master/packages/vega-parser) module takes a declarative JSON specification as input and produces a _dataflow graph description_ as output. This output is only a description: think of it as a file format for a dataflow graph.\n\nExpand the \\`parsedSpec\\` object below to inspect the parser output for our \\`inputSpec\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":229,"value":"parsedSpec = vega.parse(inputSpec)","pinned":false,"hidden":false,"mode":"ojs"},{"id":235,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":256,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":328,"value":"viewof stage = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":316,"value":"dot`${view2dot(viewHide, +stage)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":338,"value":"md`

\n## Scenegraph & Rendering\n## 场景图 & 渲染\n\nThe Vega \\`Dataflow\\` constructs and maintains a [scenegraph](https://en.wikipedia.org/wiki/Scene_graph): a tree data structure that models all the visual elements, including the position, color, shape, and size of visual marks. The [vega-scenegraph](https://github.com/vega/vega/tree/master/packages/vega-scenegraph) module traverses the scenegraph to perform _rendering_, drawing the view using web standards such as [Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) and [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG).\n\nVega \\`Dataflow\\` 构造和包含 scenegraph：一种树形数据结构，为所有视觉元素建模，包括视觉标记的位置、颜色、形状和大小。\nvega-scenegraph 模块遍历 scenegraph 使用 canvas 执行渲染（render）。\n\nExpand the \\`scene\\` object below to inspect the scenegraph for our bar chart.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":345,"value":"scene = JSON.parse(view.scenegraph().toJSON())","pinned":false,"hidden":false,"mode":"ojs"},{"id":508,"value":"dot`${scene2dot(viewHide)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":342,"value":"md`The levels of the tree alternate between enclosing _marks_ and constituent mark _items_. The first two levels are the \\`root\\` group mark and its single group item, which contains the visualization. Expanding down to \\`scene.items[0].items[0]\\`, we find a \\`rect\\` mark containing three items: one for each bar in the bar chart.\n\n树的层在封闭标记 _marks_ 和组成标记项 _items_ 之间交替。前两个级别是 root 标记及其包含可视化的单个组项。...\n\nThe \\`render\\`\ndataflow operator informs the scenegraph of items that have been modified. In response, the renderers also perform efficient incremental updates, either by redrawing only the affected pixels in a Canvas (damage/redraw) or modifying only the relevant SVG elements.\n\n\\`render\\` dataflow operator 通知 scenegraph item 修改了。作为响应，呈现器还执行有效的增量更新，要么在画布中重绘受影响的像素，要么仅修改相关的SVG元素。\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":240,"value":"md`

\n## Adding An Axis\n\nThe discussion above focuses on a simple example in which the graphical output is only three rectangles. Let's consider a more realistic chart by adding a y-axis to our original input specification:\n\n\\`\\`\\`json\n${JSON.stringify(axisDef, 0, 2)}\n\\`\\`\\`\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":246,"value":"viewof view2 = {\n const div = document.createElement('div');\n div.value = new vega.View(vega.parse(vega.extend({}, inputSpec, +axisSelector ? axisDef : null)))\n .initialize(div)\n .run();\n return div;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":129,"value":"viewof axisSelector = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":416,"value":"md`Adjust the axis selector drop-down above to switch between our original bar chart and a new one with a y-axis. Note below how much more complex the dataflow graph is when the axis is included! [Creating appropriate axes and legends is a critical, yet surprisingly involved, part of visualization design.](https://beta.observablehq.com/@vega/a-guide-to-guides-axes-legends-in-vega)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":418,"value":"dot`${view2dot(view2)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":434,"value":"md`Internally, the Vega parser processes _axis_ definitions to generate an axis group, an\n\\`axisticks\\` data source\n(parameterized by \\`yscale\\`),\nand visual encoding operators for ticks, labels, and gridlines. Vega uses a similar approach to generate legends.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":420,"value":"scene2 = JSON.parse(view2.scenegraph().toJSON())","pinned":false,"hidden":false,"mode":"ojs"},{"id":511,"value":"dot`${scene2dot(view2)}`","pinned":false,"hidden":false,"mode":"ojs"},{"id":446,"value":"md`When the y-axis is included, the \\`scene2\\` scenegraph object includes a group mark containing the axis items under \\`scene2.items[0].items[0]\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":480,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":404,"value":"md`

\n## Imports & Extras`","pinned":false,"hidden":false,"mode":"ojs"},{"id":401,"value":"axisDef = {\n return {\n \"axes\": [\n {\n \"orient\": \"left\",\n \"scale\": \"yscale\",\n \"grid\": true,\n \"tickCount\": 5\n }\n ]\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":320,"value":"// headless view to use so that other cells don't update in\n// response to signal updates on the initial view cell\nviewHide = {\n const view = new vega.View(parsedSpec).initialize();\n view.runAsync().then(function(view) {\n view.signal('scalePadding', 0.5).run();\n });\n return view;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":7,"value":"vega = require('https://cdn.jsdelivr.net/npm/vega@5/build/vega.js')","pinned":false,"hidden":false,"mode":"ojs"},{"id":32,"value":"dot = require(\"@observablehq/graphviz@0.0.2/dist/graphviz.min.js\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":174,"value":"import {scene2dot, view2dot} from '@vega/vega2dot'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W38","stdlib":"1","titling":"auto"}