Vizsla is a simple JavaScript API for Vega-Lite:

//scatter plot
vz(cars)
  .x('Horsepower')
  .y('Miles_per_Gallon')
  .plot()

See this Observable notebook for some interactive examples.

Install/Load

Vizsla uses the Universal Module Definition (UMD) so should work in any JavaScript environment. For example:

• Node.js:

  • install: npm install --save @gjmcn/vizsla
  • load: const vz = require('@gjmcn/vizsla');

• Browser, using <script>: creates a global variable vz

API Reference

Constructors

• Except for vz.Vizsla, do not use new when calling constructors.

• Constructors can be called with no arguments. For example, vz.repeat() creates a repeat spec with no inner spec; use inner to set the inner spec.

# vz(d, ops)

  d: string (URL of data) or object/array (data)

  ops: options object

Creates a unit spec and, if d is truthy, sets its data — see data.

Unit specs have mark type 'point' by default.

Returns a new unit spec.

# vz.layer(sub0, sub1, sub2, ...)

  sub0, sub1, sub2, ... : specs to be layered; unit and layer specs only

Returns a new layer spec.

# vz.hconcat(sub0, sub1, sub2, ...) # vz.vconcat(sub0, sub1, sub2, ...)

  sub0, sub1, sub2, ... : specs to be concatenated

Returns a new hconcat or vconcat spec.

# vz.facet(sub)

  sub: spec to be faceted

Use row and column (see encode) to set the channels.

Use data to set the data property of a facet. If a facet does not have a data property, it uses the data of the first unit in its inner spec that has a data property — all units in the inner spec that use this data ignore their own data property.

Note: nested facets are not currently supported in Vizsla.

Returns a new facet spec.

# vz.repeat(sub)

  sub: spec to be repeated

Use across and down to set the repeat directions and channels.

Note: Vizsla currently only allows a unit or facet spec to be repeated.

Returns a new repeat spec.

# vz.Vizsla(type = 'unit')

  type: string, 'unit', 'layer', 'hconcat', 'vconcat', 'facet' or 'repeat'

vz.Vizsla is a standard constructor, so e.g. new vz.Vizsla() returns a new unit spec.

Methods

• The following 'spec' methods are actually methods of vz.Vizsla.prototype.

• Various methods accept an 'options object' as their final argument. This is used to specify properties which are not covered by a dedicated method or argument. For example:

  vz(cars)
    .bar()
    .x('Cylinders', 'o')
    .y('Acceleration', 'q', {aggregate: 'mean'})  //options object
    .plot();

# spec.mark(type, ops)

  spec type: unit

  type: string, the mark type

  ops: options object

Set mark: type to type plus any additional mark properties specified in ops.

There are also convenience mark methods:

area, bar, boxplot, circle, errorband, errorbar, geoshape, line, point, rect, rule, square, text, tick, trail

//these are equivalent
vz().bar();
vz().mark('bar');

//these are equivalent
vz().bar(ops);
vz().mark('bar', ops);

Mark methods return the spec.

# spec.encode(chn, field, type = 'q', ops)

  spec type: unit, layer, facet

  chn: string, channel name

  field: string, field name

  type: string, 'q', 'quantitative', 't', 'temporal', 'o', 'ordinal', 'n' or 'nominal'

  ops: options object

Set channel chn: field to field, type to type plus any additional properties specified in ops.

There are also convenience methods:

x, y, x2, y2, longitude, latitude, longitude2, latitude2, color, opacity, fillOpacity, strokeOpacity, strokeWidth, size, shape, label, tooltip, href, key, order, detail, row, column

//these are equivalent
vz(cars).x('Horsepower');
vz(cars).encode('x', 'Horsepower');

//these are equivalent
vz(cars).x('Horsepower', 'q', ops);
vz(cars).encode('x', 'Horsepower', 'q', ops);

The label method actually corresponds to the text channel — text is a mark method.

Pass a non-null falsy value as field to omit the field property from the channel object.

Pass true as field as a shortcut for the count aggregate:

//these are equivalent
vz().y(true);
vz().y(false, 'q', {aggregate: 'count'});

//these are equivalent
vz().y(true, 'q', {title: 'Total'});
vz().y(false, 'q', {aggregate: 'count', title: 'Total'});

These methods return the spec.

# spec.transform(t0, t1, t2, ...)

  spec type: any

  t0, t1, t2, ... : object

Set transform.

Returns the spec.

# spec.projection(type = 'mercator', ops)

  spec type: unit, layer

  type: string

  ops: options object

Set projection: type to type plus any additional properties specified in ops.

Returns the spec.

# spec.across(chn, fields = []) # spec.down(chn, fields = [])

  spec type: repeat

  chn: string, channel name

  fields: array of strings, field names

Set across/down repeat to use channel chn and fields fields.

# spec.data(d, ops)

  spec type: unit, facet

  d: string (URL of data) or object/array (data)

  ops: options object

Set data: url/values to d plus any additional properties specified in ops.

Note: only unit and facet specs can have data in Vizsla.

Returns the spec.

# spec.inner(sub0, sub1, sub2, ...)

  spec type: layer, hconcat, vconcat, facet, repeat

   sub0, sub1, sub2, ... : spec object

Set inner spec(s) to sub0, sub1, sub2, ...

Returns the spec.

The following methods set the property of the same name to the argument and return the spec.

| Name | Spec type | | ---- | --------- | | description(string) | any | | title(string) | any | | name(string) | any (only used at top-level)| | $schema(string) | any (only used at top-level) | | background(string) | any (only used at top-level) | | padding(number/object) | any (only used at top-level) | | autosize(string/object) | any (only used at top-level) | | config(object) | any (only used at top-level) | | resolve(object) | layer, hconcat, vconcat, facet, repeat | | center(boolean/object) | hconcat, vconcat, facet, repeat | | spacing(number/object) | hconcat, vconcat, facet, repeat | | bounds(string) | hconcat, vconcat, facet, repeat | | align(string/object) | facet, repeat | | width(number) | unit, layer | | height(number) | unit, layer | | selection(object) | unit |

Example:

vz()
  .width(300)
  .height(200);

# spec.copy(recursive = true)

Copy spec. All properties are deep copied except that:

• If recursive is falsy, the inner spec(s) are not included in the copy.

• Inline data is not copied. Specifically, the data object is deep copied except for its values property — the spec and the copy refer to the same data structure.

Returns the copy.

# spec.prep()

Returns a Vega-Lite spec object ready to be rendered. The returned spec is independent of the calling spec with the possible exception that they share inline data (since Vizsla does not copy inline data).

The returned spec uses the Vega-Lite datasets property to avoid repeating inline data and for repeat specs, includes appropriately modified versions of the inner specs.

# vz.Vizsla.prototype.plot()

The plot property is initially undefined. It should be set to a function that renders the spec.

Vega-Embed examples:

• use Vizsla in an HTML document where Vega-Embed is loaded in a <script> tag:

  vz.Vizsla.prototype.plot = function(elm, opt) {
    return vegaEmbed(elm, this.prep(), opt);
  };

• use Vizsla in an Observable notebook:

  //in one cell
  vegaEmbed = require("vega-embed@3")
  
  //in another cell
  vz = {
    const vz = await require('@gjmcn/vizsla');
    vz.Vizsla.prototype.plot = function(opt) {
      return vegaEmbed(this.prep(), opt);
    };
    return vz;
  }

Notes

• Options arguments (ops) take precedence over other arguments and method names. For example, vz().bar({type: 'line'}) will set the mark type to 'line', not 'bar'.

• Pass null to delete a spec property:

  • encode method: spec.encode('x', null)

  • other methods: pass null as the first argument; e.g. spec.x(null) or spec.mark(null) or spec.inner(null)

• Spec objects have the structure:

  object
    spec           //object, spec manipulated by vz methods
    type           //string, spec type
    use            //object (unit specs only), data
    repeatChannel  //object (repeat spec only), repeat channel(s)

Contributions

Are welcome! Open an issue or create a pull request.

Also See

• Altair — Python
• VegaLite.jl — Julia