vega-lite-api

Vega-Lite API

A JavaScript API for creating Vega-Lite JSON specifications. Vega-Lite is a high-level grammar for visual analysis that generates complete Vega specifications.

With the Vega-Lite API, you can write JavaScript code like this:

vl.markBar().data('data/movies.json').encode(
  vl.x().bin('IMDB_Rating'),
  vl.y().count()
)

To produce Vega-Lite JSON like this:

{
  "mark": "bar",
  "data": {"url": "data/movies.json"},
  "encoding": {
    "x": {
      "bin": true,
      "field": "IMDB_Rating",
      "type": "quantitative"
    },
    "y": {
      "aggregate": "count",
      "type": "quantitative"
    }
  }
}

To get started with the Vega-Lite API, see these Observable notebooks:

• Introduction to Vega-Lite
• Vega-Lite API

Build Instructions

For a basic setup allowing you to build the API and run tests:

• Clone https://github.com/vega/vega-lite-api.
• Run yarn to install dependencies for all packages. If you don't have yarn installed, see https://yarnpkg.com/en/docs/install.
• Once installation is complete, run yarn build to build the API generator and generate API source code in the src directory. Run yarn test to additionally run the test suite.

API Reference

Chart Constructors

• vl.mark - Create a new mark of unspecified type.
• vl.markArea - Create a new area mark.
• vl.markBar - Create a new bar mark.
• vl.markBoxplot - Create a new boxplot mark.
• vl.markCircle - Create a new circle mark.
• vl.markErrorband - Create a new errorband mark.
• vl.markErrorbar - Create a new errorbar mark.
• vl.markGeoshape - Create a new geoshape mark.
• vl.markLine - Create a new line mark.
• vl.markPoint - Create a new point mark.
• vl.markRect - Create a new rect mark.
• vl.markRule - Create a new rule mark.
• vl.markSquare - Create a new square mark.
• vl.markText - Create a new text mark.
• vl.markTick - Create a new tick mark.
• vl.markTrail - Create a new trail mark.
• vl.layer - Create a new layered chart.
• vl.hconcat - Horizontally concatenate charts.
• vl.vconcat - Vertically concatenate charts.

Utilities

• vl.register - Register Vega and Vega-Lite with the API.

Data

• vl.data - Create a new data reference for a chart or lookup.
• vl.url - Define a url data source.
• vl.values - Define a inline data source.
• vl.sequence - Define a sequence data generator.
• vl.sphere - Define a sphere data generator.
• vl.graticule - Define a graticule data generator.
• vl.csv - Define a data source for csv format data.
• vl.dsv - Define a data source for dsv format data.
• vl.json - Define a data source for json format data.
• vl.topojson - Define a data source for topojson format data.
• vl.tsv - Define a data source for tsv format data.
• vl.csvFormat - Specify parsing of csv format data.
• vl.dsvFormat - Specify parsing of dsv format data.
• vl.jsonFormat - Specify parsing of json format data.
• vl.topojsonFormat - Specify parsing of topojson format data.
• vl.tsvFormat - Specify parsing of tsv format data.
• vl.lookupData - Specify a lookup on a secondary data source.

Encodings

• vl.color - Specify the color encoding channel.
• vl.column - Specify the column encoding channel.
• vl.detail - Specify the detail encoding channel.
• vl.facet - Specify the facet encoding channel.
• vl.fill - Specify the fill encoding channel.
• vl.fillOpacity - Specify the fillOpacity encoding channel.
• vl.href - Specify the href encoding channel.
• vl.key - Specify the key encoding channel.
• vl.latitude - Specify the latitude encoding channel.
• vl.latitude2 - Specify the latitude2 encoding channel.
• vl.longitude - Specify the longitude encoding channel.
• vl.longitude2 - Specify the longitude2 encoding channel.
• vl.opacity - Specify the opacity encoding channel.
• vl.order - Specify the order encoding channel.
• vl.row - Specify the row encoding channel.
• vl.shape - Specify the shape encoding channel.
• vl.size - Specify the size encoding channel.
• vl.stroke - Specify the stroke encoding channel.
• vl.strokeOpacity - Specify the strokeOpacity encoding channel.
• vl.strokeWidth - Specify the strokeWidth encoding channel.
• vl.text - Specify the text encoding channel.
• vl.tooltip - Specify the tooltip encoding channel.
• vl.x - Specify the x encoding channel.
• vl.x2 - Specify the x2 encoding channel.
• vl.xError - Specify the xError encoding channel.
• vl.xError2 - Specify the xError2 encoding channel.
• vl.y - Specify the y encoding channel.
• vl.y2 - Specify the y2 encoding channel.
• vl.yError - Specify the yError encoding channel.
• vl.yError2 - Specify the yError2 encoding channel.

References

• vl.field - A reference to a data field.
• vl.fieldN - A reference to a nominal data field.
• vl.fieldO - A reference to a ordinal data field.
• vl.fieldQ - A reference to a quantitative data field.
• vl.fieldT - A reference to a temporal data field.
• vl.encoding - A reference to an encoding channel.
• vl.repeat - A field variable reference for a repeated chart.
• vl.value - A constant encoding value.

Projections

• vl.projection - Define a cartographic projection for longitude, latitude coordinates.

Selections

• vl.selectInterval - Define a new interval selection.
• vl.selectMulti - Define a new multi selection.
• vl.selectSingle - Define a new single selection.

Selection Bindings

• vl.checkbox - Define a new HTML checkbox input element binding.
• vl.menu - Define a new HTML select input element binding.
• vl.radio - Define a new HTML radio input element binding.
• vl.slider - Define a new HTML range input element binding.

Logical Operations

• vl.not - Logical NOT operation.
• vl.and - Logical AND operation.
• vl.or - Logical OR operation.

Data Transformations

• vl.aggregate - Group and summarize data as counts, sums, averages, etc.
• vl.bin - Discretize numeric values into uniform bins.
• vl.calculate - Calculate a new data field value.
• vl.filter - Remove data that does not match provided conditions.
• vl.flatten - Map array fields to new records, one per array entry.
• vl.fold - Collapse one or more data fields into two key, value fields.
• vl.impute - Fill in missing values with imputed values.
• vl.joinaggregate - Extend input data with aggregate values as new fields.
• vl.join - A convenient shorthand for joinaggregate.
• vl.lookup - Extend input data with values from another data source.
• vl.sample - Filter random records from the data limit its size.
• vl.stack - Compute running sums to stack groups of values.
• vl.timeUnit - Discretize date/time values into meaningful intervals.
• vl.window - Perform running calculations over sorted groups.
• vl.groupby - Group by fields for aggregate or window transforms.

Aggregate Operations

• vl.count - A count aggregate operation.
• vl.valid - A valid aggregate operation.
• vl.missing - A missing aggregate operation.
• vl.distinct - A distinct aggregate operation.
• vl.sum - A sum aggregate operation.
• vl.mean - A mean aggregate operation.
• vl.average - A average aggregate operation.
• vl.variance - A variance aggregate operation.
• vl.variancep - A variancep aggregate operation.
• vl.stdev - A stdev aggregate operation.
• vl.stdevp - A stdevp aggregate operation.
• vl.stderr - A stderr aggregate operation.
• vl.median - A median aggregate operation.
• vl.q1 - A q1 aggregate operation.
• vl.q3 - A q3 aggregate operation.
• vl.ci0 - A ci0 aggregate operation.
• vl.ci1 - A ci1 aggregate operation.
• vl.min - A min aggregate operation.
• vl.max - A max aggregate operation.
• vl.argmin - A argmin aggregate operation.
• vl.argmax - A argmax aggregate operation.

Window Operations

• vl.row_number - A row_number window operation.
• vl.rank - A rank window operation.
• vl.dense_rank - A dense_rank window operation.
• vl.percent_rank - A percent_rank window operation.
• vl.cume_dist - A cume_dist window operation.
• vl.ntile - A ntile window operation.
• vl.lag - A lag window operation.
• vl.lead - A lead window operation.
• vl.first_value - A first_value window operation.
• vl.last_value - A last_Value window operation.
• vl.nth_value - A nth_value window operation.

TimeUnit Operations

• vl.year - A time unit operation for year.
• vl.quarter - A time unit operation for quarter.
• vl.month - A time unit operation for month.
• vl.day - A time unit operation for day.
• vl.date - A time unit operation for date.
• vl.hours - A time unit operation for hours.
• vl.minutes - A time unit operation for minutes.
• vl.seconds - A time unit operation for seconds.
• vl.milliseconds - A time unit operation for milliseconds.
• vl.yearmonth - A time unit operation for yearmonth.
• vl.timeYQ - A time unit operation for yearquarter.
• vl.timeYQM - A time unit operation for yearquartermonth.
• vl.timeYM - A time unit operation for yearmonth.
• vl.timeYMD - A time unit operation for yearmonthdate.
• vl.timeYMDH - A time unit operation for yearmonthdatehours.
• vl.timeYMDHM - A time unit operation for yearmonthdatehoursminutes.
• vl.timeYMDHMS - A time unit operation for yearmonthdatehoursminutesseconds.
• vl.timeQM - A time unit operation for quartermonth.
• vl.timeMD - A time unit operation for monthdate.
• vl.timeMDH - A time unit operation for monthdatehours.
• vl.timeHM - A time unit operation for hoursminutes.
• vl.timeHMS - A time unit operation for hoursminutesseconds.
• vl.timeMS - A time unit operation for minutesseconds.
• vl.timeSMS - A time unit operation for secondsmilliseconds.
• vl.utcyear - A time unit operation for utcyear.
• vl.utcquarter - A time unit operation for utcquarter.
• vl.utcmonth - A time unit operation for utcmonth.
• vl.utcday - A time unit operation for utcday.
• vl.utcdate - A time unit operation for utcdate.
• vl.utchours - A time unit operation for utchours.
• vl.utcminutes - A time unit operation for utcminutes.
• vl.utcseconds - A time unit operation for utcseconds.
• vl.utcmilliseconds - A time unit operation for utcmilliseconds.
• vl.utcyearmonth - A time unit operation for utcyearmonth.
• vl.utcYQ - A time unit operation for utcyearquarter.
• vl.utcYQM - A time unit operation for utcyearquartermonth.
• vl.utcYM - A time unit operation for utcyearmonth.
• vl.utcYMD - A time unit operation for utcyearmonthdate.
• vl.utcYMDH - A time unit operation for utcyearmonthdatehours.
• vl.utcYMDHM - A time unit operation for utcyearmonthdatehoursminutes.
• vl.utcYMDHMS - A time unit operation for utcyearmonthdatehoursminutesseconds.
• vl.utcQM - A time unit operation for utcquartermonth.
• vl.utcMD - A time unit operation for utcmonthdate.
• vl.utcMDH - A time unit operation for utcmonthdatehours.
• vl.utcHM - A time unit operation for utchoursminutes.
• vl.utcHMS - A time unit operation for utchoursminutesseconds.
• vl.utcMS - A time unit operation for utcminutesseconds.
• vl.utcSMS - A time unit operation for utcsecondsmilliseconds.