Chart API

A Ranger API. There is no npm package yet. The examples on this page call the compiled classes in the browser. The standalone live page is the same API with Ranger and JavaScript tabs.

Build a Vega-Lite chart by calling methods. The runtime draws the specification this API writes.

Generated from the Ranger sources that declare the surface — gallery/vela/src/VlChart.rgr — so this page cannot describe a method that is not there.

The chart API

Import "VlChart.rgr"

A dataset, a view, and marks. Nothing here draws: toSpec() hands the specification to Vela.

VlChart.rgr — Vela’s own chart API: marks and channels, in Ranger. Vela runs a specification. Until now the only way to hand it one was to write that specification out as JSON — which is what gallery/datagrid does, in three hundred lines of string concatenation, quote by escaped quote. This is the other front door: an API that a program calls, which builds the same Vega-Lite value the parser would have produced.

def data (VlDataset.create())
data.row().str("region" "North").num("sales" 120.0)
data.row().str("region" "South").num("sales"  93.0)

def chart (VlChart.create(data))
chart.size(300 200)
chart.bar().x("region").y("sales")

def spec:VlJson (chart.toSpec())    ; → VlCompile → VlRuntime → a picture

Four ideas are borrowed, and it is worth saying which from where:

the fluent surface is not the engine (AntV G2). Every call writes into a specification; toSpec hands that specification over and the API is done. Nothing here computes a scale, a layout or a pixel — the runtime that already does all three is the only thing that draws.
a view’s encoding is inherited by its marks (G2 again). chart.x(…) is said once and every mark added to the chart reads it, so a line and the points on top of it are two marks and one set of axes rather than two charts. Inheritance is resolved HERE, at emit time: each layer comes out carrying its channels in full, because a spec that states everything is one the compiler already handles and one a person can read in a diff.
a channel need not state its type (Observable Plot). A column of numbers is quantitative, a column of ISO dates is temporal, anything else is nominal — read off the data rather than asked for. 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.
the data is a value beside the chart, not a thing inside it (Apache ECharts). VlDataset is built once and can be given to several charts; a spreadsheet’s selection becomes one dataset and a dashboard’s six panels read it.

What this file deliberately does NOT do: draw, measure, scale, lay out, or know what a pixel is. It imports VlJson and nothing else, so the API layer cannot grow a dependency on the runtime by accident — and a caller that wants the runtime imports it directly, exactly as one that hands it parsed JSON does.

VlDataRow

One row, built field by field. row() hands one back already attached to the dataset, so nothing has to be pushed anywhere by the caller.

Call	Gives	What it is for
`row.num(field value)`	`VlDataRow`
`row.whole(field value)`	`VlDataRow`
`row.str(field value)`	`VlDataRow`
`row.flag(field value)`	`VlDataRow`
`row.json(field value)`	`VlDataRow`
`row.back()`	`VlDataset`

VlDataset

A named table. 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.

Call	Gives	What it is for
`VlDataset.create()`	`VlDataset`
`dataset.row()`	`VlDataRow`
`dataset.addRow(row)`	`VlDataset`
`dataset.fromValues(values)`	`VlDataset`	Rows as they came out of the JSON parser: a dataset can be a selection from a grid, a file somebody read, or a literal.
`dataset.numbers(field values)`	`VlDataset`	Column-wise filling, for a caller that holds arrays rather than records — a spreadsheet column, a series of measurements.
`dataset.strings(field values)`	`VlDataset`
`dataset.rowAt(index)`	`VlJson`
`dataset.count()`	`int`
`dataset.hasField(field)`	`boolean`
`dataset.fieldType(field)`	`string`	What kind of thing a column holds, in Vega-Lite’s vocabulary.
`VlDataset.looksLikeDate(text)`	`boolean`	“2016-01-01”, “2016-01-01T12:00:00Z”, “2016-01”.
`dataset.toValues()`	`VlJson`

`dataset.fromValues(values)`

Rows as they came out of the JSON parser: a dataset can be a selection from a grid, a file somebody read, or a literal.

`dataset.numbers(field values)`

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.

`dataset.fieldType(field)`

What kind of thing a column holds, in Vega-Lite’s vocabulary. Numbers are a quantity, an ISO date is an instant, everything else is a name. Read from the rows rather than declared, because the rows are already here — and a column that is empty answers nothing, so the caller can tell “no such column” from “a column of names”.

`VlDataset.looksLikeDate(text)`

“2016-01-01”, “2016-01-01T12:00:00Z”, “2016-01”. Four digits, a dash and a digit is enough to tell a date from a name and is what the data written by every tool in this repository looks like. Anything else is a name: a chart that read “Q1 2016” as an instant would put every quarter on the same tick and say nothing about it.

VlChartMark

One mark and the channels it reads. Every setter answers the mark, so a mark is written as one sentence:

chart.bar().x("region").y("sales").aggregate("sum")

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("y") moves the cursor back to a channel already set.

Call	Gives	What it is for
`mark.note(message)`	`void`
`mark.channel(name field)`	`VlChartMark`	— channels ———————————————————— Every one of these names a COLUMN.
`mark.x(field)`	`VlChartMark`
`mark.y(field)`	`VlChartMark`
`mark.x2(field)`	`VlChartMark`
`mark.y2(field)`	`VlChartMark`
`mark.color(field)`	`VlChartMark`
`mark.fill(field)`	`VlChartMark`
`mark.stroke(field)`	`VlChartMark`
`mark.size(field)`	`VlChartMark`
`mark.shape(field)`	`VlChartMark`
`mark.opacity(field)`	`VlChartMark`
`mark.theta(field)`	`VlChartMark`
`mark.radius(field)`	`VlChartMark`
`mark.detail(field)`	`VlChartMark`
`mark.text(field)`	`VlChartMark`
`mark.order(field)`	`VlChartMark`
`mark.column(field)`	`VlChartMark`
`mark.row(field)`	`VlChartMark`
`mark.xOffset(field)`	`VlChartMark`	What separates the bars of a grouped bar chart, in the direction the category axis runs.
`mark.yOffset(field)`	`VlChartMark`
`mark.count(channel)`	`VlChartMark`	A count has no column to read: it is one number per group.
`mark.valueNumber(channel value)`	`VlChartMark`	A channel set to a constant rather than to a column.
`mark.valueString(channel value)`	`VlChartMark`
`mark.encodeJson(channel definition)`	`VlChartMark`	The whole channel, written out, for whatever this API does not cover.
`mark.on(channel)`	`VlChartMark`	— the channel most recently named ———————————––
`mark.cursorChannel()`	`VlJson`
`mark.setOnCursor(key value)`	`VlChartMark`
`mark.aggregate(op)`	`VlChartMark`
`mark.bin()`	`VlChartMark`
`mark.maxBins(count)`	`VlChartMark`	How many bins at most.
`mark.timeUnit(unit)`	`VlChartMark`
`mark.type(kind)`	`VlChartMark`	quantitative \| nominal \| ordinal \| temporal, when the data cannot say — a column of years is numbers and is usually a category.
`mark.title(label)`	`VlChartMark`
`mark.format(pattern)`	`VlChartMark`
`mark.stack(how)`	`VlChartMark`	“zero” \| “normalize” \| “center”, or nothing stacked at all.
`mark.noStack()`	`VlChartMark`
`mark.sortBy(field)`	`VlChartMark`	The order a discrete scale runs in.
`mark.keepOrder()`	`VlChartMark`
`mark.scaleJson(scale)`	`VlChartMark`
`mark.scaleType(kind)`	`VlChartMark`
`mark.scheme(name)`	`VlChartMark`
`mark.noLegend()`	`VlChartMark`
`mark.noAxis()`	`VlChartMark`
`mark.axisOrient(side)`	`VlChartMark`	Which side of the plot this channel’s axis stands on — “left”, “right”, “top”, “bottom”.
`mark.axisJson(axis)`	`VlChartMark`
`mark.propNumber(key value)`	`VlChartMark`	— properties of the mark itself —————————————
`mark.propString(key value)`	`VlChartMark`
`mark.propFlag(key value)`	`VlChartMark`
`mark.filled(value)`	`VlChartMark`
`mark.markSize(value)`	`VlChartMark`
`mark.markColor(value)`	`VlChartMark`
`mark.markOpacity(value)`	`VlChartMark`
`mark.interpolate(kind)`	`VlChartMark`	“monotone”, “step-after”, “basis” … — how a line joins its points.
`mark.withPoints(value)`	`VlChartMark`	A line that shows the points it was drawn through.
`mark.innerRadius(value)`	`VlChartMark`
`mark.cornerRadius(value)`	`VlChartMark`
`mark.tooltip(value)`	`VlChartMark`	`tooltip(true)` shows every column the mark encodes.
`mark.tooltipField(field)`	`VlChartMark`
`mark.tooltipFields(fields)`	`VlChartMark`
`mark.thickness(value)`	`VlChartMark`	How thick a tick is drawn, across its band.
`mark.strokeWidth(value)`	`VlChartMark`
`mark.orient(value)`	`VlChartMark`	“horizontal” \| “vertical” — which way a tick lies, or which way a bar that has only one position channel runs.
`mark.extent(value)`	`VlChartMark`	What an interval is computed from: “stderr” \| “stdev” \| “ci” \| “iqr”.
`mark.chart()`	`VlChart`	Back to the chart, when the next thing to say is about the view.

`mark.channel(name field)`

— channels ———————————————————— Every one of these names a COLUMN. A constant goes through valueNumber / 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.

`mark.xOffset(field)`

What separates the bars of a grouped bar chart, in the direction the category axis runs.

`mark.encodeJson(channel definition)`

The whole channel, written out, for whatever this API does not cover. Vega-Lite is larger than any fluent surface over it, and an escape hatch that lands in the same specification is better than a wrapper that has to grow a method before anyone can draw anything.

`mark.maxBins(count)`

How many bins at most. bin and maxbins are the two forms the compiler carries; a bin written any other way is refused BY NAME when it is compiled, which is where a refusal belongs — this layer would have to keep its own list of what the layer below supports, and a list like that is wrong the first time the layer below grows.

`mark.type(kind)`

quantitative | nominal | ordinal | temporal, when the data cannot say — a column of years is numbers and is usually a category.

`mark.sortBy(field)`

The order a discrete scale runs in. sortBy names a column; keepOrder is the one every spreadsheet wants — the order the rows arrived in, rather than alphabetical.

`mark.axisOrient(side)`

Which side of the plot this channel’s axis stands on — “left”, “right”, “top”, “bottom”. A Pareto chart’s cumulative line is measured up the right-hand side, which is the whole point of drawing it there.

`mark.tooltip(value)`

tooltip(true) shows every column the mark encodes. The two below say which columns instead: one field, or a list of them in the order they should be read. A tooltip is also what the mark’s description says, so what a reader is shown by pointing and what they are told by listening stay the same sentence.

`mark.thickness(value)`

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.

`mark.orient(value)`

“horizontal” | “vertical” — which way a tick lies, or which way a bar that has only one position channel runs.

VlChart

Call	Gives	What it is for
`VlChart.create(data)`	`VlChart`
`chart.mark(markType)`	`VlChartMark`	— marks —————————————————————
`chart.bar()`	`VlChartMark`
`chart.line()`	`VlChartMark`
`chart.area()`	`VlChartMark`
`chart.point()`	`VlChartMark`
`chart.circle()`	`VlChartMark`
`chart.square()`	`VlChartMark`
`chart.tick()`	`VlChartMark`
`chart.rule()`	`VlChartMark`
`chart.rect()`	`VlChartMark`
`chart.arc()`	`VlChartMark`
`chart.label()`	`VlChartMark`
`chart.boxplot()`	`VlChartMark`
`chart.errorbar()`	`VlChartMark`	The two composite marks: an interval computed from the rows rather than read off them.
`chart.errorband()`	`VlChartMark`
`chart.trail()`	`VlChartMark`	A line whose width says something: a trail thickens with its `size`.
`chart.image()`	`VlChartMark`
`chart.geoshape()`	`VlChartMark`	A map: the shapes come from the data and the projection places them.
`chart.latest()`	`VlChartMark`	The mark added last, for a caller that built one and let go of it.
`chart.channel(name field)`	`VlChart`	— channels shared by every mark —————————————
`chart.x(field)`	`VlChart`
`chart.y(field)`	`VlChart`
`chart.color(field)`	`VlChart`
`chart.detail(field)`	`VlChart`
`chart.encodeJson(channel definition)`	`VlChart`
`chart.on(channel)`	`VlChart`
`chart.setOnCursor(key value)`	`VlChart`
`chart.type(kind)`	`VlChart`
`chart.title(label)`	`VlChart`
`chart.timeUnit(unit)`	`VlChart`
`chart.keepOrder()`	`VlChart`
`chart.size(width height)`	`VlChart`	— the view itself —————————————————–
`chart.width(value)`	`VlChart`
`chart.height(value)`	`VlChart`
`chart.heading(text)`	`VlChart`
`chart.background(colour)`	`VlChart`
`chart.propJson(key value)`	`VlChart`
`chart.configJson(config)`	`VlChart`
`chart.filter(expression)`	`VlChart`	— transforms ––––––––––––––––––––––––––––– Only the two the compiler carries.
`chart.calculate(expression as)`	`VlChart`
`chart.transformJson(transform)`	`VlChart`
`chart.independent(channel)`	`VlChart`	Two marks measuring different things up the same side of the plot must not share a scale: `chart.independent("y")` 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.
`chart.error(message)`	`void`	Said once.
`VlChart.copyOf(v)`	`VlJson`	— emitting the specification —————————————— A deep copy, because a view’s channel is inherited by every mark and each copy then has its own type filled in.
`chart.mergedEncoding(m)`	`VlJson`	The view’s channels, then the mark’s own on top of them.
`chart.resolveTypes(encoding)`	`void`	What a channel is, when the channel did not say.
`chart.inferType(ch)`	`string`
`VlChart.markValue(m)`	`VlJson`	A mark with no properties of its own is written as the string it is — `"mark": "bar"` — because that is what a person writes and what every golden file in this repository holds.
`chart.toSpec()`	`VlJson`	The whole thing: a Vega-Lite specification, ready for VlCompile.
`chart.toText()`	`string`

`chart.errorbar()`

The two composite marks: an interval computed from the rows rather than read off them. extent decides what the interval IS — “stderr” (the default), “stdev”, “ci” or “iqr”.

`chart.latest()`

The mark added last, for a caller that built one and let go of it. A chart with no marks answers a mark that belongs to nothing rather than quietly adding one: a point nobody asked for would draw.

`chart.filter(expression)`

— transforms ––––––––––––––––––––––––––––– Only the two the compiler carries. Anything else is refused by name at compile time rather than dropped here, which is the same answer arriving from the layer that knows.

`chart.independent(channel)`

Two marks measuring different things up the same side of the plot must not share a scale: chart.independent("y") 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.

`chart.error(message)`

Said once. toSpec may be called more than once — a caller that writes the specification out and then hands it on calls it twice — and the same missing column reported twice reads as two mistakes.

`VlChart.copyOf(v)`

— emitting the specification —————————————— A deep copy, because a view’s channel is inherited by every mark and each copy then has its own type filled in. Sharing one object would make two layers the same object, and a change to one of them a change to both.

`chart.resolveTypes(encoding)`

What a channel is, when the channel did not say. This is the whole of the Observable Plot ergonomics: a caller writes .x("date") and the data decides whether that is an instant or a name.

`VlChart.markValue(m)`

A mark with no properties of its own is written as the string it is — "mark": "bar" — because that is what a person writes and what every golden file in this repository holds.

The two programs below call this API in the page. chart is a compiled VlChart. Edit the JavaScript and press Run. The drawing is the SVG this runtime produced.

chart.bar — sales by regionCtrl+Enter runs. The drawing is the SVG this runtime produced.Open in the playground

chart.size(320, 200);
chart.heading("Sales by region");
const bars = chart.bar();
bars.x("region").keepOrder();
bars.y("sales").aggregate("sum").title("sales");

chart.area and chart.line — one encoding, two marksCtrl+Enter runs. The drawing is the SVG this runtime produced.Open in the playground

chart.size(320, 190);
chart.x("quarter").y("sales").color("region");
chart.area().markOpacity(0.35);
chart.line();

VlChartExamples

The examples the doc blocks above name.

These are ordinary functions: they are compiled and type-checked with the rest of the file, so a signature change breaks the build rather than the documentation. They are left OUT of the emitted code — -keep-examples puts them back — and each doc comment carries the body rendered in its own target’s syntax, so a Kotlin reader is shown Kotlin.

Call	Gives	What it is for
`VlChartExamples.datasetExample()`	`void`
`VlChartExamples.chartQuickExample()`	`void`
`VlChartExamples.markSentenceExample()`	`void`
`VlChartExamples.sharedChannelExample()`	`void`

Source

gallery/vela/src/VlChart.rgr

Licence: AGPL-3.0-or-later. This page quotes the comments in those files.

Licence: AGPL-3.0-or-later · commit f323fd4 · Ranger language documentation (MIT)