Create Vega-Lite visualizations in Haskell. It targets version 3 of the Vega-Lite specification. Note that the module does not include a viewer for these visualizations (which are JSON files), but does provide several helper functions, such as toHtmlFile, which create HTML that can be viewed with a browser to display the visualization. Other approaches include automatic display in IHaskell notebooks - with the ihaskell-vega package - or use of external viewers such as Vega View and Vega-Desktop.
It started off being a copy on an early version (2.2.1) of the Elm Vega library, which is released under a BSD3 license by Jo Wood of the giCentre at the City University of London.
This code is released under the BSD3 license.
let cars = dataFromUrl "https://vega.github.io/vega-datasets/data/cars.json"  enc = encoding . position X [ PName "Horsepower", PmType Quantitative ] . position Y [ PName "Miles_per_Gallon", PmType Quantitative ] . color [ MName "Origin", MmType Nominal ] bkg = background "rgba(0, 0, 0, 0.05)" in toVegaLite [ bkg, cars, mark Circle , enc  ]
When viewed with a Vega-Lite aware viewer, the resultant plot is
A tutorial is provided as part of the module: it is based, as is
so much of the module, on the
Elm Vega walk through.
is available on hackage - and includes the plot outputs -
and the plots it creates are also available by importing the
The Vega-Lite Example Gallery has been converted to an IHaskell notebook Unfortunately the plots created by VegaEmbed do not always appear in the notebook when viewed with either GitHub’s viewer or ipynb viewer, but things seem much better when using Jupyter Lab (rather than notebook) to create the notebooks (since Vega is natively supported in this environment). The notebooks have been re-created using Jupyter Lab (thanks to Tweag I/O’s JupyterWith environment), which should make the plots appear on GitHub (you may need to reload the notebooks as I find they don’t display on the first try).
The notebooks directory contains a poorly-curated set of examples and experiments with hvega.
Differences to Elm Vega
Elm Vega has changed significantly since I started
hvega, and no-longer
exposes data types directly but uses functions instead: for example,
PName, it uses a function like
pName. It is an open
hvega will make the same switch. Over time
the naming of certain operations or data types has diverged between
hevga and Elm Vega.
One of the more-obvious changes is that the output of
is a separate type from the input values - that is
VLSpec - since it makes it easier to display the output of
IHaskell. The JSON specification is retrieved from
this type with
For the latest version of this document, please see https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md.
Documentation fix (rendering of a URL), provided by Alexey Kuleshevich (lehins). The tests should now build without warning in GHC 8.8.1 (CPP to the rescue again!).
Avoid a build warning about importing <> from Data.Monoid in GHC 8.8.1 by using the CPP sledge-hammer. Relaxed the bounds on containers so that the tests can be built on stack LTS 9.21 (GHC 8.0.2).
Updated the tutorial, adding in a new plot to introduce the addition
of a second axis to the visualization (
Thanks to (in no order): Matthew Pickering (mpickering), Adam Conner-Sax (adamConnerSax), and Jo Wood (jwoLondon).
This is a large release, in that it greatly-improves the functionality of hvega (more-closely aligning it with version 3.4.0 of the Vega-Lite specification), but does provide a number of breaking changes (a number of functions and constructors have either been removed or had some combination of being renamed, argument types have changed, or the number of arguments has been changed). The documentation has also seen a number of additions and improvements.
A large number of functions, data types, and constructors for data
types have been added, based on version 1.12.0 (and the development
version of the next release) of the elm-vegalite module. Thanks to Jo
Wood for doing all the work! The Haddock documentation indicates new
symbols with the
since 0.4.0.0 label.
Corrected the serialization of the
datasets function, reported by
Matthew Pickering as issue
Improved the output to better-match the Vega Lite 3.4.0 specification. Note that hvega does not guarantee that it always creates valid output, in part because this would complicate the API, but also because the Vega-Lite specification is changing (e.g. I reported several issues with version 3.3.0 of the specification during development of this release, some of which have been addressed in the 3.4.0 version).
New functions, symbols, and types
The error-related types and functions discussed below are based on changes provided by Adam Conner-Sax.
toVegaLiteSchema has been added to allow you to specify a different
toVegaLite uses version 3 but version 4 is being
worked on as I type this. The
vlSchema function has been added,
vlSchema2 values. The
toHtmlFileWith functions have been added to support
more control over the embedding of the Vega-Lite visualizations, and
toHtmlXXX routines has been updated.
VLProperty type now exports its constructors, to support users
who may need to tweak or augment the JSON Vega-Lite specification
hvega (see issue
17). It has also gained
several new constructors and associated functions, which are given in
brackets after the constructor:
viewBackground). It is expected that you will be
using the functions rather the constructors!
ZIndex type has been added: this provides constructors for the
common options -
ZBack - and a fall-through (
as a protection against future changes to the Vega-Lite specification.
Four new type aliases have been added:
ZIndex. These do not provide any new functionality but do
noData function has been added to let compositions define the
source of the data (whether it is from the parent or not), and data
sources can be named with
dataName. Data can be created with
sphere. Graticules can be
NullValue type has been added to
DataValue to support data sources that are missing elements, but for
more-complex cases it is suggested that you create your data as an
Aeson Value and then use
dataFromJson. Support for data imputation
(creating new values based on existing data) has been added, as
The alignment, size, and composition of plots can be defined and
Plots can be combined and arranged with:
New functions for use in a
New functions for use with
The ability to arrange specifications has added the “flow” option
(aka “repeat”). This is seen in the addition of the
Arrangement type - which is used with
Mark type has gained
Trail constructors. The
MarkProperty type has gained
Position type has added
MarkErrorExtent type was added.
BooleanOp type has gained the
constructors which lets you use
Filter expressions as part of a
boolean operation. The
Filter type has also gained expresiveness,
Format type has gained the
DSV constructor, which allow you
to specify the separator character for column data.
The MarkChannel type has been expanded to include:
MNoTitle. The PositionChannel type has added
The LineMarker and PointMarker types have been added for use with
MPoint respectively (both from
The ability to define the binning property with
been expanded by adding the
BinProperty, as well as changing the
constructor (as described below).
StrokeJoin types has been added. These are used
StackProperty constructor has been added with the
StSort constructors. As discussed below this is a breaking change
since the old StackProperty type has been renamed to
ScaleProperty type has seen significant enhancement, by adding
Scale tye has added
SortProperty type has new constructors:
ByChannel. See the breaking-changes
section below for the constructors that were removed.
AxisProperty type has seen significant additions, including:
AxisConfig has seen a similar enhancement, and looks similar
to the above apart from the constructors do not start with ‘Ax’.
LegendConfig type has been significantly expanded and, as
discussed in the Breaking Changes section, changed. It has gained:
LegendOrientation type has gained
BaseLegendLayout types are new, and used
LeLayout to define the legent orient group.
LegendProperty type gained:
Projection has gained the
Identity constructor. The
ProjectionProperty type has gained
GraticuleProperty type was
added to configure the appearance of graticules created with
CompositionAlignment type was added and is used with
Bounds type was added for use with
ImMethod types were added for use with
ScaleConfig type has gained
SelectionProperty type has gained
The Channel type has gained:
TitleConfig type has gained:
TitleFrame type is new and used with
ViewBackground type is new and used with
ViewConfig type has gained
ConfigurationProperty type, used with
ConcatConfig type was added for use with the
FacetConfig type for the
HeaderProperty type has gained:
HyperlinkChannel type has gained
FacetChannel type has gained
TextChannel type has gained
TooltipContent type was added, for use with
Symbol type has gained:
Some of these are repeated from above.
title function now takes a second argument, a list of
values for configuring the appearance of the title.
SReverse construtor was removed from
ScaleProperty as it
represented a Vega, rather than Vega-Lite, property. The
constructors are used to change the order of an item (e.g.
ScSequential constructor was removed from
ScLinear should be used.
SortProperty type has had a number of changes: the
ByRepeat constructors have been removed, and
ByChannel constructors have been
TitleMaxLength constructors have been
AxisConfig respectively) as they
are invalid. The
AxTitleLimit (new in this release) and
TitleLimit constructors should be used instead.
AxValues constructor has been changed from
accepting a list of doubles to
constructor has been deprecated and
AxValues should be used
There have been significant changes to the
LegendConfig type: the
SymbolColor constructors have been removed;
the renaming constructors have been renamed so they all begin with
Orient is now
Orient has been added
AxisConfig); and new constructors have been added.
StackProperty type has been renamed to
StackOffset and its
constructors have changed, and a new
type has been added (that references the
Average constructor of
Operation was removed, and
should be used instead.
LEntryPadding constructor of
LegendProperty was removed.
The arguments to the
HDataCondition constructors - of
HyperlinkChannel respectively - have changed to support
accepting multiple expressions.
MarkOrientation type has been renamed
The constructors of the
ViewConfig type have been renamed so they
all begin with
View (to match
The constructors of the
ProjectionProperty type have been renamed
so that they begin with
Pr rather than
P (to avoid conflicts
Divide constructor of
BinProperty now takes a list of
Doubles rather than two.
TitleConfig type has gained the following constructors:
type was added for use with
ArgMin constructors of
Operation now take an
optional field name, to allow them to be used as part of an encoding
aggregation (e.g. with
The “z index” value has changed from an ‘Int’ to the ‘ZIndex’ type.
The constructors for the
Symbol type now all start with
Path have been
Legend type has been renamed
LegendType and its constructors
have been renamed ‘GradientLegend’ and ‘SymbolLegend’.
Added a test suite based on the Elm Vega-Lite tests (based entirely on the work of Jo Wood).
The IPython notebooks have been expanded to cover recent changes in the Vega-Lite gallery, and include validation of the output (to check against the expected output).
The minimum base version has been bumped from 4.7 to 4.9, which means ghc 8.0 or later. This is because the 0.2.0.1 release does not appear to build with ghc 7.10. If this restriction is a problem then please comment on the issues list.
There have been minor documentation updates, adding
Channel type has been extended to include
constructors and the
tooltips function allows you to provide
multiple tooltips for a channel. The schema version has been changed
from 2 to 3, but there has been limited checking to see if the API
correctly reflects the new schema.
This functionality was provided by Adam Massmann (massma) and BinderDavid.
This functionality was provided by Gregory Schwartz; apologies for taking so long to get it released.
The constructors for the LegendOrientation type have been renamed (by
adding the prefix
LO) which avoids the name clash with
seen in earlier releases. This is a breaking API change.
Clarify how to use the library in the main
Thanks to contributions from Nicolas Mattia (nmattia) and Marco Zocca (ocramz).
The only change is to the cabal file, where
cabal-version: >=1.18 has
been changed to
Updated the upper bounds of
aeson to really allow v1.4. This was not
released on Hackage.
Updated the upper bounds of
aeson from v1.2 to v1.4.
The cabal package now includes
the latter is not guaranteed to be correct), as well as a
change log and an extra image.
This is the initial version of
hvega, which is based on
version 2.2.1 of the
Elm Vega library.