Data

Akin toVega’sdata model, the basic data model used by Vega-Lite istabular data, similar to a spreadsheet or a database table. Individual data sets are assumed to contain a collection of records, which may contain any number of named data fields.

Vega-Lite’sdata property describes the visualization’s data source as part of the specification, which can be eitherinline data (values) ora URL from which to load the data (url). Or, we can create an empty,named data source (name), which can bebound at runtime or populated from top-leveldatasets.

In addition, Vega-Lite includesdata generators which can generate data sets such as numerical sequences or geographic reference elements such as GeoJSON graticule or sphere objects.

Documentation Overview

• Types of Data Sources
  • Inline Data
  • Data from URL
  • Named Data Sources
• Format
  • json
  • csv
  • tsv
  • dsv
  • topojson
• Data Generators
  • Sequence Generator
  • Graticule Generator
  • Sphere Generator
• Datasets

Types of Data Sources

Inline Data

Inline Data can be specified usingvalues property. Here is a list of all properties of an inlinedata source:

For example, the following specification embeds an inline data table with nine rows and two columns (a andb).

If the input data is simply an array of primitive values, each value is mapped to thedata property of a new object. For example[5, 3, 8, 1] is loaded as:

[{"data": 5}, {"data": 3}, {"data": 8}, {"data": 1}]

You can also inline a string that will be parsed according to the specified format type.

Data from URL

Data can be loaded from a URL using theurl property. In addition, the format of the input data can be specified using theformatType property. By default Vega-Lite will infer the type from the file extension.

Here is a list of all properties describing adata source from URL:

For example, the following specification loads data from a relativeurl:data/cars.json. Note that the format type is implicitly"json" by default.

Named Data Sources

Data can also be added at runtime through theVega View API. Data sources are referenced by name, which is specified in Vega-Lite withname.

Here is a list of all properties describing a nameddata source:

For example, to create a data source namedmyData, use the following data

{  "name": "myData"}

You can use theVega view API to load data at runtime and update the chart. Here is an example usingVega-Embed:

vegaEmbed('#vis', spec).then((res) =>  res.view    .insert('myData', [      /* some data array */    ])    .run(),);

You can also use achangeset to modify the data on the chart as done on thisdata streaming demo

Format

The format object describes the data format and additional parsing instructions.

json

Loads a JavaScript Object Notation (JSON) file. Assumes row-oriented data, where each row is an object with named attributes. This is the default file format, and so will be used if no format property is provided. If specified, theformat property should have a type property of"json", and can also accept the following:

csv

Load a comma-separated values (CSV) file. This format type does not support any additional properties.

tsv

Load a tab-separated values (TSV) file. This format type does not support any additional properties.

dsv

Load a delimited text file with a custom delimiter. This is a general version of CSV and TSV.

topojson

Load a JavaScript Object Notation (JSON) file using the TopoJSON format. The input file must contain valid TopoJSON data. The TopoJSON input is then converted into a GeoJSON format. There are two mutually exclusive properties that can be used to specify the conversion process:

Data Generators

Sequence Generator

The sequence generator creates a set of numeric values based on given start, stop, and (optional) step properties. By default, new objects with a single field nameddata are generated; use theas property to change the field name.

For example, the following specification generates a domain of number values and then uses calculate transforms to draw a sine curve:

Graticule Generator

A graticule is a grid formed by lines of latitude and longitude. The graticule generator creates a geographic grid (asGeoJSON data) to serve as a guiding element to include in maps. The graticule generator can be specified with either a booleantrue value (indicating the default graticule) or a graticule property object:

The following example generates a custom graticule and visualizes it using an orthographic projection:

Sphere Generator

AGeoJSON sphere represents the full globe. The sphere generator injects a dataset whose contents are simply[{"type": "Sphere"}]. The resulting sphere can be used as a background layer within a map to represent the extent of the Earth. The sphere generator requires either a booleantrue value or an empty object{} as its sole property.

The following example generates a layered base map containing a sphere (light blue fill) and a default graticule (black strokes):

Datasets

Vega-Lite supports a top-leveldatasets property. This can be useful when the same data should be inlined in different places in the spec. Instead of setting values inline, specify datasets at the top level and then refer to thenamed datasource in the rest of the spec.datasets is a mapping from name to aninline dataset.

    "datasets": {      "somedata": [1,2,3]    },    "data": {      "name": "somedata"    }