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 a data, mark, and encoding specification.

While simple properties like mark may be provided directly, it is usually clearer to label more complex ones such as encodings as separate expressions. This becomes increasingly helpful for visualizations that involve composition of layers, repeats and facets.

Specifications can be built up by chaining a series of functions (such as dataColumn or position in the example below). Functional composition using the . operator allows this to be done compactly.

let dat = dataFromColumns []
          . dataColumn "a" (Strings [ "C", "C", "D", "D", "E", "E" ])
          . dataColumn "b" (Numbers [ 2, 7, 1, 2, 6, 8 ])

    enc = encoding
          . position X [ PName "a", PmType Nominal ]
          . position Y [ PName "b", PmType Quantitative, PAggregate Mean ]

in toVegaLite [ dat [], mark Bar [], enc [] ]

The schema used is version 3 of Vega-Lite, although there are some differences, in part because of bugs in hvega - in which case please report an issue - but also because of issues with the Vega-Lite spec (for instance there are several minor issues I have reported against version 3.3.0 of the Vega-Lite schema).

Use toVegaLiteSchema if you need to create a Vega-Lite specification which uses a different version of the schema.

A version of toVegaLite that allows you to change the Vega-Lite schema version of the visualization.

toVegaLiteSchema vlSchema4 props

The latest version 2 Vega-Lite schema (equivalent to vlSchema 2 Nothing Nothing Nothing).

The latest version 3 Vega-Lite schema (equivalent to vlSchema 3 Nothing Nothing Nothing).

The latest version 4 Vega-Lite schema (equivalent to vlSchema 4 Nothing Nothing Nothing).

Create the Vega-Lite schema for an arbitrary version. See https://github.com/vega/schema for more information on naming and availability.

There is no validation of the input values.

At the time of writing the latest version 4 schema - which is https://vega.github.io/schema/vega-lite/v4.0.0-beta.0.json - can be specified as

vlSchema 4 (Just 0) (Just 0) (Just "-beta.0")

whereas

vlSchema 4 Nothing Nothing Nothing

refers to the latest version.

Extract the specification for passing to a VegaLite visualizer.

let vlSpec = fromVL vl
Data.ByteString.Lazy.Char8.putStrLn (Data.Aeson.Encode.Pretty.encodePretty vlSpec)

Note that there is no validation done to ensure that the output matches the Vega Lite schema. That is, it is possible to create an invalid visualization with this module (e.g. missing a data source or referring to an undefined field).

Top-level Vega-Lite properties. These are the ones that define the core of the visualization grammar. All properties are created by functions which can be arranged into seven broad groups:

Data Properties

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

Transform Properties

These 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 Properties

These relate to the symbols used to visualize data items. They are generated by mark, and include types such as Circle, Bar, and Line.

Encoding Properties

These 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

These allow visualization views to be combined to form more complex visualizations. Generated by layer, repeat, repeatFlow, facet, facetFlow, vlConcat, columns, hConcat, vConcat, asSpec, and resolve.

Interaction Properties

These allow interactions such as clicking, dragging and others generated via a GUI or data stream to influence the visualization. Generated by selection.

Supplementary and Configuration Properties

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

Prior to 0.4.0.0 this was an opaque data type, as the constructors were not exported. It is suggested that you do not import the constructors to VLProperty unless you need to transform the Vega-Lite code in some manner (e.g. because hvega is missing needed functionality or is buggy).

Note that there is only a very-limited attempt to enforce the Vega-Lite Schema (e.g. to ensure the required components are provided).

The Vega-Lite specification is represented as JSON.

A Vega Lite visualization, created by toVegaLite. The contents can be extracted with fromVL.

A convenience type-annotation label. It is the same as Data.

Since: 0.4.0.0

Represents a named Vega-Lite specification, usually generated by a function in this module. You shouldn't need to create LabelledSpec tuples directly, but they can be useful for type annotations.

Represent those functions which can be chained together using function composition to append new specifications onto an existing list.

Convenience type-annotation label to indicate an angle, which is measured in degrees from the horizontal (so anti-clockwise).

The value should be in the range 0 to 360, inclusive, but no attempt is made to enforce this.

Since: 0.4.0.0

Convenience type-annotation label to indicate a color value. There is no attempt to validate that the user-supplied input is a valid color.

Any supported HTML color specification can be used, such as:

"#eee"
"#734FD8"
"crimson"
"rgb(255,204,210)"
"hsl(180, 50%, 50%)"

Since: 0.4.0.0

Convenience type-annotation label to indicate an opacity value, which lies in the range 0 to 1 inclusive. There is no attempt to validate that the user-supplied value falls in this range.

A value of 0 indicates fully transparent (see through), and 1 is fully opaque (does not show anything it is on top of).

Since: 0.4.0.0

At what "depth" (z index) is the item to be drawn (a relative depth for items in the visualization). The standard values are 0 for back and 1 for front, but other values can be used if you want to ensure a certain layering of items.

The following example is taken from a discussion with Jo Wood:

let dcols = dataFromColumns []
              . dataColumn "x" (Numbers [ 20, 10 ])
              . dataColumn "y" (Numbers [ 10, 20 ])
              . dataColumn "cat" (Strings [ "a", "b" ])

    axis lbl z = [ PName lbl, PmType Quantitative, PAxis [ AxZIndex z ] ]
    enc = encoding
            . position X (axis "x" 2)
            . position Y (axis "y" 1)
            . color [ MName "cat", MmType Nominal, MLegend [] ]

    cfg = configure
            . configuration (Axis [ GridWidth 8 ])
            . configuration (AxisX [ GridColor "red" ])
            . configuration (AxisY [ GridColor "blue" ])

in toVegaLite [ cfg []
              , dcols []
              , enc []
              , mark Circle [ MSize 5000, MOpacity 1 ]
              ]

View the visualization in the Vega Editor

Since: 0.4.0.0

Combines a list of labelled specifications into a single specification. This is useful when you wish to create a single page with multiple visulizualizations.

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

Converts VegaLite to html Text. Uses Vega-Embed with the default options. See toHtmlWith for more control.

Since: 0.2.1.0

Converts VegaLite to an html file. Uses Vega-Embed with the default options. See toHtmlFileWith for more control.

Since: 0.2.1.0

Converts VegaLite to html Text. Uses Vega-Embed and is for when some control is needed over the output: toHtml is a simpler form which just uses the default Vega-Embed options.

The render you use to view the output file must support Javascript, since it is needed to create the visualization from the Vega-Lite specification. The Vega and Vega-Lite Javascript versions are pegged to 5 and 3, but no limit is applied to the Vega-Embed library.

Since: 0.4.0.0

Converts VegaLite to an html file. Uses Vega-Embed and is for when some control is needed over the output: toHtmlFile is a simpler form which just uses the default Vega-Embed options.

Since: 0.4.0.0

Declare data source from a url. The url can be a local path on a web server or an external http(s) url. Used to create a data ( property, specification ) pair. An optional list of field formatting instructions can be provided as the second parameter or an empty list to use the default formatting. See the Vega-Lite documentation for details.

dataFromUrl "data/weather.csv" [ Parse [ ( "date", FoDate "%Y-%m-%d %H:%M" ) ] ]

Declare a data source from a list of column values. Each column has a specific type (e.g. Number or String), but different columns can have different types.

Note that the columns are truncated to match the length of the shortest column.

dataFromColumns [ Parse [ ( "Year", FoDate "%Y" ) ] ]
  . dataColumn "Animal" (Strings [ "Fish", "Dog", "Cat" ])
  . dataColumn "Age" (Numbers [ 28, 12, 6 ])
  . dataColumn "Year" (Strings [ "2010", "2014", "2015" ])

Declare a data source from a provided list of row values. Each row contains a list of tuples where the first value is a string representing the column name, and the second the column value for that row. Each column can have a value of a different type but you must ensure that when subsequent rows are added, they match the types of previous values with shared column names.

Note though that generally if you are creating data inline (as opposed to reading from a file), adding data by column is more efficient and less error-prone.

dataFromRows [ Parse [ ( "Year", FoDate "%Y" ) ] ]
  . dataRow [ ( "Animal", Str "Fish" ), ( "Age", Number 28 ), ( "Year", Str "2010" ) ]
  . dataRow [ ( "Animal", Str "Dog" ), ( "Age", Number 12 ), ( "Year", Str "2014" ) ]
  . dataRow [ ( "Animal", Str "Cat" ), ( "Age", Number 6 ), ( "Year", Str "2015" ) ]

Declare a data source from a provided json specification. The most likely use-case for specifying json inline is when creating geojson objects, when geometry, geometryCollection, and geoFeatureCollection functions may be used. For more general cases of json creation, consider encode.

let geojson =
        geometry (GeoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []
in toVegaLite
    [ width 200
    , height 200
    , dataFromJson geojson []
    , projection [ PrType Orthographic ]
    , mark Geoshape []
    ]

Declare data from a named source. The source may be from named datasets within a specification or a named data source created via the Vega View API. An optional list of field formatting instructions can be provided as the second parameter or an empty list to use the default formatting. See the Vega-Lite documentation for details.

toVegaLite
    [ datasets [ ( "myData", dvals [] ),  ( "myJson", dataFromJson json [] ) ]
    , dataFromSource "myData" []
    , mark 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.

dvals = dataName "myName" (dataFromUrl "myData.json" [])

Since: 0.4.0.0

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.

let toJS = Data.Aeson.toJSON
    obj = Data.Aeson.object

    dvals = dataFromRows []
            . dataRow [ ( "cat", Str "a" ), ( "val", Number 10 ) ]
            . dataRow [ ( "cat", Str "b" ), ( "val", Number 18 ) ]
    json = toJS
            [ obj [ ( "cat", toJS "a" ), ( "val", toJS 120 ) ]
            , obj [ ( "cat", toJS "b" ), ( "val", toJS 180 ) ]
            ]

    enc = ...

in toVegaLite
    [ datasets [ ( "myData", dvals [] ),  ( "myJson", dataFromJson json [] ) ]
    , dataFromSource "myData" []
    , mark Bar []
    , enc []
    ]

Create a column of data. A column has a name and a list of values. The final parameter is the list of any other columns to which this is added.

This is expected to be used with dataFromColumns.

dataColumn "Animal" (Strings [ "Cat", "Dog", "Mouse"]) []

Create a row of data. A row comprises a list of (columnName, value) pairs. The final parameter is the list of any other rows to which this is added.

This is expected to be used with dataFromRows.

dataRow [("Animal", Str "Fish"), ("Age", Number 28), ("Year", Str "2010")] []

This is for composed specifications, and it tells the visualization to ignore the data from the parent.

Since: 0.4.0.0

Convenience type-annotation label for use with data generation functions.

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

It is the same as PropertySpec (which was added in 0.4.0.0), but kept separate to help better-document code.

Represents a single column of data. Used when generating inline data with dataColumn and dataFromColumns.

Represents a single row of data. Used when generating inline data with dataRow and dataFromRows.

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

geometry (GeoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []

Specifies a list of geo features to be used in a geoShape specification. Each feature object in this collection can be created with the geometry function.

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" ) ]
    ]

Specifies a list of geometry objects to be used in a geoShape specification. Each geometry object in this collection can be created with the geometry function.

geometryCollection
    [ geometry (GeoPolygon [ [ ( -3, 59 ), ( 4, 59 ), ( 4, 52 ), ( -3, 59 ) ] ]) []
    , geometry (GeoPoint -3.5 55.5) []
    ]

Specifies the type and content of geometry specifications for programatically creating GeoShapes. These can be mapped to the GeoJson geometry object types where the pluralised type names refer to their Multi prefixed equivalent in the GeoJSON specification.

Generate a sequence of numbers as a data source. The resulting sequence will have the name "data". To give it an alternative name use dataSequenceAs.

myData = dataSequence 0 6.28 0.1

Since: 0.4.0.0

Generate a sequence of numbers as a named data source. This extends dataSequence by allowing you to name the data source.

myTheta = dataSequenceAs 0 6.28 0.1 "theta"

Since: 0.4.0.0

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 ]
    , mark Geoshape [ MFill "aliceblue" ]
    ]

Since: 0.4.0.0

Generate a grid of lines of longitude (meridians) and latitude (parallels).

let proj = projection [ PrType Orthographic ]
    sphereSpec = asSpec [ sphere
                        , mark Geoshape [ MFill "aliceblue" ] ]
    gratSpec =
        asSpec
            [ graticule [ GrStep (5, 5) ]
            , mark Geoshape [ MFilled False, MStrokeWidth 0.3 ]
            ]
in toVegaLite [ proj, layer [ sphereSpec, gratSpec ] ]

Since: 0.4.0.0

Determine the properties of graticules. See the Vega-Lite documentation for details.

Since: 0.4.0.0

Specifies the type of format a data source uses. If the format is indicated by the file name extension (".tsv", ".csv", ".json") there is no need to indicate the format explicitly. However this can be useful if the filename extension does not indicate type (e.g. ".txt") or you wish to customise the parsing of a file. For example, when specifying the JSON format, its parameter indicates the name of property field containing the attribute data to extract. For details see the Vega-Lite documentation.

Indicates the type of data to be parsed when reading input data. For FoDate and FoUtc, the formatting specification can be specified using D3's formatting specifiers or left as an empty string if default date formatting is to be applied. Care should be taken when assuming default parsing of dates because different browsers can parse dates differently. Being explicit about the date format is usually safer.

Create a single transform from a list of transformation specifications. Note that the order of transformations can be important, especially if labels created with calculateAs, timeUnitAs, and binAs 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.

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

The supported transformations include: aggregate, binAs, calculateAs, impute, joinAggregate, lookup, lookupAs, flattenAs, foldAs, stack, timeUnitAs, and window.

Sets the cartographic projection used for geospatial coordinates. A projection defines the mapping from (longitude,latitude) to an (x,y) plane used for rendering. This is useful when using the Geoshape mark. For further details see the Vega-Lite documentation.

projection [ PrType Orthographic, PrRotate (-40) 0 0 ]

Properties for customising a geospatial projection that converts longitude,latitude pairs into planar (x,y) coordinate pairs for rendering and query. For details see the Vega-Lite documentation.

This type has been changed in the 0.4.0.0 release so that all constructors start with Pr rather than P (and so provide some differentiation to the PositionChannel constructors).

Types of geographic map projection. These are based on a subset of those provided by the d3-geo library. For details of available projections see the Vega-Lite documentation.

Specifies a clipping rectangle for defining the clip extent of a map projection.

Defines a set of named aggregation transformations to be used when encoding channels. This is useful when, for example, you wish to apply the same transformation to a number of channels but do not want to define it each time. For further details see the Vega-Lite documentation.

transform
    . aggregate
        [ opAs Min "people" "lowerBound", opAs Max "people" "upperBound" ]
        [ "age" ]

See also joinAggregate.

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 Mean "rating" "avYearRating" ]
        [ WGroupBy [ "year" ] ]
    . filter (FExpr "(datum.rating - datum.avYearRating) > 3"))

For details, see the Vega-Lite join aggregate documentation.

See also aggregate.

Since: 0.4.0.0

Create a named aggregation operation on a field that can be added to a transformation. For further details see the Vega-Lite documentation.

transform
    . aggregate
        [ opAs Min "people" "lowerBound"
        , opAs Max "people" "upperBound"
        ]
        [ "age" ]

Creates 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. Note though that usually it is easer to apply the temporal binning directly as part of the encoding as this will automatically format the temporal axis. See the Vega-Lite documentation for further details.

The following example takes a temporal dataset and encodes daily totals from it grouping by month:

trans = transform . timeUnitAs Month "date" "monthly"

enc = encoding
        . position X [ PName "date", PmType Temporal, PTimeUnit Day ]
        . position Y [ PAggregate Sum, PmType Quantitative ]
        . detail [ DName "monthly", DmType Temporal ]

Type of aggregation operation. See the Vega-Lite documentation for more details.

The Average constructor was removed in version 0.4.0.0; use Mean instead.

Create a named binning transformation that may be referenced in other Transformations or encodings. See the Vega-Lite documentation for more details. Note that usually, direct binning within an encoding is preferred over this form of bin transformation.

transform
    . binAs [ MaxBins 3 ] "IMDB_Rating" "ratingGroup"

Type of binning property to customise. See the Vega-Lite documentation for more details.

This is used with: binAs, DBin, FBin, HBin, MBin, OBin, PBin, and TBin.

Apply a stack transform for positioning multiple values. This is an alternative to specifying stacking directly when encoding position.

transform
    . aggregate [ opAs Count "" "count_*" ] [ "Origin", "Cylinders" ]
    . stack "count_*"
        []
        "stack_count_Origin1"
        "stack_count_Origin2"
        [ StOffset StNormalize, StSort [ WAscending "Origin" ] ]
    . window
        [ ( [ WAggregateOp Min, WField "stack_count_Origin1" ], "x" )
        , ( [ WAggregateOp Max, WField "stack_count_Origin2" ], "x2" )
        ]
        [ WFrame Nothing Nothing, WGroupBy [ "Origin" ] ]
    . stack "count_*"
        [ "Origin" ]
        "y"
        "y2"
        [ StOffset StNormalize, StSort [ WAscending "Cylinders" ] ]

Since: 0.4.0.0

How are stacks applied within a transform?

Prior to version 0.4.0.0 the StackProperty type was what is now StackOffset.

Describes the type of stacking to apply to a bar chart.

In 0.4.0.0 this was renamed from StackProperty to StackOffset, but the constructor names have not changed.

Creates a new data field based on calculations from existing fields and values.

See the Vega-Lite documentation for further details.

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

Adds the given filter operation a list of transformations that may be applied to a channel or field.

transform
    . filter (FEqual "Animal" (Str "Cat"))

Filter operations can combine selections and data predicates with BooleanOp expressions (and as of 0.4.0.0, FilterOp and FilterOpTrans can be used to lift the Filter type into boolean expressions):

transform
    . filter (FCompose (And (Expr "datum.Weight_in_lbs > 3000") (Selection "brush")))

The Vega-Lite expression documentation describes the supported format (e.g. the requirement to precede column names with "datum.").

Type of filtering operation. See the Vega-Lite documentation for details.

These can also be included into a BooleanOp expression using FilterOp and FilterOpTrans (as of version 0.4.0.0).

A pair of filter range data values. The first argument is the inclusive minimum vale to accept and the second the inclusive maximum.

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

See also flattenAs.

Since: 0.4.0.0

Similar to flatten but allows the new output fields to be named.

Since: 0.4.0.0

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 the pivot_longer and gather operations in the R tidyverse.

See also foldAs.

dvals =
    dataFromColumns []
        . dataColumn "city" (Strings [ "Bristol", "Sheffield", "Glasgow" ])
        . dataColumn "temp2017" (Numbers [ 12, 11, 7 ])
        . dataColumn "temp2018" (Numbers [ 14, 13, 10 ])

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

enc =
    encoding
        . position X [ PName "key", PmType Nominal ]
        . position Y [ PName "city", PmType Nominal ]
        . size [ MName "value", MmType Quantitative ]

Since: 0.4.0.0

A fold where the key and value fields can be renamed.

Since: 0.4.0.0

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 (like a relational join).

Unlike lookupAs, this function will only return the specific fields named in the fourth parameter. If you wish to return the entire set of fields in the secondary data source as a single object, use lookupAs.

See the Vega-Lite documentation for further details.

The following would return the values in the age and height fields from lookup_people.csv for all rows where the value in the name column in that file matches the value of person in the primary data source.

trans = transform
          . lookup "person" (dataFromUrl "data/lookup_people.csv" []) "name" ["age", "height"]

Perform an object lookup between two data sources. This allows you to find values in one data source based on the values in another (like a relational join). Unlike lookup, this function returns the entire set of field values from the secondary data source when keys match. Those fields are stored as an object with the name provided in the fourth parameter.

In the following example, personDetails would reference all the field values in lookup_people.csv for each row where the value in the name column in that file matches the value of person in the primary data source.

transform
    . lookupAs "person" (dataFromUrl "data/lookup_people.csv" []) "name" "personDetails"

If the data contained columns called age and height then they would then be accessed as personDetails.age and personDetails.height - for example:

encoding
  . position X [PName "personDetails.age", PmType Temporal, PTimeUnit Year, PTitle "Age"]
  . position Y [PName "personDetails.height", PmType Quantitative, PTitle "Height"]

See the Vega-Lite documentation for further details.

Impute missing data values.

The following example creates a value for b, set to the mean of existing b values with c=1, for the "missing" coordinate of (a=30, c=1):

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

    trans = transform
              . impute "b" "a" [ImputeProperty ImMean, ImGroupBy ["c"]]

    enc = encoding
            . position X [PName "a", PmType Quantitative]
            . position Y [PName "b", PmType Quantitative]
            . color [MName "c", MmType Nominal]

    in toVegaLite [dvals [], trans [], enc [], mark Line []]

Since: 0.4.0.0

This is used with impute and PImpute.

Since: 0.4.0.0

Imputation method to use when replacing values.

Since: 0.4.0.0