Convert a list of Vega-Lite specifications into a single JSON object that may be passed to Vega-Lite for graphics generation. Commonly these will include at least data, mark and encoding specifications.

While simple functions like bar may be provided directly, it is usually clearer to label more complex functions such as encodings with separate expressions.

Specifications can be built up by chaining functions such as dataColumn or position. Functional composition using the << operator allows this to be done compactly:

let
    data =
        dataFromColumns []
            << dataColumn "a" (strs [ "C", "C", "D", "E" ])
            << dataColumn "b" (nums [ 2, 7, 1, 2 ])


    enc =
        encoding
            << position X [ pName "a", pNominal ]
            << position Y [ pName "b", pQuant, pAggregate opMean ]
in
toVegaLite [ data [], enc [], bar [] ]

Top-level Vega-Lite properties. These are the ones that define the core of the visualization grammar. All VLProperties are created by functions in seven broad groups.

Data properties relate to the input data to be visualized. Generated by dataFromColumns, dataFromRows, dataFromUrl, dataFromSource, dataFromJson, dataSequence, sphere and graticule.

Transform properties indicate that some transformation of input data should be applied before encoding them visually. Generated by transform and projection they can include data transformations such as filter, binAs and calculateAs and geo transformations of longitude, latitude coordinates used by marks such as geoshape, point and line.

Mark functions specify the graphical symbols used to visualize data items. Generated by functions such as circle, bar and line.

Encoding properties specify which data elements are mapped to which mark characteristics (known as channels). Generated by encoding they include encodings such as position, color, size, shape, text, hyperlink and order.

Composition properties allow visualization views to be combined to form more complex visualizations. Generated by layer, repeatFlow, repeat, facetFlow, facet, concat, columns, hConcat, vConcat, specification and resolve.

Interaction properties allow clicking, dragging and other interactions generated via a GUI or data stream to influence the visualization. Generated by selection.

Supplementary and configuration properties provide a means to add metadata and styling to one or more visualizations. Generated by name, title, description, background, width, height, widthStep, heightStep, padding, autosize, viewBackground and configure.

Part or all of a Vega-Lite specification. Specs are usually nested and can range from a single Boolean value up to the full visualization specification.

A named Vega-Lite specification, usually generated by an elm-vega function. You shouldn't need to create LabelledSpec tuples directly, but are useful for type annotations.

Combines a list of labelled specifications that may be passed to JavaScript for rendering. Useful when you wish to create a single page with multiple visualizations.

combineSpecs
    [ ( "vis1", myFirstVis )
    , ( "vis2", mySecondVis )
    , ( "vis3", myOtherVis )
    ]

Declare a data source from a url. The URL can be a local path on a web server or an external (CORS) URL. A list of field formatting instructions can be provided as the second parameter or an empty list to use the default formatting.

bikeData =
    dataFromUrl "./data/bicycleHires.csv"
        [ parse [ ( "numHires", foNum ), ( "avHireTime", foNum ) ] ]


popData =
    dataFromUrl "https://vega.github.io/vega-lite/data/population.json" []

Declare a data source from a list of column values. Each column should contain values of the same type, but columns each with a different type are permitted. If columns do not contain the same number of items the dataset will be truncated to the length of the shortest, so beware of inadvertently removing data rows at the 'bottom' of a table.

A list of field formatting instructions can be provided as the first parameter or an empty list to use the default formatting. Simple numbers and strings do not normally need formatting, but it is good practice to explicitly declare date-time formats as default date-time formats can vary between browsers.

The columns are most easily generated with dataColumn:

data =
    dataFromColumns [ parse [ ( "Year", foDate "%Y" ) ] ]
        << dataColumn "Animal" (strs [ "Fish", "Dog", "Cat" ])
        << dataColumn "Age" (nums [ 28, 12, 6 ])
        << dataColumn "Year" (strs [ "2010", "2014", "2015" ])

For more complex inline data tables, such as mixtures of arrays and objects, consider using dataFromJson.

Create a column of data. A column has a name and a list of values.

Declare a data source from a list of row values. Each row should contain a list of tuples in the form (column name, value). Each column can have a value of a different type but you must ensure that values are of the same type as others in the same column. A list of field formatting instructions can be provided as the first parameter or an empty list to use the default formatting. Rows are most easily generated with dataRow.

data =
    dataFromRows [ parse [ ( "Year", foDate "%Y" ) ] ]
        << dataRow [ ( "Animal", str "Fish" ), ( "Age", num 28 ), ( "Year", str "2010" ) ]
        << dataRow [ ( "Animal", str "Dog" ), ( "Age", num 12 ), ( "Year", str "2014" ) ]
        << dataRow [ ( "Animal", str "Cat" ), ( "Age", num 6 ), ( "Year", str "2015" ) ]

Generally, adding data by column is more efficient and less error-prone. For more complex inline data tables, such as mixtures of arrays and objects, consider using dataFromJson.

Create a row of data. A row comprises a list of (columnName, value) pairs.

Declare a data source from a json specification. The most likely use-case is creating geojson objects with geometry, geometryCollection and geoFeatureCollection. For example,

let
    geojson =
        geometry (geoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []
in
toVegaLite
    [ width 200
    , height 200
    , dataFromJson geojson []
    , projection [ prType orthographic ]
    , geoshape []
    ]

For more general cases of json creation such as data tables that mix arrays and objects, consider using with Elm's Json.Encode. For example,

row title ranges =
    Json.Encode.object
        [ ( "title", Json.Encode.string title )
        , ( "ranges", Json.Encode.list Json.Encode.float ranges )
        ]


data =
    dataFromJson
        (Json.Encode.list identity
            [ row "Revenue" [ 150, 225, 300 ]
            , row "Profit" [ 20, 25, 30 ]
            , row "Order size" [ 350, 500, 600 ]
            , row "New customers" [ 1400, 2000, 2500 ]
            , row "Satisfaction" [ 3.5, 4.25, 5 ]
            ]
        )

Declare data from a named source. The source may be from named datasets within a specification or one created via the Vega View API. A list of field formatting instructions can be provided as the second parameter or an empty list to use the default formatting.

data = ...
json = ...
enc = ...
toVegaLite
    [ datasets [ ( "myData", data [] ),  ( "myJson", dataFromJson json [] ) ]
    , dataFromSource "myData" []
    , enc []
    , bar []
    ]

Name to give a data source. Useful when a specification needs to reference a data source, such as one generated via an API call.

data =
    dataFromUrl "myData.json" [] |> dataName "myName"

Create a dataset comprising a collection of named Data items. Each data item can be created with normal data generating functions such as dataFromRows or dataFromJson. These can be later referred to using dataFromSource.

import Json.Encode as JE


let
    data =
        dataFromRows []
            << dataRow [ ( "cat", str "a" ), ( "val", num 10 ) ]
            << dataRow [ ( "cat", str "b" ), ( "val", num 18 ) ]
    json =
        JE.list JE.object
            [ [ ( "cat", JE.string "a" ), ( "val", JE.float 120 ) ]
            , [ ( "cat", JE.string "b" ), ( "val", JE.float 180 ) ]
            ]


    enc = ...


in
toVegaLite
    [ datasets [ ( "myData", data [] ),  ( "myJson", dataFromJson json [] ) ]
    , dataFromSource "myData" []
    , bar []
    , enc []
    ]

Ignore the data of a specification's parent when used in a composed spec.

Convenience type annotation label for use with data generation functions.

myRegion : List DataColumn -> Data
myRegion =
    dataFromColumns []
        << dataColumn "easting" (nums [ -3, 4, 4, -3, -3 ])
        << dataColumn "northing" (nums [ 52, 52, 45, 45, 52 ])

A single column of data. Used when generating inline data with dataColumn.

A single row of data. Used when generating inline data with dataRow.

Geometric object to be used in a geoshape. The first parameter is the geometric type, the second an optional list of properties to be associated with the object.

  geojson =
      geometry (geoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []

Geo features to be used in a geoshape specification. Each feature object in this collection can be created with geometry.

geojson =
    geoFeatureCollection
        [ geometry (geoPolygon [ [ ( -3, 59 ), ( -3, 52 ), ( 4, 52 ), ( -3, 59 ) ] ])
            [ ( "myRegionName", str "Northern region" ) ]
        , geometry (geoPolygon [ [ ( -3, 52 ), ( 4, 52 ), ( 4, 45 ), ( -3, 52 ) ] ])
            [ ( "myRegionName", str "Southern region" ) ]
        ]

Geometry objects to be used in a geoshape specification. Each geometry object can be created with geometry.

geojson =
    geometryCollection
        [ geometry (geoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []
        , geometry (geoPoint -3.5 55.5) []
        ]

Point geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry point type.

Multi-point geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry multi-point type.

Line geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry line type.

Multi-line geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry multi-line type.

Polygon geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry polygon type.

Multi-polygon geometry for programmatically creating GeoShapes. Equivalent to the GeoJson geometry multi-polygon type.

Generate a sequence of numbers as a data source between the value of the first parameter (inclusive) and the second (exclusive) in steps of the value of the third. The resulting sequence will have the name data.

myData =
    dataSequence 0 6.28 0.1

To give the sequence an alternative name use dataSequenceAs

Generate a sequence of numbers as a data source between the value of the first parameter (inclusive) and the second (exclusive) in steps of the value of the third. The resulting sequence will have the name provided as the fourth parameter.

myData =
    dataSequenceAs 0 6.28 0.1 "x"

Generate a data source that is a sphere for bounding global geographic data. The sphere will be subject to whatever projection is specified for the view.

toVegaLite
    [ sphere
    , projection [ prType orthographic ]
    , geoshape [ maFill "aliceblue" ]
    ]

Generate a grid of lines of longitude (meridians) and latitude (parallels). The parameter can be used to specify the number and extent of lines, or to use default values, provide an empty list.

let
    proj =
        projection [ prType orthographic ]


    sphereSpec =
        asSpec [ sphere, geoshape [ maFill "aliceblue" ] ]


    gratSpec =
        asSpec
            [ graticule [ grStep ( 5, 5 ) ]
            , geoshape [ maFilled False, maStrokeWidth 0.3 ]
            ]
in
toVegaLite [ proj, layer [ sphereSpec, gratSpec ] ]

Set the step sizes between all graticule lines. The parameter is a (longitude,latitude) pair defining the EW and NS graticule intervals respectively.

Set the step sizes between major graticule lines. By default, major graticule lines extend to both poles, but minor lines stop at ±80 degrees latitude. The parameter is a (longitude,latitude) pair defining the EW and NS graticule intervals respectively.

Set the step sizes between minor graticule lines. By default, major graticule lines extend to both poles, but minor lines stop at ±80 degrees latitude. The parameter is a (longitude,latitude) pair defining the EW and NS graticule intervals respectively.

Set the extent of both major and minor graticule lines. The first parameter is a (longitude,latitude) pair defining the minimum extent, the second parameter the maximum extent.

Set the extent of major graticule lines. The first parameter is a (longitude,latitude) pair defining the minimum extent, the second parameter the maximum extent.

Set the extent of minor graticule lines. The first parameter is a (longitude,latitude) pair defining the minimum extent, the second parameter the maximum extent.

The precision of the graticule in degrees. If unspecified, the default of 2.5 degrees is used. Smaller values provide a less stepped appearance of curved lines but take longer to render.

CSV data file format (only necessary if the file extension does not indicate the type).

TSV data file format (only necessary if the file extension does not indicate the type).

Delimited file format (DSV) with a given separator.

Apache arrow data file format.

data =
    dataFromUrl "https://gicentre.github.io/data/scrabble.arrow" [ arrow ]

Property to be extracted from some JSON when it has some surrounding structure. e.g., specifying the property values.features is equivalent to retrieving json.values.features from a JSON object with a custom delimiter.

A topoJSON feature format containing an object with the given name. The name of the object can be found by inspecting the topoJSON file and searching for the value associated with the objects key.

geodata =
    dataFromUrl "city.json" [ topojsonFeature "boroughs" ]

A topoJSON mesh format containing an object with the given name. Unlike topojsonFeature, the corresponding geo data are returned as a single unified mesh, not as individual GeoJSON features.

Parsing rules when processing some data text, specified as a list of tuples in the form (fieldname, datatype). Useful when automatic type inference needs to be overridden, for example when converting integers representing years into dates and strings into numbers:

data =
    dataFromUrl "myDataFile.csv"
        [ parse [ ( "year", foDate "%Y" ), ( "y", foNum ) ] ]

Indicate numeric data type to be parsed when reading input data.

Indicate Boolean data type to be parsed when reading input data.

Date format for parsing input data using D3's formatting specifiers or left as an empty string for default formatting.

Similar to foDate but for UTC format dates.

Create a single transform from a list of transformation specifications. The order of transformations can be important, e.g. labels created with calculateAs, timeUnitAs and binAs that are used in other transformations. Using the functional composition pipeline idiom (as example below) allows you to provide the transformations in the order intended in a clear manner.

trans =
    transform
        << filter (fiExpr "datum.year == 2010")
        << calculateAs "datum.sex == 2 ? 'Female' : 'Male'" "gender"

Map projection used for geospatial coordinates.

proj =
    projection [ prType equirectangular, prRotate -156 0 0 ]

Type of global map projection.

Projection’s clipping circle radius to the specified angle in degrees. A value of Nothing will switch to antimeridian cutting rather than small-circle clipping.

Projection’s viewport clip extent to the specified bounds in pixels.

Projection’s center as longitude and latitude in degrees.

A projection’s zoom scale, which if set, overrides automatic scaling of a geo feature to fit within the viewing area.

A projection’s panning translation, which if set, overrides automatic positioning of a geo feature to fit within the viewing area.

A projection’s three-axis rotation angle. This should be in order lambda phi gamma specifying the rotation angles in degrees about each spherical axis.

Threshold for the projection’s adaptive resampling in pixels. Corresponds to the Douglas–Peucker distance. If precision is not specified, the projection’s current resampling precision of 0.707 is used.

'Hammer' map projection coefficient.

'Satellite' map projection distance.

Bottomley map projection fraction.

Number of lobes in lobed map projections such as the 'Berghaus star'.

Parallel for map projections such as the 'Armadillo'.

Radius value for map projections such as the 'Gingery'.

Ratio value for map projections such as the 'Hill'.

Reflect the x-coordinates after performing an identity projection. This creates a left-right mirror image of the geoshape marks when subject to an identityProjection.

Reflect the y-coordinates after performing an identity projection. This creates a top-bottom mirror image of the geoshape marks when subject to an identityProjection.

Spacing value for map projections such as the 'Lagrange'.

'Satellite' map projection tilt.

An Albers equal-area conic map projection.

An Albers USA map projection that combines continental USA with Alaska and Hawaii. Unlike other projection types, this remains unaffected by prRotate.

An azimuthal equal area map projection.

An azimuthal equidistant map projection.

A conformal conic map projection.

An equal area conic map projection.

An equidistant conic map projection.

An Equal Earth map projection that provides a reasonable shape approximation while retaining relative areas.

An equirectangular map projection that maps longitude to x and latitude to y. While showing less area distortion towards the poles than the default mercator projection, it is neither equal-area nor conformal.

A gnomonic map projection.

An 'identity' projection where longitude is projected directly to the x position and latitude to the y position. Can also reflect either of the coordinates by specifying prReflectX / prReflectY in the list of projection properties.

A Mercator map projection. This is the default projection of longitude,latitude values if no projection is set explicitly. It preserves shape (local angle) and lines of equal angular bearing remain parallel straight lines. But area is significantly enlarged towards the poles.

An orthographic map projection.

A stereographic map projection.

A transverse Mercator map projection.

Custom projection type. Additional custom projections from d3 can be defined via the Vega API and called from with this function where the parameter is the name of the D3 projection to use (e.g. customProjection "winkel3").

Indicate no clipping to be applied.

Clipping rectangle in pixel units. The four parameters are respectively 'left', 'top', 'right' and 'bottom' of the rectangular clipping bounds.

Aggregation transformations to be used when encoding channels. Useful when for applying the same transformation to a number of channels without defining it each time. The first parameter is a list of the named aggregation operations to apply. The second is a list of 'group by' fields.

trans =
    transform
        << aggregate
            [ opAs opMin "people" "lowerBound", opAs opMax "people" "upperBound" ]
            [ "age" ]

Aggregation transformations to be used when encoding channels. Unlike aggregate, this transformation joins the results to the input data. Can be helpful for creating derived values that combine raw data with some aggregate measure, such as percentages of group totals. The first parameter is a list of the named aggregation operations to apply. The second is a list of possible window aggregate field properties, such as a field to group by when aggregating. The third parameter is a list of transformations to which this is added.

transform
    << joinAggregate [ opAs opMean "rating" "avYearRating" ]
        [ wiGroupBy [ "year" ] ]
    << filter (fiExpr "(datum.rating - datum.avYearRating) > 3")

For details, see the Vega-Lite join aggregate documentation

Aggregation operation. The first parameter is the operation to use; the second the name of the field in which to apply it and the third the name to be given to this transformation.

trans =
    transform
        << aggregate
            [ opAs opMin "people" "lowerBound"
            , opAs opMax "people" "upperBound"
            ]
            [ "age" ]

If the operation is Count, it does not apply to any specific field, so the second parameter can be an empty string.

Create a new data field based on the given temporal binning. Unlike the direct encoding binning, this transformation is named and so can be referred to in multiple encodings. The first parameter is the width of each temporal bin, the second is the field to bin and the third is name to give the newly binned field.

An input data object containing the minimum field value to be used in an aggregation operation. If supplied as part of an encoding aggregation, the parameter should be Just the name of the field to maximise. For example the following would find the production budget for the maximum US grossing film in each genre.

encoding
    << position X
        [ pName "Production_Budget"
        , pQuant
        , pAggregate (opArgMax (Just "US_Gross"))
        ]
    << position Y [ pName "Major_Genre", pNominal ]

If supplied as part of a transform, the parameter should be Nothing as the field is specified in the aggregate parameter. For example,

trans =
    transform
        << aggregate
            [ opAs (opArgMax Nothing) "US_Gross" "amUSGross" ]
            [ "Major_Genre" ]

An input data object containing the minimum field value to be used in an aggregation operation.

Lower 95% confidence interval to be used in an aggregation operation.

Upper 95% confidence interval to be used in an aggregation operation.

Total count of data objects to be used in an aggregation operation.

Count of distinct data objects to be used in an aggregation operation.

Maximum field value to be used in an aggregation operation.

Mean value to be used in an aggregation operation.

Median field value to be used in an aggregation operation.

Minimum field value to be used in an aggregation operation.

Count of null or undefined field value to be used in an aggregation operation.

Lower quartile boundary of field values to be used in an aggregation operation.

Upper quartile boundary of field values to be used in an aggregation operation.

Standard error of field values to be used in an aggregation operation.

Sample standard deviation of field values to be used in an aggregation operation.

Population standard deviation of field values to be used in an aggregation operation.

Sum of field values to be used in an aggregation operation.

Count of values that are not null, undefined or NaN to be used in an aggregation operation.

Sample variance of field value to be used in an aggregation operation.

Population variance of field value to be used in an aggregation operation.

Binning transformation that may be referenced in other transformations or encodings. The first parameter is a list of customisation optiona (biBase, biDivide etc.) or an empty list to use the default binning. Sthe second is the field to bin and the third the name to give the output binned data.

trans =
    transform
        << binAs [ biMaxBins 3 ] "IMDB_Rating" "ratingGroup"

Note that usually, direct binning within an encoding is preferred over this form of bin transformation.

Value in the binned domain at which to anchor the binning. Boundaries are possibly shifted to ensure they align with the anchor value.

Number base to use for automatic bin determination (default is base 10).

Scale factors indicating allowable subdivisions for binning. The default value is [5, 2], which indicates that for base 10 numbers (the default base), binning will consider dividing bin sizes by 5 and/or 2.

Desired range of bin values when binning a collection of values. The first and second parameters indicate the minimum and maximum range values. To base a binning extent on an interactive selection, use biSelectionExtent instead.

Set the desired range of bin values based on an interactive selection. The parameter should be the name of an interval selection that defines the extent.

For example,

sel =
    selection
        << select "brush" seInterval [ seEncodings [ chX ] ]


enc =
    encoding
        << position X
            [ pName "temperature"
            , pBin [ biSelectionExtent "brush" ]
            , pQuant
            ]

Maximum number of bins when binning a collection of values.

Step size between bins when binning a collection of values.

Whether or not binning boundaries use human-friendly values such as multiples of ten.

Step size between bins when binning a collection of values.

Allowable step sizes between bins when binning a collection of values.

Apply a stack transform for positioning multiple values. This is an alternative to specifying stacking directly when encoding position. First parameter is the field to be stacked; the second the fields to group by; the third and fourth are the names to give the output field names; the fifth lists the optional offset and sort properties.

Stack offset when applying a stack transformation.

Rescale a stacked layout to use a common height while preserving relative size of stacked quantities.

Offset a stacked layout using a central stack baseline.

Offset a stacked layout using a baseline at the foot of a stack.

Do not stack marks (produces a layered plot).

Ordering within a stack when applying a stack transformation.

Indicate that the given field should be sorted in ascending order.

Indicate that the given field should be sorted in descending order.

Generate a new data field based on some calculations from existing values and fields. The first parameter is an expression representing the calculation and the second is the name to give the newly calculated field.

trans =
    transform << calculateAs "datum.sex == 2 ? 'F' : 'M'" "gender"

Apply a filter to a channel or field that specifies which values will 'pass through' for encoding. A filter can an expression such as,

trans =
    transform << filter (fiExpr "datum.y < 50")

noting that to refer to a particular data value, prefix the field name with datum.. Alternatively a boolean filtering function such as fiOneOf or fiLessThan can be supplied,

trans =
    transform << filter (fiLessThan "y" (num 50))

Filter a data stream so that only data in a given field equal to the given value are used.

Filter a data stream so that only data in a given field less than the given value are used.

Filter a data stream so that only data in a given field less than or equal to the given value are used.

Filter a data stream so that only data in a given field greater than the given value are used.

Filter a data stream so that only data in a given field greater than or equal to the given value are used.

Filter a data stream so that only data that satisfy the given predicate expression are used.

Convert a filter into a BooleanOp so that it may be used as part of a more complex Boolean composition. For example,

trans =
    transform
        << filter
            (fiCompose
                (and
                    (fiValid "IMDB_Rating" |> fiOp)
                    (fiValid "Rotten_Tomatoes_Rating" |> fiOp)
                )
            )

Combine a data transformation operation with a filter before converting into a Boolean operation. This can be useful when working with dates. For example the following will aggregate a set of dates into years and filter only those years between 2010 and 2017 inclusive. Note the use of fiCompose to convert the Boolean operation back into a Filter.

filter
    (fiRange "date" (dtRange [ dtYear 2010 ] [ dtYear 2017 ])
        |> fiOpTrans (mTimeUnit year)
        |> fiCompose
    )

Build up a filtering predicate through logical composition (and, or etc.). For example, to filter only items selected interactively and that represent ages over 65,

trans =
    transform
        << filter
            (fiCompose
                (and (selected "brush") (expr "datum.age > 65"))
            )

Filter a data stream so that only data in a given field that are within the given interactive selection are used. For example,

sel =
    selection
        << select "myBrush" seInterval [ seEncodings [ chX ] ]


trans =
    transform
        << filter (fiSelection "myBrush")

Filter a data stream so that only data in a given field contained in the given list of values are used.

Filter a data stream so that only data in a given field that are within the given range are used. For example,

filter (fiRange "date" (dtRange [ dtYear 2006 ] [ dtYear 2016 ]))

Filter a data stream so that only valid data (i.e. not null or NaN) in a given field are used.

Minimum-maximum number range to be used in data filtering.

Min max date-time range to be used in data filtering. If either parameter is an empty list, it is assumed to be unbounded.

Map array-valued fields to a set of individual data objects, one per array entry.

Similar to flatten but allows the new output fields to be named (second parameter).

Perform a gather operation to tidy a table. Collapse multiple data fields into two new data fields: key containing the original data field names and value containing the corresponding data values. This performs the same function as 'gather' in the Tidy Elm package and the pivot_longer / gather operation in the R tidyverse . It is the inverse of pivot.

data =
    dataFromColumns []
        << dataColumn "city" (strs [ "Bristol", "Sheffield", "Glasgow" ])
        << dataColumn "temp2017" (nums [ 12, 11, 7 ])
        << dataColumn "temp2018" (nums [ 14, 13, 10 ])


trans =
    transform
        << fold [ "temp2017", "temp2018" ]


enc =
    encoding
        << position X [ pName "key", pNominal ]
        << position Y [ pName "city", pNominal ]
        << size [ mName "value", mQuant ]

Similar to fold but allows the new output key and value fields to be given alternative names.

Perform a pivot operation on a table. Spreads a key-value pair of fields across multiple fields according to the data in the key field. The first two parameters are the key and value fields respectively. The third is a set of customisation options. This performs the same function as 'spread' in the Tidy Elm package and the pivot_wider / spread operation in the R tidyverse. It is the inverse of fold.

data =
    dataFromColumns []
        << dataColumn "city" (strs [ "Bristol", "Bristol", "Sheffield", "Sheffield", "Glasgow", "Glasgow" ])
        << dataColumn "temperature" (nums [ 12, 14, 11, 13, 7, 10 ])
        << dataColumn "year" (nums [ 2017, 2018, 2017, 2018, 2017, 2018 ])


trans =
    transform
        << pivot "year" "temperature" [ piGroupBy [ "city" ] ]


enc =
    encoding
        -- 2017 temperatures for the Bristol, Sheffield and Glasgow
        << position X [ pName "2017", pQuant ]
        << position Y [ pName "city", pNominal ]

The data fields to group by when pivoting. If not specified, a single group containing all data objects will be used.

Maximum number of fields to generate when pivoting. If 0 or unspecified, all fields are pivoted. The pivot names are sorted in ascending order before any limit is applied.

The aggregation to apply to grouped fields during a pivot.

Perform a lookup of named fields between two data sources. This allows you to find values in one data source based on the values in another. The first parameter is the field in the primary data source to act as key, the second is the secondary data source which can be specified with a call to dataFromUrl or other data generating function. The third is the name of the field in the secondary data source to match values with the primary key. The fourth parameter is the list of fields to be stored when the keys match.

For linking data with interactive selections, see lookupSelection.

A common use for lookup is to join geographic and attribute data sources. Below geodata is the primary data source containing borough boundaries and censusData the secondary data source containing attribute data. Both have common data field values identifying a borough (id and borough) that is used to join the data sources:

geoData =
    dataFromUrl "city.json" [ topojsonFeature "boroughs" ]


censusData =
    dataFromUrl "census.csv" []


trans =
    transform
        << lookup "id"
            (censuData [])
            "borough"
            (luFields [ "carOwnership", "numBedrooms" ])

Attach the results of an interactive selection to a primary data source. The first three parameters are the field in the primary data source to look up; the name of the interactive selection; and the name of the field in the selection to link with the primary data field. This is similar to lookup except that the data in a selection are used in place of the secondary data source.

For example:

  sel =
      selection
          << select "mySel" seSingle [ seOn "mouseover", seEncodings [ chX ] ]


  trans =
      transform
          << lookupSelection "country" "mySel" "country"

Names of the fields to be returned from a secondary data source when performing a lookup transformation.

The same as luFields except with a second parameter providing the default value if the lookup fails.

Names of the fields and their aliases to be returned from a secondary data source when performing a lookup transformation. Each tuple should be a name of a field to return followed by the new name to give it. Unlike luAs this allows separate aliases to be given to each matched field.

The same as luFieldsAs except with a second parameter providing the default value if the lookup fails.

Name to give the entire set of fields in a secondary data source when performing a lookup. To refer to individual fields via this name, use dot notiation. For example,

data =
    dataFromUrl "data/flights-airport.csv" []


trans =
    transform
        << lookup "origin"
            (dataFromUrl "data/airports.csv" [])
            "iata"
            (luAs "o")


enc =
    encoding
        << position Longitude [ pName "o.longitude", pQuant ]
        << position Latitude [ pName "o.latitude", pQuant ]

The same as luAs except with a second parameter providing the default value if the lookup fails.

Impute missing data values as a data transform. The first parameter is the data field to process; the second the key field to uniquely identify data objects within a group; the third customisable options.

For example, to impute the missing value of b with the mean of existing b values, when a is 30 and its color group (c) is 1:

let
    data =
        dataFromColumns []
            << dataColumn "a" (nums [ 0, 0, 10, 10, 20, 20, 30 ])
            << dataColumn "b" (nums [ 28, 91, 43, 55, 81, 53, 19 ])
            << dataColumn "c" (nums [ 0, 1, 0, 1, 0, 1, 0 ])


    trans =
        transform
            << impute "b" "a" [ imMethod imMean, imGroupBy [ "c" ] ]


    enc =
        encoding
            << position X [ pName "a", pQuant ]
            << position Y [ pName "b", pQuant ]
            << color [ mName "c", mNominal ]
in
toVegaLite [ data [], trans [], enc [], line [] ]

1d window over which data imputation values are generated. The two parameters should either be Just a number indicating the offset from the current data object, or Nothing to indicate unbounded rows preceding or following the current data object.

Key values to be considered for imputation.

Key values to be considered for imputation as a sequence of numbers between a start (first parameter), to less than an end (second parameter) in steps of the third parameter.

Imputation method to use when replacing values.

Allow imputing of missing values on a per-group basis. For use with the impute transform only and not a channel encoding.

New value to use when imputing with imValue.

Use field value when imputing missing data.

Use mean of values when imputing missing data.

Use median of values when imputing missing data.

Use maximum of values when imputing missing data.

Use maximum of values when imputing missing data.

Randomly sample rows from a data source up to a given maximum. For example, to randomly sample 50 values from a sine curve.

data =
    dataSequenceAs 0 13 0.001 "x"


trans =
    transform
        << calculateAs "sin(datum.x)" "y"
        << sample 50

Apply Kernel Density Estimation to a data stream to generate a new stream of samples of the estimated density. Useful for representing probability distributions and generating continuous distributions from discrete samples.

The data fields to group by when estimating density. If not specified, a single group containing all data objects will be used.

Whether or not density estimates will be cumulative. If unspecified, non-cumulative estimates will be generated.

Whether density estimates should generate counts (true) or probabilities (false). If unspecified, probabilities will be generated.

The bandwidth (standard deviation) of the Gaussian kernal used in KDE estimation. If 0 or unspecified, the bandwidth will be calculated using Scott's method.

The min (first parameter) - max (second parameter) domain from which to sample a distribution for density estimation. If unspecified, the full extent of input values will be sampled.

The minimum number of samples to take from the extent domain when estimating density. Default is 25.

The maximum number of samples to take when estimating density. Default is 200.

The exact number of samples to take from the extent domain when estimating density. Will override dnMinSteps and dnMaxSteps and is useful in conjunction with a fixed extent to ensure consistent sample points for stacked densities.

Name the outputs of a density transform. The first parameter is the name to give the field containing samples, the second the name to give the field containing density estimates. If not specified, the default names value and density will be used.

Generate a loess (locally-estimated scatterplot smoothing) trendline through a pair of data fields. The first parameter is the name of the field representing the dependent variable (commonly mapped to the y-axis), the second is the name of the field representing the independent variable (commonly mapped to the x-axis). The third parameter is a list of optional loess parameters to customise the trend fitting.

The data fields to group by when generating a loess trendline. If not specified, a single group containing all data objects will be used.

The bandwidth scaled between [0,1] to determine the amount of loess smoothing. Default value is 0.3

Name the outputs of a loess transform. The first parameter is the name to give the field containing the smoothed independent variable, the second the name to give the field containing smoothed dependent variable. If not specified, the original input independent and dependent field names are used.

Generate a 2d regression model for smoothing and predicting data. The first parameter is the name of the field representing the dependent variable (commonly mapped to the y-axis), the second is the name of the field representing the independent variable (commonly mapped to the x-axis). The third parameter is a list of optional regression customisation options.

The data fields to group by when generating a regression model. If not specified, a single group containing all data objects will be used.

The type of regression model to use when generating a 2d regression.

The order of a polynomial model to use when generating a 2d regression. Only applies if rgMethod is set to rgPoly.

The min (first parameter) - max (second parameter) domain over which to estimate the dependent variable in a regression. If unspecified, the full extent of input values will be used.

Name the outputs of a regression transform. The first parameter is the name to give the field containing the independent variable, the second the name to give the field containing dependent variable. If not specified, the original input independent and dependent field names are used.

Indicates a linear regression method.

Indicates a log regression method.

Indicates an exponential regression method.

Indicates a power regression method.

Indicates a quadratic regression method.

Indicates a polynomial regression method. The order of the polynomial can be set with rgOrder (defaulting to cubic if not provided).

Calculate quantile values from an input data stream. Useful for examining distributional properties of a data stream and for creating Q-Q plots.

The data fields to group by when performing a quantile transformation. If not specified, a single group contianing all data objects will be used.

A list of probabilities in the range [0,1] for which to compute quantile values. If not specified, the default step size of 0.01 or the value specified via qtStep will be used.

The interval between probabilties to use when performing a quantile transformation. All values from half the given step size to 1 will be sampled. Only used if qtProbs is not specified.

The field names to give the probability and associated quantile values generated by a quantile transofrmation. If not specified, prob and value are used.

Window transform for performing calculations over sorted groups of data objects such as ranking, lead/lag analysis, running sums and averages.

The first parameter is a list of tuples each comprising a window transform field definition and an output name. The second is the window transform definition.

   trans =
       transform
           << window [ ( [ wiAggregateOp opSum, wiField "Time" ], "TotalTime" ) ]
               [ wiFrame Nothing Nothing ]

An aggregate operation to be used in a window transformation.

transform
    << window [ ( [ wiAggregateOp opSum, wiField "Time" ], "TotalTime" ) ]
        [ wiFrame Nothing Nothing ]

Window-specific operation to be used in a window transformation.

Numeric parameter for window-only operations that can be parameterised (woPercentile, woLag, woLead and woNthValue).

Field for which to compute a window operation. Not needed for operations that do not apply to fields such as opCount, woRank and woDenseRank.

Assign consecutive row number to values in a data object to be applied in a window transform.

Rank function to be applied in a window transform.

Dense rank function to be applied in a window transform.

Percentile of values in a sliding window to be applied in a window transform.

Cumulative distribution function to be applied in a window transform.

Value preceding the current object in a sliding window to be applied in a window transform.

Value preceding the current object in a sliding window to be applied in a window transform.

Value following the current object in a sliding window to be applied in a window transform.

First value in a sliding window to be applied in a window transform.

Last value in a sliding window to be applied in a window transform.

Nth value in a sliding window to be applied in a window transform.

Moving window for use by a window transform. The two parameters should either be Just a number indicating the offset from the current data object, or Nothing to indicate unbounded rows preceding or following the current data object.

Whether or not the sliding window frame in a window transform should ignore peer values (those considered identical by the sort criteria).

Fields for partitioning data objects in a window transform into separate windows. If unspecified, all points will be in a single group.

Comparator for sorting data objects within a window transform.

Indicate that the given field should be sorted in ascending order when performing a window transform.

Indicate that the given field should be sorted in descending order when performing a window transform.

An area mark for representing a series of data elements, such as in a stacked area chart or streamgraph.

Bar mark for histograms, bar charts etc.

Boxplot composite mark for showing summaries of statistical distributions. By default, just box and whiskers are shown, but ticks and outliers can be specified explicitly. For example,

boxplot
    [ maTicks [ maColor "black", maSize 8 ]
    , maBox [ maFill "grey" ]
    , maOutliers [ maColor "firebrick" ]
    ]

Errorband composite mark for showing summaries of variation along a signal. By default no border is drawn. To add a border use maBorders with an empty list for default border, or mark properties to customise. For example,

errorband [ maBorders [ maColor "black", maStrokeWidth 0.5 ] ]

Errorbar composite mark for showing summaries of variation along a signal. By default no ticks are drawn. To add ticks with use maTicks with an empty list for default appearance, or with a list of mark properties to customise. For example,

errorbar [ maTicks [ maColor "black", maSize 8 ] ]

Circle mark for symbolising points. Unlike the point mark, circles are filled by default and may be sized via a separate size encoding.

Geoshape determined by geographically referenced coordinates.

let
    data =
        dataFromUrl "city.json" [ topojsonFeature "boroughs" ]
in
toVegaLite
    [ data
    , geoshape [ maFill "lightgrey", maStroke "white" ]
    ]

Image mark for displaying an image. The parameter is a list of standard mark properties for customising the image. The image files to be displayed should be specified via the url channel. Normally, the width and height of the image should be specified with maWidth and maHeight.

let
    data =
        dataFromColumns []
            << dataColumn "x" (nums [ 0.5, 1.5, 2.5 ])
            << dataColumn "y" (nums [ 0.5, 1.5, 2.5 ])


    enc =
        encoding
            << position X [ pName "x", pQuant ]
            << position Y [ pName "y", pQuant ]
            << url [ hStr "myImage.png" ]
in
toVegaLite [ data [], enc [], image [ maWidth 50, maHeight 25 ] ]

Alternatively, data-driven images can be used by referencing a data field containing image URLs.

let
    data =
        dataFromColumns []
            << dataColumn "x" (nums [ 0.5, 1.5, 2.5 ])
            << dataColumn "y" (nums [ 0.5, 1.5, 2.5 ])
            << dataColumn "img" (strs [ "img1.png", "img2.png", "img3.png" ])


    enc =
        encoding
            << position X [ pName "x", pQuant ]
            << position Y [ pName "y", pQuant ]
            << url [ hName "img", hNominal ]
in
toVegaLite [ data [], enc [], image [ maWidth 30, maHeight 30 ] ]

Line mark for symbolising a sequence of values.

Point mark for symbolising a data point with a symbol.

Rectangle mark.

Rule line connecting two vertices.

Square mark for symbolising points.

Text mark to be displayed at some point location.

Short line (tick) mark for symbolising point locations.

Trail mark (line with variable width along its length).

Horizontal alignment of a text mark.

Rotation angle of a text mark (degrees from horizontal).

Band size of a bar mark.

Vertical alignment of a text mark.

Offset between bars for a binned field using a bar mark.

Border properties for an errorband mark.

Box symbol properties for the boxplot mark.

Whether or not a mark should be clipped to the enclosing group's dimensions.

Determine whether or not invalid (null and NaN) values are considered for encoding as marks. If true (default), invalid values are ignored, otherwise they are treated as if 0.

Default color of a mark. Note that maFill and maStroke have higher precedence and will override this if specified. Color strings can use any valid HTML color specification. For example,

maColor "#eee"


maColor "#734FD8"


maColor "crimson"


maColor "rgb(255,204,210)"


maColor "hsl(180, 50%, 50%)"

A color gradient to apply to a mark. The first parameter indicates whether the gradient should be linear or radial. The second is a set of customisation options for the colors, positioning and rate of change of the gradient. For example, to set a radial red-blue color gradient for a mark:

maColorGradient grRadial [ grStops [ ( 0, "red" ), ( 1, "blue" ) ] ]

The radius in pixels of all four corners of a rectangle mark. Default is 0 (square corners).

The radius in pixels of the top-left corner of a rectangle mark. Will override any value specified in maCornerRadius.

The radius in pixels of the top-right corner of a rectangle mark. Will override any value specified in maCornerRadius.

The radius in pixels of the bottom-left corner of a rectangle mark. Will override any value specified in maCornerRadius.

The radius in pixels of the bottom-right corner of a rectangle mark. Will override any value specified in maCornerRadius.

Cursor to be associated with a hyperlink mark.

Extent of whiskers used in a boxplot, error bars or error bands.

Hyperlink to be associated with a mark making it a clickable hyperlink.

Continuous band size of a bar mark.

Discrete band size of a bar mark.

Horizontal offset between a text mark and its anchor.

Vertical offset between a text mark and its anchor.

Default fill color of a mark. Color strings can use any valid HTML color specification. For example,

maColor "#eee"


maColor "#734FD8"


maColor "crimson"


maColor "rgb(255,204,210)"


maColor "hsl(180, 50%, 50%)"

An empty string ("") indicates that no filling should be provided (but for clearer semantics, better to use maFilled False).

A color gradient to apply to a mark's interior. The first parameter indicates whether the gradient should be linear or radial. The second is a set of customisation options for the colors, positioning and rate of change of the gradient. For example, to set a radial red-blue color gradient as a fill for a mark:

maStrokeGradient grRadial [ grStops [ ( 0, "red" ), ( 1, "blue" ) ] ]

Fill gradients have a higher priority than maColorGradient.

Whether or not a mark's color should be used as the fill color instead of stroke color.

Fill opacity of a mark.

Font of a text mark. Can be any font name made accessible via a css file (or a generic font like serif, monospace etc.).

Font size in pixels used by a text mark.

Font style (e.g. italic) used by a text mark.

Font weight used by a text mark.

Interpolation method used by line and area marks. For example to create a curved line joining data points:

line [ maInterpolate miMonotone ]

Overall opacity of a mark in the range 0 (completely transparent) to 1 (completely opaque).

Ordering of vertices in a line or area mark. If true (default), order is determined by measurement type or order channel. If false, the original data order is used.

Orientation of a non-stacked bar, tick, area or line mark.

Appearance of a point marker joining the vertices of a line or area mark.

line [ maPoint (pmMarker [ maFill "black" ]) ]

Appearance of a line marker joining the vertices of an area mark.

area
    [ maLine (lmMarker [ maStroke "black" ])
    , maInterpolate miMonotone
    ]

Median line properties for the boxplot mark.

Outlier symbol properties for the boxplot mark.

Polar coordinate radial offset of a text mark from its origin.

Rule (main line) properties for the errorbar and boxplot marks.

Shape of a point mark.

Whether or not month and weekday names are abbreviated in a text mark.

Size of a mark in square units. For example to create a circle of diameter 50 pixels,

circle [ maSize 2500 ]

Default stroke color of a mark. Color strings can use any valid HTML color specification. For example,

maColor "#eee"


maColor "#734FD8"


maColor "crimson"


maColor "rgb(255,204,210)"


maColor "hsl(180, 50%, 50%)"

An empty string ("") indicates that no stroke around a mark be drawn.

A color gradient to apply to a mark's bounary stroke. The first parameter indicates whether the gradient should be linear or radial. The second is a set of customisation options for the colors, positioning and rate of change of the gradient. For example, to set a radial red-blue color gradient for a mark's stroke:

maStrokeGradient grRadial [ grStops [ ( 0, "red" ), ( 1, "blue" ) ] ]

Stroke gradients have a higher priority than maColorGradient.

Cap style of a mark's stroke.

Rounded stroke cap.

Square stroke cap.

Butt stroke cap.

Stroke dash style used by a mark. Determined by an alternating 'on-off' sequence of line lengths.

Number of pixels before the first line dash is drawn.

Line segment join style of a mark's stroke.

Rounded stroke join.

Bevelled stroke join.

Mitred stroke join.

Mitre limit at which to bevel a join between line segments of a mark's stroke.

Stroke opacity of a mark in the range 0 to 1.

Stroke width of a mark in pixel units.

Names of custom styles to apply to a mark. Each should refer to a named style defined in a separate style configuration.

Interpolation tension used when interpolating line and area marks.

Placeholder text for a text mark for when a text channel is not specified.

Polar coordinate angle (clockwise from north in radians) of a text mark from the origin determined by its x and y properties.

Thickness of a tick mark.

Tick properties for the errorbar or boxplot mark.

Source of a mark's tooltip content.

Explicitly set the width of a mark (e.g. bar width)

Explicitly set the height of a mark.

X position of a mark.

Y position of a mark.

X position offset for a mark.

Y position offset for a mark.

X2 position (secondary x value for lines and areal marks).

Y2 position (secondary y value for lines and areal marks).

X2 position offset for a mark.

Y2 position offset for a mark.

Whether or not the aspect ratio of an image mark should be preserved.

Indicates a linear color gradient. See the Vega-Lite color gradient documentation.

Indicates a radial color gradient. See the Vega-Lite color gradient documentation.

The x-coordinate, normalized to [0, 1], for the start of a color gradient. If the gradient is linear the default is 0; if radial, it is the x-position of the centre of the inner circle with a default of 0.5.

The x-coordinate, normalized to [0, 1], for the end of a color gradient. If the gradient is linear the default is 1; if radial, it is the x-position of the centre of the outer circle with a default of 0.5.

The y-coordinate, normalized to [0, 1], for the start of a color gradient. If the gradient is linear the default is 0; if radial, it is the y-position of the centre of the inner circle with a default of 0.5.

The y-coordinate, normalized to [0, 1], for the end of a color gradient. If the gradient is linear the default is 1; if radial, it is the y-position of the centre of the outer circle with a default of 0.5.

The radius, normalized to [0, 1], of the inner circle for a radial color gradient. Default is 0.

The radius, normalized to [0, 1], of the outer circle for a radial color gradient. Default is 0.5.

Color interpolation points. Each tuple in the list is a position normalised [0, 1] and its associated color.

Indicate horizontal mark orientation.

Indicate vertical mark orientation.

Cubic basis spline interpolation between points anchored at first and last points.

Open cubic basis spline interpolation between points, which may not intersect first and last points.

Closed cubic basis spline interpolation between points forming a polygon.

Bundle curve interpolation between points.

Cubic cardinal spline interpolation between points anchored at first and last points.

Open cubic cardinal spline interpolation between points, which may not intersect first and last points

Closed cubic cardinal spline interpolation between points forming a polygon.

Linear (straight) interpolation between points.

Cubic spline interpolation that preserves monotonicity between points.

Piecewise (stepped) constant interpolation function centred on each point in a sequence.

Piecewise (stepped) constant interpolation function after each point in a sequence.

Piecewise (stepped) constant interpolation function before each point in a sequence.

Specify a circular symbol for a shape mark.

Specify a cross symbol for a shape mark.

Specify a diamond symbol for a shape mark.

Specify a square symbol for a shape mark.

Specify an upward triangular symbol for a shape mark.

Specify a downward triangular symbol for a shape mark.

Specify a leftward facing triangular symbol for a shape mark.

Specify a rightward facing triangular symbol for a shape mark.

A custom symbol shape as an SVG path description.

Specify a linear symbol for a shape mark. Note that this will only be visible if the symbol has a stroke setting (unlike all the other areal symbols filling it has no effect).

Specify a centred arrow symbol for a shape mark. Useful for vector plots.

Specify a centred wedge (thin triangle) symbol for a shape mark. Useful for vector plots.

Specify a centred triangle symbol for a shape mark. Useful for vector plots.

No point marker to be shown on a line or area mark.

Transparent point marker to be placed on area or line mark. Useful for interactive selections.

Properties of a point marker that is overlaid on a line or area mark. Used when specifying an maPoint.

Properties of a line marker that is overlaid on an area mark. Used when specifying an maLine.

Indicates no line marker on an area mark.

Band extent between the minimum and maximum values in a distribution.

Band extent between the 95% confidence intervals of a distribution.

Band extent between the lower and upper quartiles of a distribution.

A scaling of the interquartile range to be used as whiskers in a boxplot. For example, a value of 1.5 would extend whiskers to ±1.5x the IQR from the mean.

Band extent as the standard error about the mean of a distribution.

Band extent as the standard deviation of a distribution.

Indicate tooltips are generated by all fields in the underlying data.

circle [ maTooltip ttData ]

Indicate tooltips should be enebled using the encoded data of the mark.

circle [ maTooltip ttEncoding ]

Indicate that tooltips should be disabled for the mark (default).

circle [ maTooltip ttNone ]

Automatically determine a cursor type depending on interaction context.

Default cursor.

No cursor.

Context menu cursor.

Help cursor.

Pointer cursor.

Progress cursor.

Waiting cursor.

Cell cursor.

Crosshair cursor.

Text cursor.

Vertical text cursor.

Alias cursor.

Copy cursor.

Move cursor.

'No drop' cursor.

'Not allowed' cursor.

Scrolling cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Resizing cursor.

Zooming cursor.

Zooming cursor.

Grab cursor.

Grabbing cursor.

Create an encoding specification from a list of channel encodings. These are commonly built by chaining series of channel encoding functions together such as position, color, size etc.

enc =
    encoding
        << position X [ pName "month", pTemporal ]
        << position Y [ pName "score", pQuant ]
        << color [ mName "team", mMType Nominal ]

Type of measurement to be associated with some channel.

• Nominal indicates categories that have no order. e.g. people's names; country names.
• Ordinal indicates ordered categories. e.g. Small / Medium / Large; 1st, 2nd, 3rd.
• Quantitative indicates numerical measurements and counts. e.g. price; temperature; frequency.
• Temporal indicates time-related data.
• GeoFeature indicates one or more geographic locations. e.g. a longitude/latitude; country outline.

Encode a position channel. The first parameter identifies the channel, the second a list of position encoding options.

enc =
    encoding
        << position X [ pName "month", pTemporal ]
        << position Y [ pName "numHires", pQuant ]

Type of position channel. X and Y position marks along the horizontal and vertical axes. X2 and Y2 are used in combination with X and Y when two boundaries of a mark need to be specified (e.g. a rule mark).

Longitude/Longitude2 and Latitude/Latitude2 are the equivalent for geographic positioning subject to projection.

XError/XError2 and YError/YError2 are used when specifying bounds of an errorbar mark.

Name of field used for encoding with a position channel.

Reference in a position channel to a field name generated by repeatFlow or repeat. The parameter identifies whether reference is being made to fields that are to be arranged in columns, in rows or a with a flow layout.

enc =
    encoding
        << position X [ pRepeat arFlow, pQuant ]


spec =
      asSpec [ data [], tick [], enc [] ]


toVegaLite
    [ repeatFlow [ "Horsepower", "Miles_per_Gallon", "Acceleration"]
    , specification spec
    ]

Indicate a data field encoded as a position is nominal. Equivalent to pMType Nominal.

Indicate a data field encoded as a position is ordinal. Equivalent to pMType Ordinal.

Indicate a data field encoded as a position is quantitative. Equivalent to pMType Quantitative.

Indicate a data field encoded as a position is temporal. Equivalent to pMType Temporal.

Indicate a data field encoded as a position is a geo feature. Equivalent to pMType GeoFeature.

Level of measurement when encoding with a position channel. See also pNominal, pOrdinal, pQuant, pTemporal and pGeo for shorthand equivalents.

Discretize numeric values into bins when encoding with a position channel. For non-default binning, bin-widths, extent etc. can be specified in the first ] parameter. For example, to encode a frequency histogram with bins every 5 units,

enc =
    encoding
        << position X [ pName "x", pOrdinal, pBin [ biStep 5 ] ]
        << position Y [ pQuant, pAggregate opCount ]

Indicate that data encoded with position are already binned.

Form of time unit aggregation of field values when encoding with a position channel.

Title of a field when encoding with a position channel. Multi-line titles can be specified by adding a \n at line breaks.

Compute some aggregate summary statistics for a field to be encoded with a position channel. The type of aggregation is determined by the given operation parameter.

enc =
    encoding
        << position X [ pName "role", pOrdinal ]
        << position Y [ pName "salary", pQuant, pAggregate opMean ]

Scaling applied to a field when encoding with a position channel. The scale will transform a field's value into a position along one axis.

For example, the following will scale the bars positioned along a horizontal axis to have an inner spacing of 50% (0.5) of the total space allocated to each bar.

enc =
    encoding
        << position X [ pName "ageGroup", pNominal, pScale [ scPaddingInner 0.5 ] ]

Axis properties used when encoding with a position channel. For no axis, provide an empty list.

Sort order for field when encoding with a position channel.

Specify mark position or size relative to band size. For non-rect marks, the relative position on a band of a stacked, binned, time unit or band scale is used. A value of 0, posituions the mark at the beginning of the band; 0.5, in the middle etc.

For rect-based marks (rect, bar, and image), if set to 1, the mark size is set to the band width or the time unit interval. If set to 0.5, the mark size is half of the bandwidth or the time unit interval. etc.

Type of stacking offset for field when encoding with a position channel. For example, stacking areas away from a centreline can be used to create a streamgraph:

enc =
    encoding
        << position X [ pName "week", pOrdinal ]
        << position Y [ pName "takings", pQuant, pStack stCenter ]
        << color [ mName "shop", mNominal ]

Set the position to the width of the enclosing data space. Useful for justifying a mark to the right hand edge of a view. e.g. to position a mark at the right of the data rectangle:

enc =
    encoding
        << position X [ pWidth ]

Set the position to the height of the enclosing data space. Useful for placing a mark relative to the bottom edge of a view.

Set a position to an arbitrary value. Useful for placing items at the top of a plot area (pNum 0) or a fixed number of pixels from the top.

Imputation rules for a position channel. See the Vega-Lite impute documentation For example, to impute the missing value of b with the mean of existing b values, when a is 30 and its color group (c) is 1:

let
    data =
        dataFromColumns []
            << dataColumn "a" (nums [ 0, 0, 10, 10, 20, 20, 30 ])
            << dataColumn "b" (nums [ 28, 91, 43, 55, 81, 53, 19 ])
            << dataColumn "c" (nums [ 0, 1, 0, 1, 0, 1, 0 ])


    enc =
        encoding
            << position X [ pName "a", pQuant ]
            << position Y [ pName "b", pQuant, pImpute [ imMethod imMean ] ]
            << color [ mName "c", mNominal ]
in
toVegaLite [ data [], enc [], line [] ]

Indicate sorting is to be applied from low to high.

Indicate sorting is to be applied from high to low.

Sort by the aggregated summary of a given field using a given aggregation operation. e.g., sort the categorical data field variety by the mean age of the data in each variety category:

position Y
    [ pName "variety"
    , pOrdinal
    , pSort [ soByField "age" opMean, soDescending ]
    ]

Sort by another channel.

position Y [ pName "age", pOrdinal, pSort [ soByChannel chX ] ]

Sort by the aggregated summaries of the given fields (referenced by a repeat iterator) using a given aggregation operation.

Custom sort order listing data values explicitly.

Position of axis tick relative to a band (0 to 1).

Maximum extent in pixels that axis ticks and labels should use.

Minimum extent in pixels that axis ticks and labels should use.

Orientation of an axis relative to the plot it is describing.

Offset to displace the axis from the edge of the enclosing group or data rectangle.

Anchor position of the axis in pixels. For x-axis with top or bottom orientation, this sets the axis group x coordinate. For y-axis with left or right orientation, this sets the axis group y coordinate.

Drawing order of the axis and its associated features (grid lines, ticks etc.) relative to the other chart elements. A value greater than 0 indicates axis is drawn in front of chart marks, 0 indicates it is drawn behind them. The z-order of intersecting grid lines associated with x- and y- axes can be controlled by assigning a higher z-value to the axis to appear on top.

Make an axis property (tick, grid or label) conditional on one or more predicate expressions. The first parameter is the test to apply. The second is a pair of properties to set if the test evaluates to true or false.

The test parameter has access to the axis properties value and label corresponding to the value associated with an individual axis element and its text label. These should be used rather than the underlying data field when referencing a data value. For example,

 pAxis
    [ axDataCondition (expr "datum.value <= 2")
        (cAxTickColor "red" "blue")
    , axDataCondition (expr "datum.label =='4.0'")
        (cAxTickWidth 5 2)
    ]

You can also apply inline aggregation before applying the test using fiOpTrans, which can be particularly useful for filtering temporal data. For example the following will apply solid grid lines for January 1st of each year and dashes for all other dates:

pAxis
    [ axDataCondition
        (fiEqual "value" (dt [ dtMonth Jan, dtDate 1 ])
            |> fiOpTrans (mTimeUnit monthDate)
        )
        (cAxGridDash [] [ 2, 2 ])
    ]

Whether or not an axis baseline (domain) should be included as part of an axis.

Color of axis domain line.

Opacity of axis domain line.

Width of axis domain line.

Formatting pattern for axis labels. To distinguish between formatting as numeric values and data/time values, additionally use axFormatAsNum or axFormatAsTemporal.

Indicate that axis labels should be formatted as numbers. To control the precise numeric format, additionally use axFormat providing a d3 numeric format string.

Indicate that axis labels should be formatted as dates/times. To control the precise temporal format, additionally use axFormat providing a d3 date/time format string.

Whether or not axis labels should be displayed.

Horizontal alignment of axis tick labels.

Conditional axis label alignment. The first parameter provides the alignment when a predicate is true, the second when it is false.

Rotation angle of axis labels (degrees from horizontal).

Vertical alignment of axis tick labels.

Conditional axis vertical label alignment. The first parameter provides the alignment when a predicate is true, the second when it is false.

How or if labels should be hidden if they exceed the axis range. If Nothing, no check for label size is made. A number specifies the permitted overflow in pixels.

Color of axis tick label.

Conditional axis label color. The first parameter provides the color when a predicate is true, the second when it is false.

An expression to generate axis labels. The parameter is a valid Vega expression. Can reference datum.value and datum.label for access to the underlying data values and default label text respectively. For example, to provide 4 digit years every decade and 2-digit years for all other tick marks:

pAxis
    [ axLabelExpr "if(year(datum.value) % 10 == 0"
        ++ ", utcFormat(datum.value,'%Y')"
        ++ ", utcFormat(datum.value,'%y'))"
    ]

How or if labels at beginning or end of the axis should be aligned. Specifies the distance threshold from an end-point within which labels are flush-adjusted or if Nothing, no flush-adjustment made.

Number of pixels by which to offset flush-adjusted labels.

Font name of an axis label.

Conditional axis label font. The first parameter provides the font when a predicate is true, the second when it is false.

Font size of an axis label.

Conditional axis label font size. The first parameter provides the size when a predicate is true, the second when it is false.

Font style of an axis label (e.g. "italic")

Conditional axis label font style. The first parameter provides the style when a predicate is true, the second when it is false.

Font weight of an axis label.

Conditional axis label font weight. The first parameter provides the weight when a predicate is true, the second when it is false.

Maximum length in pixels of axis tick labels.

Opacity of an axis label.

Conditional axis label opacity. The first parameter provides the opacity when a predicate is true, the second when it is false.

Overlap strategy for labels when they are too large to fit within the space devoted to an axis.

Padding in pixels between an axis and its text labels.

The minimum separation between labels (in pixel units) before they are considered non-overlapping. Ignored if axLabelOverlap is osNone.

Whether or not an axis should include tick marks.

Color of axis ticks.

Conditional axis tick color. The first parameter provides the color when a predicate is true, the second when it is false.

Desired number of ticks for axes visualizing quantitative scales. The resulting number may be different so that values are “nice” (multiples of 2, 5, 10).

Whether or not an extra axis tick should be added for the initial position of an axis.

Offset in pixels of an axis's ticks, labels and gridlines.

Opacity of axis ticks.

Conditional axis tick opacity. The first parameter provides the opacity when a predicate is true, the second when it is false.

Whether or not axis tick positions should be rounded to nearest integer.

Tick mark size in pixels.

The minimum desired step between axis ticks, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If specified, the tick count value will be adjusted, if necessary, to enforce the minimum step value.

Width of axis ticks.

Conditional axis tick width. The first parameter provides the width when a predicate is true, the second when it is false.

Set explicit tick/grid/label values along an axis. For example, for a quantitative field:

pAxis [ axValues (nums [ 2, 3, 5, 7, 11, 13, 17 ]) ]

Or a categorical field:

pAxis [ axValues (strs [ "cats", "dogs", "parrots" ]) ]

Or for a temporal field:

pAxis
    [ axValues
        (dts
            [ [ dtYear 2019, dtMonth Mar, dtDate 31 ]
            , [ dtYear 2019, dtMonth Jun, dtDate 30 ]
            , [ dtYear 2019, dtMonth Sep, dtDate 30 ]
            , [ dtYear 2019, dtMonth Dec, dtDate 31 ]
            ]
        )
    ]

Title to display as part of an axis. An empty string can be used to prevent a title being displayed. Multi-line titles can be specified by adding a \n at line breaks.

Horizontal alignment of an axis title.

Anchor position of an axis title.

Angle of an axis title (degrees from horizontal).

Vertical alignment of axis title.

Color of axis title.

Font name for an axis title.

Font size of an axis title.

Font style of an axis title (e.g. "italic").

Font weight of an axis title.

Maximum length in pixels of axis title.

Opacity of an axis title.

Padding in pixels between a title and axis.

X position of an axis title relative to the axis group.

Y position of an axis title relative to the axis group.

Whether or not grid lines should be included as part of an axis.

Color of grid lines associated with an axis.

Conditional axis grid color. The first parameter provides the color when a predicate is true, the second when it is false.

Axis grid line dash style. The parameter is a list of alternating 'on' and 'off' lengths in pixels representing the dashed line.

Conditional axis grid dash. The first parameter provides the dash when a predicate is true, the second when it is false.

Opacity of grid lines associated with an axis.

Conditional axis grid opacity. The first parameter provides the opacity when a predicate is true, the second when it is false.

Width of grid lines associated with an axis.

Conditional axis grid width. The first parameter provides the width when a predicate is true, the second when it is false.

Left horizontal text alignment.

Center horizontal text alignment.

Right horizontal text alignment.

Top vertical text alignment.

Middle vertical text alignment.

Bottom vertical text alignment.

No overlap strategy to be applied when there is not space to show all items on an axis.

Greedy overlap strategy to be applied when there is not space to show all items on an axis.

Give all items equal weight in overlap strategy to be applied when there is not space to show them all on an axis.

Top side, used to specify an axis position.

Bottom side, used to specify an axis position.

Left side, used to specify an axis position.

Right side, used to specify an axis position.

Encode a size channel. The first parameter is a list of size encoding options such as the data to encode, size scaling etc.

enc =
    encoding
        << size [ mName "population", mQuant ]

Encode a color channel. The first parameter is a list of color encoding options such as the data to encode, colour scaling etc.

enc =
    encoding
        << color [ mName "avHireTime", mQuant ]

Encode a fill channel. This acts in a similar way to encoding by color but only affects the interior of closed shapes. If both fill and color encodings are specified, fill takes precedence.

Encode a stroke channel. This acts in a similar way to encoding by color but only affects the exterior boundary of marks.

Encode a stroke width channel.

Encode an opacity channel.

Encode a fill opacity channel. This acts in a similar way to encoding by opacity but only affects the interior of closed shapes. If both fillOpacity and opacity encodings are specified, fillOpacity takes precedence.

Encode a stroke opacity channel. This acts in a similar way to encoding by opacity but only affects the exterior boundary of marks. If both opacity and strokeOpacity are specified, strokeOpacity takes precedence for stroke encoding.

Encode a shape channel. The first parameter is a list of shape encoding options such as the data to encode, custom shape encodings etc.

enc =
    encoding
        << shape [ mName "company", mNominal ]

Name of field used for encoding with a mark property channel.

Reference in a mark channel to a field name generated by repeatFlow or repeat. The parameter identifies whether reference is being made to fields that are to be arranged in columns, in rows or a with a flow layout.

Indicate a data field encoded as a mark property is nominal. Equivalent to mMType Nominal.

Indicate a data field encoded as a mark property is ordinal. Equivalent to mMType Ordinal.

Indicate a data field encoded as a mark property is quantitative. Equivalent to mMType Quantitative.

Indicate a data field encoded as a mark property is temporal. Equivalent to mMType Temporal.

Indicate a data field encoded as a mark property is a geo feature. Equivalent to mMType GeoFeature.

Level of measurement when encoding with a mark property channel. See also nNominal, mOrdinal, mQuant, mTemporal and mGeo for shorthand equivalents.

Scaling applied to a field when encoding with a mark property channel. The scale will transform a field's value into a color, shape, size etc.

Discretize numeric values into bins when encoding with a mark property channel.

Indicate that data encoding with a mark are already binned.

Sort order when encoding sortable mark properties such as colour.

Time unit aggregation of field values when encoding with a mark property channel.

Title of a field when encoding with a mark property channel. Multi-line titles can be specified by adding a \n at line breaks.

Compute some aggregate summary statistics for a field to be encoded with a mark property channel. The type of aggregation is determined by the given operation parameter.

Properties of a legend that describes a mark's encoding. For no legend, provide an empty list as the parameter.

SVG path string used when encoding with a mark property channel. Useful for providing custom shapes.

Literal numeric value when encoding with a mark property channel.

Literal string value when encoding with a mark property channel.

Boolean value when encoding with a mark property channel.

A symbol literal when encoding with a mark property channel. Can be useful when making a symbol dependent on some data or selection condition.

A gradient legend for continuous quantitative data.

A symbol legend for categorical data.

Limit height of legend entries.

Horizontal padding between symbol legend entries.

Number of columns in which to arrange symbol legend entries.

Legend corner radius.

Direction of a legend.

Legend background color.

Formatting pattern for legend values. To distinguish between formatting as numeric values and data/time values, additionally use leFormatAsNum or leFormatAsTemporal.

Indicate that legend labels should be formatted as numbers. To control the precise numeric format, additionally use leFormat providing a d3 numeric format string.

Indicate that legend labels should be formatted as dates/times. To control the precise temporal format, additionally use leFormat providing a d3 date/time format string.

Length in pixels of the primary axis of a color ramp legend.

Thickness in pixels of a color ramp legend.

Color for strokes in a color ramp legend.

Width for strokes in a color ramp legend.

Alignment to apply to symbol legends rows and columns.

Horizontal alignment of legend labels.

Vertical alignment of legend labels.

Color for legend labels.

Font for legend labels.

Font size legend labels.

Maximum width for legend labels in pixel units.

Offset for legend labels.

Strategy for resolving overlapping legend labels.

Offset in pixels of a legend from the encoded marks it describes. If the legend orientation is one of loTop, loBottom, loLeft or loRight, a positive offset moves the legend outwards away from the encoded marks. If it is one of loTopLeft, loTopRight, loBottomLeft or loBottomRight a positive offset will move it inwards away from the corner. If loNone, the offset has no effect.

Position of a legend in a scene.

Padding in pixels between a legend and axis.

Vertical spacing in pixel units between a symbol legend entries.

Legend border color.

Legend border stroke width.

Legend symbol fill color.

Legend symbol size.

Legend symbol outline color.

Legend symbol stroke width.

Legend symbol type.

Number of tick marks in a quantitative legend.

Title of a legend. Multi-line titles can be specified by adding a \n at line breaks.

Horizontal alignment for legend titles.

Vertical alignment for legend titles.

Color for legend title.

Font for legend titles.

Font size for legend titles.

Font weight for legend titles.

Maximum size in pixel units for legend titles.

Spacing in pixel units between title and legend.

Type of legend.

An explicit set of legend values.

x-position of legend group in pixel units for absolute positioning when leOrient is set to loNone.

y-position of legend group in pixel units for absolute positioning when leOrient is set to loNone.

Drawing order of a legend relative to other chart elements. To place a legend in front of others use a positive integer, or 0 to draw behind.

Position legend to the left of the visualization it describes.

Position legend outside and to the right of the visualization it describes.

Position legend outside and above the visualization it describes.

Position legend outside and below the visualization it describes.

Position legend within the visualization it describes in the top-left corner.

Position legend within the visualization it describes in the top-right corner.

Position legend within the visualization it describes in the bottom-left corner.

Position legend within the visualization it describes in the bottom-right corner.

Do not perform automatic legend positioning (allows legend to be located explicitly via x y coordinates).

An explicit set of numeric legend values.

An explicit set of legend strings.

An explicit set of legend date-times.

Encode a text channel. The first parameter is a list of text encoding options such as the data to encode, number formatting etc.

enc =
    encoding
        << text [ tName "keyword", tNominal ]

Encode a tooltip channel using a single data field.

 tooltip [ tName "Month", tTemporal, tFormat "%B %Y" ]

To encode multiple tooltip values with a mark, use tooltips.

Encode a tooltip channel using multiple data fields. The first parameter is a list of the multiple tooltips, each of which is a list of text channel properties that define the channel.

tooltips
    [ [ tName "month", tTemporal, tFormat "%B %Y" ]
    , [ tName "temperature", tQuant ]
    ]

Name of field used for encoding with a text channel.

Reference in a text channel to a field name generated by repeatFlow or repeat. The parameter identifies whether reference is being made to fields that are to be arranged in columns, in rows or a with a flow layout.

Indicate a data field encoded as a text property is nominal. Equivalent to tMType Nominal.

Indicate a data field encoded as a text property is ordinal. Equivalent to tMType Ordinal.

Indicate a data field encoded as a text property is quantitative. Equivalent to tMType Quantitative.

Indicate a data field encoded as a text property is temporal. Equivalent to tMType Temporal.

Indicate a data field encoded as a text property is a geo feature. Equivalent to tMType GeoFeature.

Level of measurement when encoding with a text channel. See also tNominal, tOrdinal, tQuant, tTemporal and tGeo for shorthand equivalents.

Discretize numeric values into bins when encoding with a text channel.

Indicate that data encoded with a text channel are already binned.

Compute some aggregate summary statistics for a field to be encoded with a text channel. The type of aggregation is determined by the given operation parameter.

Time unit aggregation of field values when encoding with a text channel.

Title of a field when encoding with a text or tooltip channel. Multi-line titles can be specified by adding a \n at line breaks.

Literal string value when encoding with a text property channel. Can be useful for quick text annotation. For example

encoding
    << position X [ pNum 300 ]
    << position Y [ pNum 300 ]
    << text [ tStr "Upper limit of range" ]

Formatting pattern for text marks. To distinguish between formatting as numeric values and data/time values, additionally use tFormatAsNum or tFormatAsTemporal.

Indicate that values encoded with a text channel should be formatted as numbers. To control the precise numeric format, additionally use tFormat providing a d3 numeric format string.

Indicate that values encoded with a text channel should be formatted as dates/times. To control the precise temporal format, additionally use tFormat providing a d3 date/time format string.

Weight options for a font.

Encode a hyperlink channel. The first parameter is a list of hyperlink channel properties that characterise the hyperlinking such as the destination URL and cursor type.

encData =
    encoding
        << hyperlink [ hName "url", hNominal ]


encLiteral =
    encoding
        << hyperlink [ hStr "http://www.imdb.com" ]

Name of field used for encoding with a hyperlink channel.

Reference in a hyperlink channel to a field name generated by repeatFlow or repeat. The parameter identifies whether reference is being made to fields that are to be arranged in columns, in rows or a with a flow layout.

Indicate a data field encoded as a hyperlink or url property is nominal. Equivalent to hMType Nominal.

Indicate a data field encoded as a hyperlink property is ordinal. Equivalent to hMType Ordinal.

Indicate a data field encoded as a hyperlink or url property is quantitative. Equivalent to hMType Quantitative.

Indicate a data field encoded as a hyperlink or url property is temporal. Equivalent to hMType Temporal.

Indicate a data field encoded as a hyperlink property is a geo feature. Equivalent to hMType GeoFeature.

Level of measurement when encoding with a hyperlink or url channel. See also hNominal, hOrdinal, hQuant, hTemporal and hGeo for shorthand equivalents.

Discretize numeric values into bins when encoding with a hyperlink channel.

Indicate that data encoded with a hyperlink channel are already binned.

Compute some aggregate summary statistics for a field to be encoded with a hyperlink channel. The type of aggregation is determined by the given operation parameter.

Time unit aggregation of field values when encoding with a hyperlink channel.

Literal string value when encoding with a hyperlink channel.

Encode a url channel. The first parameter is a list of url channel properties that characterise the hyperlink to encode with. This is used for specifying data-driven image files for the image mark.

encData =
    encoding
        << url [ hName "url", hNominal ]


encLiteral =
    encoding
        << url [ hStr "http://www.imdb.com" ]