Display nushell tables using Vega Lite in a webview. Not to be confused with the Vega View API.
This is a rust project so rust up! The supporting scripts require nushell, install here. Next, download the Vega prerequisites:
nu download-vega.nu
The executable, vega-view
, can now be built:
cargo build --release
To run vega-view
a webview component must be present. You probably already have one as part of your platform but check the platform specific notes for the wry project. (This project uses wry.)
First run nu
then:
use vega.nu # load the vega nushell module.
vega view <spec> # visualize the input with a vega-lite specification
vega bar <value> # a specification for a bar graph
vega series <value> <time> # a specification for a time series plot
vega scatter <value> <domain> # a specification for a scatter plot
vega flip # exchange the x and y axes of a specification
For example, the following nushell script will visualize the b
column of the table in example.json
:
use vega.nu
let spec = vega bar b
let data = open example.json
$data | vega view $spec
This produces a single bar with height representing the sum of the b
column in the data. A more interesting bar graph would divide the data up into categories. Identifying the category fields and putting it as a one-liner:
open example.json | vega view (vega bar b --category=t --subcategory=a)
With nushell's excellent data handling abilities you can equally easily visualize CSV, SQLite, JSON and other data sources. You can write your own specification or use one of the built in ones below.
A vega-lite specification for a bar graph.
Usage:
> bar {flags} <value>
Flags:
--category <String> - field to discriminate different bars
--subcategory <String> - field to discriminate stacked bar sections
--aggregate <String> - how to combine values for a bar or bar section (default: 'sum')
Parameters:
value <string>: field name for the bar height
Example:
open example.json | vega view --title "Stacked Bar Example" (vega bar b --category=t --subcategory=a)
A vega-lite specification for a time series plot.
Usage:
> series {flags} <value> <time>
Flags:
--category <String> - field to discriminate different series
--area - render as a stacked area plot
Parameters:
value <string>: field name for the series values
time <string>: field for time values
Example:
open example.json | vega view --title "Time Series Example" (vega series b t --category a)
A vega-lite specification for a scatter plot.
Usage:
> scatter {flags} <value> <domain>
Flags:
--category <String> - field for the category of the point in the plot
Parameters:
value <string>: field name for the y coodinate of a point in the plot
domain <string>: field for the x coodinate of a point in the plot
Example:
open example.json | vega view --title "Scatter Plot Example" (vega scatter b t --category a)
The vega-lite gallery is a good place to start when developing a visualization. You can adapt one of these specifications by changing the field names to match your data. You can omit the data
section of the specification.
The vega view
nushell command takes several options controlling how it displaya a Vega visualization of the input data in a window. (We have seen the --title
option in the examples above.)
Usage:
> view {flags} <spec>
Flags:
--title <String> - title for the window (default: 'Vega View')
--width <Number> - width of the window (default: 1000)
--height <Number> - height of the window (default: 800)
-h, --help - Display the help message for this command
Parameters:
spec <record>: a vega-lite specification
The vega-view
executable creates and controls the webview. The vega view
nushell command wraps the executable and takes care of conversions from nushell tables. The wrapper locates the executable via the environment variable $env.vega_view_bin
.
It is possible to use vega-view
directly without the nushell scripting. By default JSON data is supplied on the standard input and a JSON vega-lite specification is given as an argument. Ensure that the data url in the specification is /data
. ie:
{
...
data: { url: '/data' },
...
}
The full command is:
Usage: vega-view [OPTIONS] <SPEC>
Arguments:
<SPEC> vega-lite specification for this visualization
Options:
--page <PAGE> file containing a HTML template for the page
--script <SCRIPT> file containing javascript used in the page
--data <DATA> file containing data to visualize (default is stdin)
--title <TITLE> The window title
--width <WIDTH> The window width
--height <HEIGHT> The window height
-h, --help Print help
Material derived from the Vega project including vega-all.js is Copyright (c) 2024, University of Washington Interactive Data Lab. See VEGA-LICENSE.
All other material is Copyright (c) 2024 Cuprous Pty Ltd Australia. See LICENSE.