Edit on GitHub

The @vlplot command

The @vlplot macro is the main method to create Vega-Lite plots from Julia. The macro accepts arguments that look almost identical to the original Vega-Lite JSON syntax. It should therefore be very easy to take any given Vega-Lite JSON example and translate it into a corresponding @vlplot macro call. The macro also provides a number of shorthands that make it easy to create very compact plot specifications. This section will first review the difference between the original JSON Vega-Lite syntax and the @vlplot macro, and then discuss the various shorthands that users will typically use.

JSON syntax vs @vlplot macro

A very simple Vega-Lite JSON specification looks like this:

{
  "data": {
    "values": [
      {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
      {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
      {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "ordinal"},
    "y": {"field": "b", "type": "quantitative"}
  }
}

This can be directly translated into the following @vlplot macro call:

using VegaLite

@vlplot(
    data={
        values=[
            {a="A",b=28},{a="B",b=55},{a="C",b=43},
            {a="D",b=91},{a="E",b=81},{a="F",b=53},
            {a="G",b=19},{a="H",b=87},{a="I",b=52}
        ]
    },
    mark="bar",
    encoding={
        x={field="a", type="ordinal"},
        y={field="b", type="quantitative"}
    }
)

We had to make the following adjustments to the original JSON specification:

  1. The outer pair of {} brackets was removed, the parenthesis () of the macro call instead deliminate the beginning and end of the specification.
  2. The quotation marks " around keys like mark are removed.
  3. The JSON key-value separator : was replaced with =.
  4. Any null value in the JSON specification should be replaced with nothing in the @vlplot call.

These four rules should be sufficient to translate any valid JSON Vega-Lite specification into a corresponding @vlplot macro call.

Symbols instead of Strings

A first shorthand provided by the @vlplot macro is that you can use a Symbol on the right hand side of any key-value pair instead of a String. For example, instead of writing mark="bar", you can write mark=:bar.

The following example demonstrates this in the context of a full plotting example:

data |>
@vlplot(
    mark=:point, # Note how we use :point instead of "point" here
    encoding={
        x={
            field=:a, # Note how we use :a instead of "a" here
            type=:ordinal # Note how we use :ordinal instead of "ordinal" here
        },
        y={
            field=:b, # Note how we use :b instead of "b" here
            type=:quantitative # Note how we use :quantitative instead of "quantitative" here
        }
    }
)

Shorthand string syntax for encodings

VegaLite.jl provides a similar string shorthand syntax for encodings as Altair (the Python wrapper around Vega-Lite).

Almost any channel encoding in a specification will have the keys field and type, as in x={field=:a, type=:ordinal}. Because these patterns are so common, we provide a shorthand string syntax for this case. Using the shorthand one can write the channel encoding as x={"a:o"}. These string shorthands have to appear as the first positional argument inside the curly brackets {} for the encoding channel. The pattern inside the string is that one specifies the name of the field before the :, and then the first letter of the type of encoding (o for ordinal, q for quantitative etc.).

The string shorthand also extends to the timeUnit and aggregate key in encodings. Aggregation functions and time units can be specified using a function call syntax inside the string shorthand. For example, x={"mean(foo)"} is equivalent to x={field=:foo, aggregate=:mean, type=:quantitative} (note that we don't have to specify the type explicitly when we use aggregations, the default assumption is that the result of an aggregation is quantitative). An example that uses the shorthand for a time unit is x={"year(foo):t"}, which is equivalent to x={field=:foo, timeUnit=:year, type=:quantitative}. For aggregations that don't require a field name (e.g. the count aggregation), you can just write x="count()".

String shorthands can be combined with any other attributes. For example, the following example shows how one can specify an axis title and still use the string shorthand notation:

x={"foo:q", axis={title="some title"}}

In cases where you don't want to specify any other attributes than what can be expressed in the string shorthand you don't have to use the surrounding curly brackets {} for the encoding: x="foo:q" is equivalent to x={field=:foo, type=:quantitative}. If you only want to specify the field and not even the type, you can resort to using a Symbol: x=:foo is also a valid encoding.

The shorthand string syntax allows us to write the specification of the plot from the previous section in this much more concise format:

data |>
@vlplot(
    mark=:point,
    encoding={
        x="a:o",
        y=:b
    }
)

Shorthands for the encoding element

There are two shorthands for the encoding element in a plot specification.

The first is to simply write enc instead of encoding. For example, the previous specification can be written as

data |>
@vlplot(
    mark=:point,
    enc={
        x="a:o",
        y=:b
    }
)

An even shorter notation is to just leave the level of the encoding element away and place the channel encodings directly into the top level specification. With that option you would write the previous example as:

data |>
@vlplot(mark=:point, x="a:o", y=:b)

Mark shorthands

There are two shorthands for the mark attribute in a specification. The first option is to use the first positional argument in a @vlplot call to specify the mark type. This only works if you don't want to specify any other mark attributes. For example, the previous plot can now be written as

data |> @vlplot(:point, x="a:o", y=:b)

If you want to specify more mark attributes, you can reintroduce curly brackets {}, and then specify the type of the mark as the first positional argument inside the mark block. For example, the following code specifies that the mark color should be red, in addition to picking points as the mark type:

data |>
@vlplot(
    mark={:point, color=:red},
    x="a:o",
    y=:b
)

x and y encoding channel as positional arguments

For the x and y encoding channel only, you can specify their values as the second and third positional element at the root level of the @vlplot call instead of using named arguments. In particular, you can write @vlplot(:point, :colA, :colB) instead of @vlplot(:point, x=:colA, y=:colB) or @vlplot(:point, :colA) instead of @vlplot(:point, x=:colA).