vegascope 1.0.14

示例

假设我们有一个生成Vega图形的进程，例如 PdVega（示例需要pip软件包 pdvega 和 vega_datasets）

>>> from vega_datasets import data
>>> import pdvega
>>> stocks = data.stocks(pivoted=True)
>>> stocks.vgplot.line().spec

{'selection': {'grid': {'bind': 'scales', 'type': 'interval'}}, 'encoding': {'y': {'fi
eld': 'value', 'type': 'quantitative'}, 'x': {'field': 'date', 'type': 'temporal'}, 'c
olor': {'field': 'variable', 'type': 'nominal'}}, 'height': 300, 'width': 450, '$schem
a': 'https://vega.github.io/schema/vega-lite/v2.json', 'mark': 'line', 'data': {'value
s': [{'date': '2000-01-01', 'variable': 'AAPL', 'value': 25.94}, {'date': '2000-01-02'
...

这个 stocks.vgplot.line().spec 是一个表示股票价格时间序列的JSON对象。它太复杂，无法手动阅读。

导入vegascope并创建一个LocalCanvas。它将在您的网页浏览器中打开一个标签页，用于绘制Vega图形。（提示：在其他桌面或首先在当前桌面创建浏览器窗口中寻找它！）

每次将画布作为函数在Vega图形中调用时，网页将更新为最新的绘图。无需刷新浏览器。

>>> import vegascope
>>> canvas = vegascope.LocalCanvas()
Created new window in existing browser session.
127.0.0.1 connected

>>> canvas.how()
Point web browser at: http://localhost:40142

>>> canvas(stocks.vgplot.line().spec)

PdVega仅用作示例；图形可以来自任何地方。它可能是一个URL字符串

>>> canvas("https://vega.github.io/vega/examples/stacked-bar-chart.vg.json")

或者是一个JSON字符串

>>> graphic = """{
...   "$schema": "https://vega.github.io/schema/vega-lite/v2.json",
...   "description": "A simple bar chart with embedded data.",
...   "data": {
...     "values": [
...       {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
...       {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
...       {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
...     ]
...   },
...   "mark": "bar",
...   "encoding": {
...     "x": {"field": "a", "type": "ordinal"},
...     "y": {"field": "b", "type": "quantitative"}
...   }
... }"""
>>> canvas(graphic)

或者是一个嵌套的Python字典的JSON对象。它支持Vega 3和Vega-Lite 2规范。

交互功能

除了Vega图形本身可能具有的任何交互性外，VegaScope还有五个交互功能

• 另存为PNG：在您的下载文件夹中创建一个PNG图像（文件名是当前标题+.png）。

• 另存为SVG：在您的下载文件夹中创建一个SVG图像（以< span class="docutils literal">.svg结尾）。SVG文件可以作为矢量图形编辑（您可以移动数据点，添加注释），并无损转换为清晰的PDF文件。我最喜欢的编辑SVG和转换为PDF的工具是Inkscape。

• 缩放按钮/框：缩放网页上的图形。不影响已保存文件的大小。

• 查看源代码：查看原始JSON。

• 在编辑器中查看：在官方的Vega编辑器中编辑和查看图形。此编辑器可以让你深入了解Vega声明如何转换为图形，但它不适用于快速绘图。

从脚本保存图像

您可能想以编程方式保存图像（例如，在循环中），因此VegaScope画布有方法可以从服务器调用此操作

>>> canvas.png(graphic, title="filename")   # saves filename.png
>>> canvas.svg(graphic, title="filename")   # saves filename.svg

但是，您的网页浏览器可能将其解释为弹出窗口。通常，您不希望网络服务器远程将文件写入您的磁盘！在大多数网络浏览器中，第一次尝试以编程方式写入文件时，在地址栏中会出现一个指示器；选择它并允许此服务器的弹出窗口。

提示：如果您始终使用相同的端口号，则网页浏览器将记住该设置

>>> canvas = vegascope.LocalCanvas(port=12345)

远程查看

上面所有的示例都使用了vegascope.LocalCanvas。要使网络服务器对世界可见，请创建一个vegascope.Canvas。

>>> canvas = vegascope.Canvas()
Point web browser at: http://8.8.8.8:50060

其中8.8.8.8是运行VegaScope的机器的真实IP地址。一切照旧，只是网页浏览器不再受限于与服务器相同的机器。

然而，连接可能在服务器和客户端之间的任何步骤中被阻止。大多数系统管理员会阻止除了一系列合理的例外情况之外的所有端口；您可能需要要求打开一个端口，并明确传递该端口。

>>> canvas = vegascope.Canvas(port=12345)
Point web browser at: http://8.8.8.8:12345

即使端口阻止之外，一些管理员可能还会阻止HTTP协议，因为除了绘图之外，网络服务器可能还会用于更不良的活动。他们可能会以向任何有地址的人展示数据为由提出安全风险（尽管您可以通过canvas.connections来监控谁在观看）。这取决于您数据的敏感性。

如果您无法选择不受限制的网络服务器，但ssh是可用的（毕竟，您是如何连接到机器的终端的？），请考虑使用vegascope.TunnelCanvas。

>>> canvas = vegascope.TunnelCanvas()
Type into terminal:   ssh -L 43213:localhost:43213 username@8.8.8.8
Point web browser at: http://localhost:43213

TunnelCanvas仅在本地可用，但您可以通过ssh隧道扩展“本地”的含义。假设您已经通过一个ssh终端连接到远程机器，请打开另一个终端，并将新的ssh命令粘贴到其中。只要第二个终端保持打开状态，您的本地网页浏览器就会将http://localhost:43213视为远程的一个。

与vegascope.Canvas是可读的全球相比，vegascope.TunnelCanvas与ssh一样安全。选择最适合您的安全约束的选项。

Vega版本

VegaScope 指示您的网页浏览器使用来自 cdn.jsdelivr.net 的最新版本的 Vega、Vega-Lite 和 Vega-Embed。如果您想使用其他版本，可以在任何 Canvas 构造函数中指定 vega="3.3.1"、vegalite="2.5.2" 和 vegaembed="3.15.0"。

传递 None 或空字符串将使用 vegascope.py 文件内嵌入的独立版本。如果您电脑（尤其是运行网页浏览器的电脑）未连接到互联网，这很有用。

作为 shell 命令

如果更方便将 VegaScope 作为独立进程使用，它可以作为 shell 命令运行，监视文件更改或 stdin。所有选项都可作为命令行开关使用。

usage: vegascope.py [-h] [-w WAIT] [-t {Canvas,LocalCanvas,TunnelCanvas}]
                    [-T TITLE] [-b HOST] [-p PORT] [-q] [-Q] [--vega VERSION]
                    [--vega-lite VERSION] [--vega-embed VERSION]
                    [FILE]

VegaScope can be used within Python (import vegascope) or a shell command.

positional arguments:
  FILE                  file to watch for changes; default is '-' for lines on
                        stdin (stdin requires one JSON object per line)

optional arguments:
  -h, --help            show this help message and exit
  -w WAIT, --wait WAIT  poll wait time in seconds; default is 0.1 (100 ms);
                        not applicable to stdin
  -t {Canvas,LocalCanvas,TunnelCanvas}, --type {Canvas,LocalCanvas,TunnelCanvas}
                        type of Canvas; default is LocalCanvas
  -T TITLE, --title TITLE
                        browser window title and saved file name prefix
  -b HOST, --host HOST  host name to bind to; default is 0.0.0.0 for any
                        address (not applicable to LocalCanvas or
                        TunnelVanvas)
  -p PORT, --port PORT  port to bind to; default is 0 for any open port
  -q, --no-verbose      if supplied, do not log output to stdout (opposite of
                        verbose)
  -Q, --no-newtab       if supplied, do not open a browser window (opposite of
                        newtab, only applicable to LocalCanvas)
  --vega VERSION        Vega version to request from cdn.jsdelivr.net or "" to
                        use an standalone copy.
  --vega-lite VERSION   Vega-Lite version to request from cdn.jsdelivr.net or
                        "" to use an standalone copy.
  --vega-embed VERSION  Vega-Embed version to request from cdn.jsdelivr.net or
                        "" to use an standalone copy.

在文件监视模式下，当文件被覆盖时，画布将更新。在 stdin 监视模式下，当传递一行 JSON 文档到 stdin 时，画布将更新。