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 4 of Vega-Lite, and please report an issue if you find a problem with the output of hvega. 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 vlSchema3 props

Note that the schema is only used to fill in the "$schema" field of the JSON structure. It does not change the JSON encoding of the visualization.

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.

Alpha and Beta releases can be specified by setting the last argument; for instance to get the "beta.0" version of version 4 you would use

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

whereas

vlSchema 4 Nothing Nothing Nothing

refers to the latest release of version 4.

Obtain the Vega-Lite JSON (i.e. specification) for passing to a Vega-Lite 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, heightStep, width, widthStep, 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 an encoding (input to encoding).

It is expected that routines like position and color are used to create values with this type, but they can also be constructed and deconstructed manually with toEncodingSpec and fromEncodingSpec.

Since: 0.5.0.0

This function is provided in case there is any need to inject JSON into the Vega-Lite document that hvega does not support (due to changes in the Vega-Lite specification or missing functionality in this module). If you find yourself needing to use this then please report an issue.

See also fromEncodingSpec.

Since: 0.5.0.0

Extract the contents of an encoding specification. This may be needed when the Vega-Lite specification adds or modifies settings for a particular encoding, and hvega has not been updated to reflect this change. If you find yourself needing to use this then please report an issue.

See also toEncodingSpec.

Since: 0.5.0.0

Represent a transformation (input to transform).

It is expected that routines like calculateAs and filter are used to create values with this type, but they can also be constructed and deconstructed manually with toTransformSpec and fromTransformSpec.

Since: 0.5.0.0

This function is provided in case there is any need to inject JSON into the Vega-Lite document that hvega does not support (due to changes in the Vega-Lite specification or missing functionality in this module). If you find yourself needing to use this then please report an issue.

See also fromTransformSpec.

Since: 0.5.0.0

Extract the contents of a transformation specification. This may be needed when the Vega-Lite specification adds or modifies settings for a particular encoding, and hvega has not been updated to reflect this change. If you find yourself needing to use this then please report an issue.

See also toTransformSpec.

Since: 0.5.0.0

Represent a set of resolution properties (input to resolve).

It is expected that resolution is used to create values with this type, but they can also be constructed and deconstructed manually with toResolveSpec and fromResolveSpec.

Since: 0.5.0.0

This function is provided in case there is any need to inject JSON into the Vega-Lite document that hvega does not support (due to changes in the Vega-Lite specification or missing functionality in this module). If you find yourself needing to use this then please report an issue.

See also fromResolveSpec.

Since: 0.5.0.0

Extract the contents of an resolve specification. This may be needed when the Vega-Lite specification adds or modifies settings for a particular resolve, and hvega has not been updated to reflect this change. If you find yourself needing to use this then please report an issue.

See also toResolveSpec.

Since: 0.5.0.0

Represent a set of resolution properties (input to selection).

It is expected that select is used to create values with this type, but they can also be constructed and deconstructed manually with toSelectSpec and fromSelectSpec.

Since: 0.5.0.0

This function is provided in case there is any need to inject JSON into the Vega-Lite document that hvega does not support (due to changes in the Vega-Lite specification or missing functionality in this module). If you find yourself needing to use this then please report an issue.

See also fromSelectSpec.

Since: 0.5.0.0

Extract the contents of a select specification. This may be needed when the Vega-Lite specification adds or modifies settings for a particular select, and hvega has not been updated to reflect this change. If you find yourself needing to use this then please report an issue.

See also toSelectSpec.

Since: 0.5.0.0

Represent a set of configuration properties (input to configuration).

It is expected that configuration is used to create values with this type, but they can also be constructed and deconstructed manually with toConfigureSpec and fromConfigureSpec.

Since: 0.5.0.0

This function is provided in case there is any need to inject JSON into the Vega-Lite document that hvega does not support (due to changes in the Vega-Lite specification or missing functionality in this module). If you find yourself needing to use this then please report an issue.

See also fromConfigureSpec.

Since: 0.5.0.0

Extract the contents of a configuration specification. This may be needed when the Vega-Lite specification adds or modifies settings for a particular configure, and hvega has not been updated to reflect this change. If you find yourself needing to use this then please report an issue.

See also toConfigureSpec.

Since: 0.5.0.0

Represent the functions that can be chained together and sent to encoding.

Since: 0.5.0.0

Represent the functions that can be chained together and sent to transform.

Since: 0.5.0.0

Represent the functions that can be chained together and sent to resolve.

Since: 0.5.0.0

Represent the functions that can be chained together and sent to selection.

Since: 0.5.0.0

Represent the functions that can be chained together and sent to configure.

Since: 0.5.0.0

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

A blank string is converted to the JSON null value (new in 0.5.0.0).

Since: 0.4.0.0

The dash style for a line. This is defined as a series of on and then off lengths, in pixels. So [10, 4, 5, 2] means a long line, followed by a space, then a line half as long as the first segment, and then a short space. This pattern is then repeated.

This is a convenience type annotation and there is no validation of the input.

Since: 0.5.0.0

The offset at which to start drawing the line dash (given by a DashStyle argument), in pixels.

This is a convenience type annotation and there is no validation of the input.

Since: 0.5.0.0

The field name. This can include "dotted" notation, such as "o.latitude".

There is no attempt to validate this value (e.g. check it is not empty, contains only valid characters, or remove excess whitespace).

Since: 0.5.0.0

Convenience type-annotation to label a normalized coordinate for color gradients. The value should be in the range 0 to 1, inclusive. There is no attempt to validate that the number lies within this range.

Since: 0.5.0.0

Convenience type-annotation label to indicate the color interpolation points - i.e. the colors to use at points along the normalized range 0 to 1 (inclusive).

The list does not have to be sorted. There is no check that the color is valid (i.e. not empty or a valid color specification).

Since: 0.5.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

Convenience type-annotation label to indicate the name, or label, of a selection. It is expected to be a non-empty string, but there is no attempt to validate this.

Since: 0.5.0.0

Convenience type-annotation to indicate a name, or label, that represents a set of mark or axis styles. The styles are generated with AxisNamedStyles and MarkNamedStyles, and used with constructs such as AStyle, AxStyle, MStyle, and TStyle.

Since: 0.6.0.0

Convenience type-annotation label to indicate a Vega Expression. There is no attempt to validate the expression.

Examples include:

"datum.IMDB_Rating != null"
"datum.height / 1000"
"if(datum.index % 2 == 1, datum.label, '')"
"sampleLogNormal(2.3, 0.3)"

Since: 0.5.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

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 4, 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 are: aggregate, binAs, calculateAs, density, filter, flatten, flattenAs, fold, foldAs, impute, joinAggregate, loess, lookup, lookupAs, lookupSelection, pivot, quantile, regression, sample, 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).