1.0.0A JSON value: null, a boolean, a number, text, an array or an object.
This is the value model the whole of Vela exchanges — a specification arrives as one, the chart API emits one, and the runtime reads one. It is pure Ranger with no host JSON, so the same tree is built on every target, which is what makes a scene comparison against the reference implementation mean anything.
Two things it carries that a plain JSON model does not: object keys keep the
order they were written in, so a re-serialised specification is stable; and a
number remembers whether it was written as an integer, so 5 does not come
back as 5.0.
One row of a dataset, filled column by column.
A row is handed back already attached to its dataset, so nothing has to be pushed anywhere by the caller.
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
data.row().str("region", "South").num("sales", 93.0);
Puts a whole number in one column of this row.
A count is an integer and prints as one: 12, not 12.0. Use this rather than
num wherever the value counts things, or the axis labels will say so.
VlDataRow:
This row, so columns chain.
Puts text in one column of this row.
A column of text is read as a category unless every value in it parses as an ISO date, in which case it is an instant.
VlDataRow:
This row, so columns chain.
A table of rows, built once and given to as many charts as want it.
Rows are JSON objects — the same values the parser produces for
"data": {"values": […]} — so a dataset built here and one read off disk are
the same thing to everything downstream.
The dataset is a value beside the chart rather than a thing inside it: a spreadsheet's selection becomes one dataset and a dashboard's six panels read it.
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
data.row().str("region", "South").num("sales", 93.0);
Takes the rows of a JSON array as they came out of the parser.
A dataset built here and one read off disk are the same thing to everything downstream, so a selection from a grid, a file somebody read and a literal all arrive the same way.
(VlJson)
A JSON array of row objects.
VlDataset:
This dataset, so calls chain.
Fills one numeric column from an array, one value per row.
Column-wise filling, for a caller that holds arrays rather than records — a
spreadsheet column, a series of measurements. Row i of every column is the
same row, so two calls with arrays of the same length make a table.
VlDataset:
This dataset, so calls chain.
What kind of thing a column holds, in Vega-Lite's vocabulary.
Read off the rows rather than declared: numbers are a quantity, ISO dates are an instant, anything else is a name. A column the data does not have answers the empty string, so a caller can tell "no such column" from "a column of names" — which is the difference between a mistake and a chart.
(string)
The column name.
string:
quantitative
,
temporal
,
nominal
, or the empty string when no row has the column.
One mark and the channels it reads.
Every setter answers the mark, so a mark is written as one sentence.
aggregate, bin, title and the rest apply to the channel most recently
named — the cursor — which is what makes that sentence read in the order it is
thought. on moves the cursor back to a channel already set.
A channel names a column. A constant goes through valueNumber or
valueString, and the two are kept apart on purpose: .color("red") meaning a
column called red and .color("#c00") meaning paint it red cannot both be
true, and the version that guesses is the one that draws a chart nobody asked
for.
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
const chart = VlChart.create(data);
chart.bar().x("region").y("sales").aggregate("sum").title("Total sales");
Sets any channel to a column by name.
The named channel becomes the cursor, so the next aggregate, title or
type applies to it.
VlChartMark:
This mark, so calls chain.
Position along the horizontal axis.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Position along the vertical axis.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The far end of a horizontal interval, for a bar, an area or a rule that spans two values.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The far end of a vertical interval, for a bar, an area or a rule that spans two values.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Colour, and the legend that explains it.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Fill colour, set apart from the outline.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Outline colour, set apart from the fill.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Mark size: the area of a point, the width of a trail.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The symbol a point is drawn as.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
How opaque the mark is.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The angle an arc covers, which is what makes a pie or a donut.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
How far from the centre an arc reaches.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Groups the rows without drawing anything of its own: one line per group, no legend.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The text a label mark shows.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
The order the rows are drawn in, and the order a line joins its points.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Splits the chart into side-by-side panels, one per value.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Splits the chart into stacked panels, one per value.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
What separates the bars of a grouped bar chart, across the horizontal axis.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
What separates the bars of a grouped bar chart, across the vertical axis.
Names a COLUMN, never a constant. .color("red") means a column
called red; painting a mark red is markColor.
(string)
The column name.
VlChartMark:
This mark, so channels chain.
Sets a channel to a count of rows: one number per group, with no column to read.
(string)
The channel to put the count on, usually "y" or "x".
VlChartMark:
This mark, so calls chain.
Sets a channel to a constant number rather than to a column.
VlChartMark:
This mark, so calls chain.
Sets a channel to a constant string rather than to a column.
This is how a mark is painted a fixed colour: .valueString("color" "#c00").
The channel setters name columns and never constants, because a .color(…)
that guessed between the two would draw a chart nobody asked for.
VlChartMark:
This mark, so calls chain.
Sets a whole channel from an already-built definition.
The escape hatch. Vega-Lite is larger than any fluent surface over it, and a definition that lands in the same specification is better than waiting for this API to grow a method.
VlChartMark:
This mark, so calls chain.
Moves the cursor back to a channel that is already set.
Everything that follows — aggregate, title, scaleType — applies to it.
A channel that was never set is reported in the chart's errors rather than
silently created.
(string)
The channel name.
VlChartMark:
This mark, so calls chain.
How the rows in each group are reduced to one value.
VlChartMark:
This mark, so calls chain.
Bins the cursor channel's column into buckets.
VlChartMark:
This mark, so calls chain.
Bins the cursor channel's column into at most this many buckets.
(number)
The upper bound on the number of bins.
VlChartMark:
This mark, so calls chain.
Which part of an instant to read: year, month, yearmonth, hours and the rest.
(string)
The time unit.
VlChartMark:
This mark, so calls chain.
States what the column holds, when the data cannot say.
A column of years is numbers and is usually a category, which is the case this exists for.
VlChartMark:
This mark, so calls chain.
The axis or legend label for the cursor channel.
(string)
The label.
VlChartMark:
This mark, so calls chain.
The number or date format its axis labels are drawn in.
(string)
A d3-format or d3-time-format pattern.
VlChartMark:
This mark, so calls chain.
How marks sharing a position are stacked.
VlChartMark:
This mark, so calls chain.
Draws the marks overlapping rather than stacked.
VlChartMark:
This mark, so calls chain.
The order a discrete scale runs in, taken from another column.
(string)
The column to sort by.
VlChartMark:
This mark, so calls chain.
Keeps the order the rows arrived in, rather than sorting alphabetically.
The one every spreadsheet wants.
VlChartMark:
This mark, so calls chain.
Sets the cursor channel's whole scale definition.
(VlJson)
The scale definition.
VlChartMark:
This mark, so calls chain.
The kind of scale the cursor channel uses.
VlChartMark:
This mark, so calls chain.
The colour scheme a colour channel draws from.
VlChartMark:
This mark, so calls chain.
Draws the cursor channel without a legend.
VlChartMark:
This mark, so calls chain.
Draws the cursor channel without an axis.
VlChartMark:
This mark, so calls chain.
Which side of the plot the cursor channel's axis stands on.
A Pareto chart's cumulative line is measured up the right-hand side, which is the whole point of drawing it there.
VlChartMark:
This mark, so calls chain.
Sets the cursor channel's whole axis definition.
(VlJson)
The axis definition.
VlChartMark:
This mark, so calls chain.
Sets any numeric property of the mark itself.
VlChartMark:
This mark, so calls chain.
Sets any string property of the mark itself.
VlChartMark:
This mark, so calls chain.
Sets any boolean property of the mark itself.
VlChartMark:
This mark, so calls chain.
Whether the mark is filled or drawn as an outline.
(boolean)
True to fill.
VlChartMark:
This mark, so calls chain.
How big every mark is drawn, as one number rather than from a column.
(number)
The size.
VlChartMark:
This mark, so calls chain.
Paints every mark one colour, rather than reading a column.
(string)
A CSS colour.
VlChartMark:
This mark, so calls chain.
How opaque every mark is drawn, as one number rather than from a column.
(number)
0 to 1.
VlChartMark:
This mark, so calls chain.
How a line joins its points.
VlChartMark:
This mark, so calls chain.
Draws a line showing the points it was drawn through.
(boolean)
True to show them.
VlChartMark:
This mark, so calls chain.
The hole in the middle of an arc, which is what turns a pie into a donut.
(number)
The inner radius in pixels.
VlChartMark:
This mark, so calls chain.
How rounded the corners of a bar or a rectangle are.
(number)
The radius in pixels.
VlChartMark:
This mark, so calls chain.
Shows every column the mark encodes when the reader points at it.
(boolean)
True to show a tooltip.
VlChartMark:
This mark, so calls chain.
Shows one named column as the tooltip.
(string)
The column name.
VlChartMark:
This mark, so calls chain.
Shows several named columns as the tooltip, in the order they should be read.
A list is not a channel, so the cursor does not move onto it: the next title
belongs to whatever was named before.
VlChartMark:
This mark, so calls chain.
How thick a tick is drawn across its band.
A hi-lo-open-close chart's open and close are ticks, and a two-pixel one is what makes them read as marks rather than as hairlines.
(number)
The thickness in pixels.
VlChartMark:
This mark, so calls chain.
How thick the mark's outline is drawn.
(number)
The width in pixels.
VlChartMark:
This mark, so calls chain.
Which way a tick lies, or which way a bar with only one position channel runs.
VlChartMark:
This mark, so calls chain.
What an interval mark is computed from.
VlChartMark:
This mark, so calls chain.
A chart: a dataset, the channels every mark shares, how big it is, and the marks.
The fluent surface is a writer of specifications, not the engine. Every
call writes into a specification and toSpec hands that specification over;
nothing here computes a scale, a layout or a pixel. There is no path where the
API computes something the engine would have computed differently, because the
API computes nothing at all.
A channel said on the chart is inherited by every mark on it, so a line and the points on top of it are two marks and one set of axes rather than two charts.
A channel need not state its type — the data says. A column of numbers is a
quantity, a column of ISO dates an instant, anything else a name. A field the
data does not have is an error rather than a guess: errors is non-empty
and the caller can say so instead of drawing an empty axis.
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
data.row().str("region", "South").num("sales", 93.0);
const chart = VlChart.create(data);
chart.size(300, 200);
chart.bar().x("region").y("sales").aggregate("sum");
const spec = chart.toSpec();
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
const chart = VlChart.create(data);
chart.x("region").y("sales").color("region");
chart.area().markOpacity(0.35);
chart.line();
Adds a mark of any type the compiler knows.
(string)
The Vega-Lite mark name.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a bar mark to the chart.
A rectangle per row: the bar chart, and with x2/y2 a range.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a line mark to the chart.
A line joining the rows in order.
VlChartMark:
The new mark, so its channels and properties chain.
Adds an area mark to the chart.
A filled band between a line and a baseline.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a point mark to the chart.
One symbol per row: the scatter plot.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a circle mark to the chart.
A filled circle per row — point with the shape settled.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a square mark to the chart.
A filled square per row — point with the shape settled.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a tick mark to the chart.
A short stroke per row, across the band it sits in.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a rule mark to the chart.
A line at one value, spanning the plot or between x2/y2.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a rect mark to the chart.
A rectangle over two ranges: the heatmap.
VlChartMark:
The new mark, so its channels and properties chain.
Adds an arc mark to the chart.
A wedge, which with theta is a pie and with innerRadius a donut.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a text mark, which draws the value of its text channel.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a boxplot mark to the chart.
A box and whiskers, computed from the rows rather than read off them.
VlChartMark:
The new mark, so its channels and properties chain.
Adds an error bar: an interval computed from the rows rather than read off them.
extent decides what the interval is — stderr by default, or stdev, ci
or iqr.
VlChartMark:
The new mark, so its channels and properties chain.
Adds an error band: the same interval as an error bar, drawn as a filled region.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a trail mark to the chart.
A line whose width says something: a trail thickens with its size.
VlChartMark:
The new mark, so its channels and properties chain.
Adds an image mark to the chart.
A picture per row, placed by its position channels.
VlChartMark:
The new mark, so its channels and properties chain.
Adds a geoshape mark to the chart.
A map: the shapes come from the data and the projection places them.
VlChartMark:
The new mark, so its channels and properties chain.
The mark added last, for a caller that built one and let go of it.
A chart with no marks answers a mark belonging to nothing and reports it in
errors, rather than quietly adding a point nobody asked for.
VlChartMark:
The last mark added.
Stops the layers sharing one scale on a channel.
Two marks measuring different things up the same side of the plot must not share a scale. This is what makes a Pareto chart — bars against a count, a line against a running percentage — rather than two series averaged into one axis neither of them asked for.
(string)
The channel to split, usually "y".
VlChart:
This chart, so calls chain.
The chart as a Vega-Lite specification.
One mark comes out as a plain specification; several come out as layers, each carrying the shared channels in full — a specification that states everything is one the compiler already handles and one a person can read in a diff.
May be called more than once. Check errors afterwards: a chart that names a
column its data does not have is reported here, where Vega-Lite would have
drawn an empty axis and said nothing.
VlJson:
A Vega-Lite specification, ready for
VlCompile
.
const data = VlDataset.create();
data.row().str("region", "North").num("sales", 120.0);
data.row().str("region", "South").num("sales", 93.0);
const chart = VlChart.create(data);
chart.size(300, 200);
chart.bar().x("region").y("sales").aggregate("sum");
const spec = chart.toSpec();