hvega
Create Vega-Lite visualizations (version 4) in Haskell.
https://github.com/DougBurke/hvega
LTS Haskell 22.43: | 0.12.0.7 |
Stackage Nightly 2024-12-09: | 0.12.0.7 |
Latest on Hackage: | 0.12.0.7 |
hvega-0.12.0.7@sha256:c53272ed98f6c1926d8202cc1b0e13c6778c613718fcd1950f8accd4d9c1dc13,11152
Module documentation for 0.12.0.7
- Graphics
- Graphics.Vega
- Graphics.Vega.Tutorials
- Graphics.Vega.VegaLite
- Graphics.Vega
hvega
Create Vega-Lite visualizations in Haskell. It targets version 4.15 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.
Examples
Cars
The Vega-Lite example gallery contain
a number of visualizations of the cars.json
dataset, which has a number of
columns to display, such as “Horsepower”, “Miles_per_Gallon”, and “Origin”. The
following code will create a visualization that plots the efficiency of the
cars (the “mpg”) as a function of its Horsepower, and color-code by the
origin of the car:
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, PTitle "Miles per Gallon" ]
. color [ MName "Origin" ]
bkg = background "rgba(0, 0, 0, 0.05)"
in toVegaLite [ bkg, cars, mark Circle [MTooltip TTEncoding], enc [] ]
When the JSON is viewed with a Vega-Lite aware viewer, the resultant plot can be interacted with (e.g. to use the tooltip support) using the interactive version. It can also be viewed as a PNG:
Betelgeuse
In late 2019 and early 2020 the star Betelgeuse - a member of the constellation Orion - dimmed enough that you could see it. Betelgeuse is a member of the class of Red Supergiant stars, which are massive enough that they will go supernova at some point, and so there was some speculation that we could see a “naked-eye” supernova (even though the current models suggest that Betelgeuse has about 100,000 more years to go before this happens, and the rapid brightening in mid 2023 has also got some people’s hopes up). This interest lead to a lot of observations added to the American Association of Variable Star Observers database, which we are going to look at below. This example is rather-more involved than the case one, since it involves data filtering and creation, multiple plots, faceting, and interactive selection.
let titleStr = "Betelegeuse's magnitude measurements, collated by AAVSO"
w = width 600
h = height 150
pos1Opts fld ttl = [PName fld, PmType Quantitative, PTitle ttl]
x1Opts = pos1Opts "days" "Days since January 1, 2020"
y1Opts = pos1Opts "magnitude" "Magnitude" ++ [PSort [Descending], yRange]
yRange = PScale [SDomain (DNumbers [-1, 3])]
filtOpts = [MName "filterName"]
filtEnc = color (MLegend [ LTitle "Filter", LTitleFontSize 16, LLabelFontSize 14 ] : filtOpts)
. shape filtOpts
circle = mark Point [ MOpacity 0.5, MFilled False ]
encOverview = encoding
. position X x1Opts
. position Y y1Opts
. filtEnc
selName = "brush"
pos2Opts fld = [PName fld, PmType Quantitative, PNoTitle,
PScale [SDomainOpt (DSelectionField selName fld)]]
x2Opts = pos2Opts "days"
y2Opts = pos2Opts "magnitude" ++ [PSort [Descending]]
encDetail = encoding
. position X x2Opts
. position Y y2Opts
. filtEnc
xlim = (Number (-220), Number 100)
ylim = (Number (-0.5), Number 2.5)
overview = asSpec [ w
, h
, encOverview []
, selection
. select selName Interval [ Encodings [ChX, ChY]
, SInitInterval (Just xlim) (Just ylim)
]
$ []
, circle
]
detailPlot = asSpec [ w
, h
, encDetail []
, circle
]
headerOpts = [ HLabelFontSize 16
, HLabelAlign AlignRight
, HLabelAnchor AEnd
, HLabelPadding (-24)
, HNoTitle
, HLabelExpr "'Filter: ' + datum.label"
]
details = asSpec [ columns 1
, facetFlow [ FName "filterName"
, FHeader headerOpts
]
, spacing 10
, specification detailPlot
]
in toVegaLite [ title titleStr [ TFontSize 18 ]
, dataFromUrl "https://raw.githubusercontent.com/DougBurke/hvega/master/hvega/data/betelgeuse-2020-03-19.json" []
, transform
. filter (FExpr "datum.filterName[0] === 'V'")
. filter (FExpr "datum.magnitude < 4")
. calculateAs "datum.jd - 2458849.0" "days"
$ []
, vConcat [overview, details]
, configure
. configuration (Axis [ TitleFontWeight Normal, TitleFontSize 16, LabelFontSize 14 ])
$ []
]
This can be viewed as
-
as a PNG:
Documentation
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.
The tutorial
is available on hackage - and includes the plot outputs -
and the plots it creates are also available by importing the
Graphics.Vega.Tutorials.VegaLite
module.
The
Vega-Lite Example Gallery has
been converted to IHaskell notebooks in the
notebooks directory.
Start with the
overview notebook,
which describes the set up, and then the individual
sections have their own notebooks (with names of
VegaLiteGallery-<section>.ipynb
.
It is strongly advised that you stick with jupyter notebook
rather than jupyter lab
, since the 0.3 release of ihaskell-hvega
provides much better support for the former than the latter.
The notebooks have been created using Jupyter Lab (thanks to Tweag I/O’s JupyterWith environment).
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,
rather than PName
, it uses a function like pName
. It is an open
question whether 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 toVegaLite
is a separate type from the input values - that is VegaLite
and VLSpec
- since it makes it easier to display the output of
hvega
in IHaskell
. The JSON specification is retrieved from
this type with fromVL
. The 0.5.0.0
release adds some more
type safety (restricting the functions that can be applied
to encoding
and transform
for instance).
Changes
For the latest version of this document, please see https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md.
0.12.0.7
Bump to support containers version 0.7.
0.12.0.6
Bump to support text version 2.1. This appears to have been un-released, so is a secret just between you and I.
0.12.0.5
Bump to support bytestring version 0.12.0.0 (only needed if building the tests).
0.12.0.4
Bump to support aeson version 2.2 (tests may require building with the –allower-newer=aeson option).
0.12.0.3
Bump to support aeson version 2.1.
0.12.0.2
Bump to support text version 2.0. All hail our new UTF-8 rulers.
0.12.0.1
Bump to support bytestring version 0.11 for testing hvega
. There
are no changes to the code.
0.12.0.0
Support aeson version 2.0. There is currently no significant change to the API but it is expected that in a future release there will be when we wil require a minimum version of 2.0 for aeson.
At the time of release of 0.12.0.0 the tests will fail when using
aeson >= 2.0 because aeson-pretty
has not yet been updated (see
https://github.com/informatikr/aeson-pretty/issues/36).
0.11.0.1
There is no change in the code, only the tests, which should now pass when using hashable 0.3.1.0.
0.11.0.0
The Vega-Lite tests are now validated against version 4.15 of the Vega-Lite schema.
Note that hvega
does not provide any information to help users
take advantage of the (new to 4.14) ability to omit the type of a
field when it can be inferred.
As the type is currently optional in hvega
users can just not give a type.
The example IHaskell notebooks
have been updated to show off the optional support.
Similarly, Vega-Lite 4.14 allows you to share the type, scale, axis,
and legend in a shared encoding. There is no explicit support added in
0.11.0.0 because hvega
already allowed you to create the specification.
New Constructors
The OrderChannel
type has gained OBand
, OTitle
/ONoTitle
,
and conditional-predicate support with ODataCondition
,
OSelectionCondition
, and ONumber
constructors.
The MarkChannel
type has gained the MNullValue
constructor.
The ScaleRange
type has gained RField
, RMax
, and RMin
constructors.
Breaking Changes
Domain settings in ScaleProperty
and associated types have been
changed to better match the Vega-Lite schema: SDomain
now takes
a new type (DomainLimits
) which actually contains many of the
orignal symbols (so hopefully will require no changes), and a new
constructor has been added (SDomainOpt
) which takes the
ScaleDomain
type, which has seen new constructors - DMax
,
DMaxTime
, DMid
, DMin
, and DMinTime
- as well as
some constructors moving to DomainLimits
.
Deprecated symbols
The SDomainMid
constructor of ScaleProperty
will be removed in a
future release as it has been replaced by the DMid
constructor
in ScaleDomain
.
0.10.0.0
The Vega-Lite tests are now validated against version 4.13 of the Vega-Lite schema.
Breaking Changes
The handling of time units (for both TimeUnit
and ScaleNice
) has
changed. The contents of these types have been split into two parts: a
“time unit” and the options that get applied to it (rather than having
a single type that combines both functions). This does mean that
setting time units has now become more verbose, but it has stopped
some problem cases (and, in the case of ScaleNice
, fixed a logical
error on my part). The new time units are BaseTimeUnit
and
NTimeUnit
, and contain the “basic” constructors for the time
units. The TimeUnit
and ScaleNice
constructors now reference these
types rather than include them in their definition, so that PTimeUnit Month
has been changed to PTimeUnit (TU Month)
and SNice NMinute
has changed to SNice (NTU NMinute)
.
The BaseTimeUnit
type has seen a number of additions: the Week
and
DayOfYear
time units added in Vega-Lite 4.13.0, along with the
associated composite units (such as YearWeek
), and a number of
composite types that were missing (such as MonthDateHours
). The
DateTime
type has added the DTWeek
and DTDayOfYear
constructors.
0.9.1.0
The tutorial has been expanded to add a section describing the new pie chart support (the Arc mark).
0.9.0.1
The introductory text of the module has been updated to start with the “cars” example (from the README) before rampng up to the Betelgeuse example.
0.9.0.0
The Vega-Lite tests are now validated against version 4.12 of the Vega-Lite schema.
New Constructors
Support for arcs has been added: the Arc
type has been added to
Mark
; Theta
, Theta2
, R
, and R2
have been added to
Position
; and MInnerRadius
, MOuterRadius
, MPadAngle
,
MRadius2
, MRadiusOffset
, MRadius2Offset
, MTheta2
,
MThetaOffset
, and MTheta2Offset
added to MarkProperty
.
ArcStyle
has been added to ConfigurationProperty
.
Support for ARIA attributes has been added to a number of features
(e.g. Aria
and AriaDescription
for AxisConfig
and MAria
,
MAriaDescription
, MAriaRole
, MAriaRoleDescription
for
MarkProperty
, AriaStyle
for ConfigurationProperty
). The
ariaDescrption
encoding has been added, along with the
AriaDescriptionChannel
.
The angle
encoding channel has been added for text and point marks.
The Channel
type has gained ChAngle
, ChTheta
, ChTheta2
,
ChRadius
, ChRadius
, ChDescription
, and ChURL
.
Layers have been added to Arrangement
(Layer
) and to RepeatFields
(LayerFields
).
The MRepeatDatum
and MDatum
, PRepeatDatum
and PDatum
, and
TRepeatDatum
and TDatum
pairs have been added to MarkChannel
,
PositionChannel
, and TextChannel
respectively.
The MarkProperty
now has support for labelling the X (or X2)
coordinate as the “width” of the plot and Y (or Y2) as the “height” of
the plot. See MXWidth
, MX2Width
, MYHeight
, and MY2Height
.
Improved support for tick scales: TickCount
and TickCountTime
have
been added to AxisConfig
, AxTickCountTime
has been added to
AxisProperty
, LTickCountTime
has been added to LegendProperty
,
and LeTickCountTime
has been added to LegendConfig
.
Add support for width and height to scale’s range, with the RHeight
and
RWidth
constructors. The RPair
constructor has been added as an
experimental means for specifying just the minimum and maximum values.
AxisProperty
has gained AxFormatAsCustom
. AxisConfig
has gained
Format
, FormatAsNum
, FormatAsTemporal
, and FormatAsCustom
.
LegendProperty
has gained LFormatAsCustom
. HeaderProperty
has
gained HFormatAsCustom
. TextChannel
has gained TFormatAsCustom
.
The ConfigurationProperty
type has a new option to configure support
for custom format types (CustomFormatStyle
).
AxisConfig
and AxisProperty
have gained new cap styles:
DomainCap
, GridCap
, TickCap
and AxDomainCap
, AxGridCap
,
AxTickCap
respectively.
The TZIndex
option of TitleConfig
can now be used with TitleStyle
(prior to Vega-Lite 4.12 it was only supported when used with
title
). The LeZIndex
type has been added to LegendConfig
.
The HyperlinkChannel
has gained a number of constructors it was
missing: HyBand
, HyFormat
, HyFormatAsNum
, HyFormatAsTemporal
,
HyFormatAsCustom
, HyLabelExpr
, HyTitle
, and HyNoTitle
. A
similar update has been made to TextChannel
, which has gained
TBand
and TLabelExpr
.
0.8.0.0
The Vega-Lite tests are now validated against version 4.8 of the Vega-Lite Sschema.
The RepeatStyle
constructor for ConfigurationProperty
should not
be used, as its functionality has been moved to ConcatStyle
in
Vega-Lite 4.8. This constructor will be removed at some point in the
future but is still available (as support for Vega-Lite 4.8 is
limited).
Breaking Changes
The HTitleFontWeight
constructor (a member of HeaderProperty
)
now takes a FontWeight
argument rather than Text
.
The LeTitle
constructor from LegendConfig
was removed as it is not
supported in Vega-Lite (LeNoTitle
remains, as it is used to remove
legend titles from a visualization).
ScBinLinear
was removed from Scale
as it is not used by Vega-Lite.
New constructors
The HeaderProperty
type has gained the following constructors from
Vega-Lite 4.8: HLabelBaseline
, HLabelFontWeight
,
HLabelLineHeight
, and HOrient
.
The AxisConfig
type has gained the Disable
constructor from
Vega-Lite 4.8.
The LegendConfig
type has gained the LeDirection
and (from
Vega-Lite 4.8) LeDisable
constructors. The LegendProperty
type has
gained LLabelExpr
, LSymbolLimit
, and LTitleLineHeight
constructors.
0.7.0.1
Minor documentation fixes (typos and fixing links).
0.7.0.0
The Vega-Lite tests are now validated against version 4.7 of the Vega-Lite schema.
New functionality
The BlendMode
type has been added for controlling how marks blend
with their background. This is used with the new MBlend
constructor
for marks.
Breaking Change
The axis style options for specific data- or mark- types (AxisBand
,
AxisDiscrete
, AxisPoint
, AxisQuantitative
, and AxisTemporal
)
have been changed to accept an additional argument (the new
AxisChoice
type) which defines which axis (X, Y, or both) the
configuration should be applied to. This is to support new axis
configuration options added in Vega-Lite 4.7.0.
The ChTooltip
Channel
constructor has been removed as support
for this channel type was dropped in Vega-Lite 4.
New constructors
The ScaleDomain
type has gained DSelectionField
and
DSelectionChannel
constructors, which allow you to link a scale
(e.g. an axis) to a selection that is projected over multiple fields
or encodings.
The Operation
type has gained the Product
specifier from Vega-Lite
4.6.0.
The TextChannel
has gained TStrings
to support multi-line labels.
The VAlign
type has gained AlignLineTop
and AlignLineBottom
(Vega-Lite 4.6.0).
LineBreakStyle
has been added to ConfigurationProperty
.
The height of multi-line axis labels can now be set with the
LabelLineHeight
and AxLabelLineHeight
properties of the
AxisConfig
and AxisProperty
types (Vega-Lite 4.6.0).
Numeric filter ranges, specified with FRange
, can now be lower- or
upper-limits - NumberRange
and NumberRange
respectively - added to
the FilterRange
type.
0.6.0.0
The Vega-Lite tests are now validated against version 4.5 of the Vega-Lite schema.
New functionality
New function for use with encoding
: strokeDash
. The ChStrokeDash
constructor has been added to the Channel
type, and RNumberLists
(Vega-Lite 4.4) to ScaleRange
.
Named styles have been added for axes as well as marks. As mentioned
below, this involves deprecating the previous constructors for naming
styles, as there are now separate configuration options:
AxisNamedStyles
and MarkNamedStyles
. The AStyle
and AxStyle
options have been added to AxisConfig
and AxisProperty
respectively. The StyleLabel
type alias has been added to help the
documentation, but provides no extra type safety.
Breaking changes
The ConcatStyle
and FacetStyle
constructors for
ConfigurationProperty
now accept a common type,
CompositionConfig
, rather than having separate
ConcatConfig
and FacetConfig
types with the same meaning.
So ConcatColumns
and FColumns
have been replaced by CompColumns
,
and CompSpacing
and FSpacing
by CompSpacing
.
The ViewFill
and ViewStroke
constructors of ViewConfig
no longer
take an optional Color
argument. The Nothing case has been replaced
by new constructors: ViewNoFill
and ViewNoStroke
.
The VBFill
and VBStroke
constructors of ViewBackground
no longer
take an optional Color
argument. The Nothing case has been replaced
by new constructors: VBNoFill
and VBNoStroke
.
New constructors
FacetChannel
has gained the following constructors: FAlign
,
FCenter
, and FSpacing
. The last one would have collides with
the FacetStyle
option, but this has fortuitously been renamed to
CompSpacing
.
MSymbol
has been added to MarkChannel
which can be used to make the
shape
encoding conditional on a data or selection condition.
The TUStep
and TUMaxBins
constructors have been added to TimeUnit
for controlling how time values are binned.
The MarkProperty
type has gained the MCornerRadiusEnd
constructor,
which is used to draw rounded histogram bars, and MTexts
for
specifying multiple text values.
Error box and band properties (constructors in MarkProperty
) can now
be turned off with explicit No
variants: MNoBorders
, MNoBox
,
MNoMedian
, MNoRule
, and MNoTicks
. These join the MNoOutliers
constructor.
The ScaleProperty
type has gained SDomainMid
, useful for
asymmetric diverging color scales, and SReverse
from Vega-Lite v4.5.
The ScaleDomain
type has gained the DUnionWith
option from
Vega-Lite v4.3. The ScaleConfig
type has gained SCXReverse
from Vega-Lite v4.5.
Labels can now be vertically aligned to their baseline with the
AlignBaseline
constructor of the VAlign
type.
Headers (HeaderProperty
) have gained the following constructors:
HLabel
, HLabelExpr
, HLabelFontStyle
, HTitleFontStyle
,
and HTitleLineHeight
.
Conditional axis (ConditionalAxisProperty
) has gained the following
constructors for features added in Vega-Lite v4.2 and v4.5:
CAxLabelOffset
, CAxLabelPadding
, and CAxTickSize
.
Cursor handling has been enhanced (to match Vega-Lite 4.1):
ViewCursor
has been added to ViewConfig
and SMCursor
to
SelectionMarkProperty
.
The legend configuration has been updated (to match Vega-Lite 4.0)
with the addition of LeSymbolLimit
, LeTickCount
, LeTitleLineHeight
,
and LeUnselectedOpacity
constructors.
The axis configuration and property types (AxisConfig
and
AxisProperty
) have gained the Vega-Lite 4.4 LabelOffset
and
AxLabelOffset
constructors. Note that version 4.4.0 of the
Vega-Lite specification has these fields as strings but this is fixed
in version 4.5.0.
ConfigurationProperty
has added new constructors: AxisDiscrete
and
AxisPoint
from Vega-Lite 4.5, AxisQuantitative
and AxisTemporal
from Vega-Lite 4.4, BoxplotStyle
, ErrorBandStyle
, ErrorBarStyle
,
FontStyle
(Vega-Lite 4.3), HeaderColumnStyle
, HeaderFacetStyle
,
HeaderRowStyle
, ImageStyle
, and RepeatStyle
.
Deprecated symbols
ConfigurationProperty
has seen a large number of deprecations, as a
number of constructors have been renamed:
-
The
NamedStyle
andNamedStyles
have been replaced byMarkNamedStyles
; -
Autosize
,Background
,CountTitle
,FieldTitle
,Legend
,NumberFormat
,Padding
,Projection
,Range
,Scale
,TimeFormat
, andView
constructors have been replaced byAutosizeStyle
,BackgroundStyle
,CountTitleStyle
,FieldTitleStyle
,LegendStyle
,NUmberFormatStyle
,PaddingStyle
,ProjectionStyle
,RangeStyle
,ScaleStyle
,TimeFormatStyle
,ViewStyle
respectively.
0.5.0.0
Update to version 4.0 of the Vega-Lite specification (tested against version 4.0.2). There are several changes in default behavior due to this (tooltips are now disabled by default, the background now defaults to white rather than transparent), although this is also controlled by how the Vega-Lite visualization is rendered, which can make tracking down why something has changed a bit awkward.
There is more-extensive use of type aliases, such as Color
,
and the introduction of several more (e.g. DashStyle
and FieldName
).
These do not add any type safety, but help the documentation (as they provide
a single place to explain the meaning and any constraints on a
particular value). There are some changes that do improve type safety,
discussed in the “Breaking changes” section below.
Documentation improvements, including a new section in the tutorial on choropleths contributed by Adam Conner-Sax, and plots using an Aitoff projection contributed by Jo Wood.
New functionality
Title (and subtitle) strings can now be split across multiple lines: use ‘\n’ to indicate a line break.
Colors are now stripped of extraneous white space, and if empty converted to the JSON null value rather than an empty string.
The pivot
transform has been added, along with the PivotProperty
preferences type. This is the inverse of fold
.
The density
transform has been added, along with the DensityProperty
configuration type, to support kernel density estimation (e.g. to
generate a continuous distribtion from a discrete one).
The loess
transform has been added, along with the LoessProperty
configuration type, to support scatterplot smoothing.
The regression
transform has been added, along with the RegressionProperty
and RegressionMethod
configuration types, to support regression
analysis.
The quantile
transform has been added, along with the QuantileProperty
type, to support quantile analysis.
The url
encoding has been added, which allows you to view images (e.g.
PNG) via the (new) Image
mark type. The MAspect
MarkProperty
has
been added as a configuration option.
The lookupSelection
transform has been added to support joining
data via a selection. The SelectionLabel
type alias has been added
to help the documentation.
The heightOfContainer
and widthOfContainer
functions
have been added to support responsive sizing, although I have not had
much success in getting them to work!
The tooltip
encoding will now turn off tooltips if given an empty
list (although note that tooltips are now off by default in Vega-Lite 4).
Breaking changes
The combineSpecs
function has been removed.
In an attempt to provide some type safety, the encoding
,
transform
, resolve
, selection
, and configure
functions now
take specialised types (EncodingSpec
, TransformSpec
,
ResolveSpec
, SelectSpec
, and ConfigureSpec
respectively) rather
than the generic LabelledSpec
type. Simple visualizations should
remain unchanged, but helper functions may need to have their type
signatures updated.
The lookup
transform has been changed so that the list of fields
stored when the keys match is now specified by the LookupFields
type (rather than a list of field names). This supports providing
aliases and handling of default values, and now subsumes the lookupAs
encoding, which has been marked as deprecated.
The RemoveInvalid
constructor has removed from ConfigurationProperty
,
and has been replaced by the MRemoveInvalid
constructor of
MarkProperty
. The Stack
constructor was removed.
The SRangeStep
constructor from ScaleProperty
has been removed.
The widthStep
and heightStep
functions should be used instead.
The ViewWidth
and ViewHeight
constuctors of ViewConfig
have
been replaced by ViewContinuousWidth
, ViewContinuousHeight
,
ViewDiscreteWidth
, and ViewDiscreteHeight
(well, the symbols
remain but have been deprecated for the continous-named versions).
The SCRangeStep
and SCTextXRangeStep
constructors of ScaleConfig
have been removed. The new ViewStep
constructor of ViewConfig
should be
used as a replacement.
The ShortTimeLabels
, LeShortTimeLabels
, and MShortTimeLabels
constructors - from AxisConfig
, LegendConfg
, and MarkProperty
respectively - have been removed.
New constructors
This section does not repeat names mentioned above.
AxisProperty
has gained the AxDataCondition
constructor for
marking a subset of axis properties as being conditional on their
position, and the ConditionalAxisProperty
for defining which
properties (grid, label, and tick) can be used in this way. It has
also gained the AxLabelExpr
constructor, which allows you to
change the content of axis labels, AxTickBand
for positioning the
labels for band scales (and the associated BandAlign
type),
AxTitleLineHeight
to specify the line height, and AxTranslateOffset
for applying a translation offset to the axis group.
AxisConfig
has gained TickBand
, TitleLineHeight
, and
TranslateOffset
, matching the additions to AxisProperty
.
The ViewBackgroundStyle
constructor has been added to ViewConfig
.
The TitleConfig
type gained the following constructors:
TAlign
, TdX
, TdY
, TLineHeight
, TSubtitle
, TSubtitleColor
,
TSubtitleFont
, TSubtitleFontSize
, TSubtitleFontStyle
,
TSubtitleFontWeight
, TSubtitleLineHeight
, and TSubtitlePadding
.
Added AFitX
and AFitY
constructors to the Autosize
type.
The SelectionProperty
type has gained the BindLegend
constructor,
and the associated BindLegendProperty
type, to allow selection of
a legend (categorical data only).
The TextChannel
type has gained the TString
constructor, which
lets you specify the text content as a literal.
Two new projections - EqualEarth
and NaturalEarth1
- have been
added to the Projection
type.
Support for color gradients has been added for marks via the
MColorGradient
, MFillGradient
, and MStrokeGradient
constructors of
MarkProperty
, along with the new ColorGradient
and
GradientProperty
types for defining the appearance of the
gradient. The GradientCoord
and GradientStops
type aliases
have also been added (although they provides no type safety).
The MCornerRadius
, MCornerRadiusTL
, MCornerRadiusTR
, MCornerRadiusBL
,
and MCornerRadiusBR
constructors have been added to MarkProperty
to
set the corner radii of rectangular marks.
The MDir
, MEllipsis
, and MLimit
constructors have been added to
MarkProperty
to control how text is truncated. The TextDirection
type
has been added for use with MDir
.
The MarkProperty
type has gained MLineBreak
and MLineHeight
constructors
for controlling how multi-line labels are displayed. Note that hvega
will
always split on the newline character (\n
), which will over-ride the
MLineBreak
setting.
The DTMonthNum
and DTDayNum
constructors have been added to DateTime
.
The BinProperty
type has gained the SelectionExtent
constructor, for defining a bin range via an interval selection.
The PositionChannel
type has gained the PBand
constructor,
for defining the size of a mark relative to a band, and MarkProperty
has added MTimeUnitBand
and MTimeUnitBandPosition
.
Bug fixes
The selection property SInitInterval Nothing Nothing
is now a
no-op (as it does nothing), rather than generating invalid JSON.
The following options or symbols generated incorrect JSON output:
ONone
, LSymbolStrokeWidth
, LeLabelOpacity
.
0.4.1.2
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!).
0.4.1.1
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).
0.4.1.0
Updated the tutorial, adding in a new plot to introduce the addition
of a second axis to the visualization (parallaxBreakdown
).
0.4.0.0
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.
Bug fixes
Corrected the serialization of the datasets
function, reported by
Matthew Pickering as issue
29.
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
Vega-Lite schema. toVegaLite
uses version 3 but version 4 is being
worked on as I type this. The vlSchema
function has been added,
along with vlSchema4
, vlSchema3
, and vlSchema2
values. The
toHtmlWith
and toHtmlFileWith
functions have been added to support
more control over the embedding of the Vega-Lite visualizations, and
the versions of the required Javascript libraries used by the
toHtmlXXX
routines has been updated.
The VLProperty
type now exports its constructors, to support users
who may need to tweak or augment the JSON Vega-Lite specification
created by hvega
(see issue
17). It has also gained
several new constructors and associated functions, which are given in
brackets after the constructor: VLAlign
(align
); VLBounds
(bounds
); VLCenter
(center
, centerRC
); VLColumns
(columns
); VLConcat
(vlConcat
); VLSpacing
(alignRC
,
spacing
, spacingRC
); VLUserMetadata
(usermetadata
); and
VLViewBackground
(viewBackground
). It is expected that you will be
using the functions rather the constructors!
The ZIndex
type has been added: this provides constructors for the
common options - ZFront
and ZBack
- and a fall-through (ZValue
)
as a protection against future changes to the Vega-Lite specification.
Four new type aliases have been added: Angle
, Color
, Opacity
,
and ZIndex
. These do not provide any new functionality but do
document intent.
The 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
dataSequence
, dataSequenceAs
, and sphere
. Graticules can be
created with graticule
. The 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
discussed below.
The alignment, size, and composition of plots can be defined and
changed with align
, alignRC
, bounds
, center
, centerRC
,
columns
, spacing
, and spacingRC
.
Plots can be combined and arranged with: facet
, facetFlow
,
repeat
, repeatFlow
, and vlConcat
New functions for use in a transform
: flatten
, flattenAs
,
fold
, foldAs
, impute
, and stack
.
New functions for use with encoding
: fillOpacity
, strokeOpacity
,
strokeWidth
,
The ability to arrange specifications has added the “flow” option
(aka “repeat”). This is seen in the addition of the Flow
constructor
to the Arrangement
type - which is used with ByRepeatOp
,
HRepeat
, MRepeat
, ORepeat
, PRepeat
, and TRepeat
.
The Mark
type has gained Boxplot
, ErrorBar
, ErrorBand
, and
Trail
constructors. The MarkProperty
type has gained MBorders
,
MBox
, MExtent
, MHeight
, MHRef
, MLine
, MMedian
, MOrder
,
MOutliers
, MNoOutliers
, MPoint
, MRule
, MStrokeCap
, MStrokeJoin
,
MStrokeMiterLimit
, MTicks
, MTooltip
, MWidth
, MX
, MX2
,
MXOffset
, MX2Offset
, MY
, MY2
, MYOffset
, and MY2Offset
constructors.
The Position
type has added XError
, XError2
, YError
, and
YError2
constructors.
The MarkErrorExtent
type was added.
The BooleanOp
type has gained the FilterOp
and FilterOpTrans
constructors which lets you use Filter
expressions as part of a
boolean operation. The Filter
type has also gained expresiveness,
with the FLessThan
, FLessThanEq
, FGreaterThan
, FGreaterThanEq
,
and FValid
.
The 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: MBinned
, MSort
,
MTitle
, and MNoTitle
. The PositionChannel type has added
PHeight
, PWidth
, PNumber
, PBinned
, PImpute
, PTitle
, and
PNoTitle
constructors.
The LineMarker and PointMarker types have been added for use with
MLine
and MPoint
respectively (both from MarkProperty
).
The ability to define the binning property with
binAs
, DBin
, FBin
, HBin
, MBin
, OBin
, PBin
, and TBin
has
been expanded by adding the AlreadyBinned
and BinAnchor
constructors to BinProperty
, as well as changing the Divide
constructor (as described below).
The StrokeCap
and StrokeJoin
types has been added. These are used
with MStrokeCap
, VBStrokeCap
, and ViewStrokeCap
and
MStrokeJoin
, VBStrokeJoin
, and ViewStrokeJoin
respectively.
The StackProperty
constructor has been added with the StOffset
and StSort
constructors. As discussed below this is a breaking change
since the old StackProperty type has been renamed to StackOffset
.
The ScaleProperty
type has seen significant enhancement, by adding
the constructors: SAlign
, SBase
, SBins
, SConstant
and
SExponent
. THe Scale
tye has added ScSymLog
ScQuantile
,
ScQuantize
, and ScThreshold
.
The SortProperty
type has new constructors: CustomSort
,
ByRepeatOp
, ByFieldOp
, and ByChannel
. See the breaking-changes
section below for the constructors that were removed.
The AxisProperty
type has seen significant additions, including:
AxBandPosition
, AxDomainColor
, AxDomainDash
,
AxDomainDashOffset
, AxDomainOpacity
, AxDomainWidth
,
AxFormatAsNum
, AxFormatAsTemporal
, AxGridColor
, AxGridDash
,
AxGridDashOffset
, AxGridOpacity
, AxGridWidth
, AxLabelAlign
,
AxLabelBaseline
, AxLabelNoBound
, AxLabelBound
,
AxLabelBoundValue
, AxLabelColor
, AxLabelNoFlush
, AxLabelFlush
,
AxLabelFlushValue
, AxLabelFlushOffset
, AxLabelFont
,
AxLabelFontSize
, AxLabelFontStyle
, AxLabelFontWeight
,
AxLabelLimit
, AxLabelOpacity
, AxLabelSeparation
, AxTickColor
,
AxTickDash
, AxTickDashOffset
, AxTickExtra
, AxTickMinStep
,
AxTickOffset
, AxTickOpacity
, AxTickRound
, AxTickWidth
,
AxNoTitle
, AxTitleAnchor
, AxTitleBaseline
, AxTitleColor
,
AxTitleFont
, AxTitleFontSize
, AxTitleFontStyle
,
AxTitleFontWeight
, AxTitleLimit
, AxTitleOpacity
, AxTitleX
, and
AxTitleY
.
The AxisConfig
has seen a similar enhancement, and looks similar
to the above apart from the constructors do not start with ‘Ax’.
The LegendConfig
type has been significantly expanded and, as
discussed in the Breaking Changes section, changed. It has gained:
LeClipHeight
, LeColumnPadding
, LeColumns
, LeGradientDirection
,
LeGradientHorizontalMaxLength
, LeGradientHorizontalMinLength
,
LeGradientLength
, LeGradientOpacity
, LeGradientThickness
,
LeGradientVerticalMaxLength
, LeGradientVerticalMinLength
,
LeGridAlign
, LeLabelFontStyle
, LeLabelFontWeight
,
LeLabelOpacity
, LeLabelOverlap
, LeLabelPadding
,
LeLabelSeparation
, LeLayout
, LeLeX
, LeLeY
, LeRowPadding
,
LeSymbolBaseFillColor
, LeSymbolBaseStrokeColor
, LeSymbolDash
,
LeSymbolDashOffset
, LeSymbolDirection
, LeSymbolFillColor
,
LeSymbolOffset
, LeSymbolOpacity
, LeSymbolStrokeColor
, LeTitle
,
LeNoTitle
, LeTitleAnchor
, LeTitleFontStyle
, LeTitleOpacity
,
and LeTitleOrient
.
The LegendOrientation
type has gained LOTop
and LOBottom
.
The LegendLayout
and BaseLegendLayout
types are new, and used
with LeLayout
to define the legent orient group.
The LegendProperty
type gained: LClipHeight
, LColumnPadding
,
LColumns
, LCornerRadius
, LDirection
, LFillColor
,
LFormatAsNum
, LFormatAsTemporal
, LGradientLength
,
LGradientOpacity
, LGradientStrokeColor
, LGradientStrokeWidth
,
LGradientThickness
, LGridAlign
, LLabelAlign
, LLabelBaseline
,
LLabelColor
, LLabelFont
, LLabelFontSize
, LLabelFontStyle
,
LLabelFontWeight
, LLabelLimit
, LLabelOffset
, LLabelOpacity
,
LLabelOverlap
, LLabelPadding
, LLabelSeparation
, LRowPadding
,
LStrokeColor
, LSymbolDash
, LSymbolDashOffset
,
LSymbolFillColor
, LSymbolOffset
, LSymbolOpacity
, LSymbolSize
,
LSymbolStrokeColor
, LSymbolStrokeWidth
, LSymbolType
,
LTickMinStep
, LNoTitle
, LTitleAlign
, LTitleAnchor
,
LTitleBaseline
, LTitleColor
, LTitleFont
, LTitleFontSize
,
LTitleFontStyle
, LTitleFontWeight
, LTitleLimit
, LTitleOpacity
,
LTitleOrient
, LTitlePadding
, LeX
, and LeY
.
Projection
has gained the Identity
constructor. The
ProjectionProperty
type has gained PrScale
, PrTranslate
,
PrReflectX
, and PrReflectY
. The GraticuleProperty
type was
added to configure the appearance of graticules created with
graticule
.
The CompositionAlignment
type was added and is used with align
,
alignRC
, LeGridAlign
, and LGridAlign
.
The Bounds
type was added for use with bounds
.
The ImputeProperty
and ImMethod
types were added for use with
impute
and PImpute
.
The ScaleConfig
type has gained SCBarBandPaddingInner
,
SCBarBandPaddingOuter
, SCRectBandPaddingInner
, and
SCRectBandPaddingOuter
.
The SelectionProperty
type has gained Clear
, SInit
, and
SInitInterval
.
The Channel type has gained: ChLongitude
, ChLongitude2
,
ChLatitude
, ChLatitude2
, ChFill
, ChFillOpacity
, ChHref
,
ChKey
, ChStroke
, ChStrokeOpacity
. ChStrokeWidth
, ChText
,
and ChTooltip
.
The TitleConfig
type has gained: TFontStyle
, TFrame
, TStyle
,
and TZIndex
.
The TitleFrame
type is new and used with TFrame
from TitleConfig
.
The ViewBackground
type is new and used with viewBackground
.
The ViewConfig
type has gained ViewCornerRadius
, ViewOpacity
,
ViewStrokeCap
, ViewStrokeJoin
, and ViewStrokeMiterLimit
.
The ConfigurationProperty
type, used with configuration
, has
gained ConcatStyle
, FacetStyle
, GeoshapeStyle
, HeaderStyle
,
NamedStyles
, and TrailStyle
constructors.
The ConcatConfig
type was added for use with the ConcatStyle
,
and the FacetConfig
type for the FacetStyle
configuration settings.
The HeaderProperty
type has gained: HFormatAsNum
,
HFormatAsTemporal
, HNoTitle
, HLabelAlign
, HLabelAnchor
,
HLabelAngle
, HLabelColor
, HLabelFont
, HLabelFontSize
,
HLabelLimit
, HLabelOrient
, HLabelPadding
, HTitleAlign
,
HTitleAnchor
, HTitleAngle
, HTitleBaseline
, HTitleColor
,
HTitleFont
, HTitleFontSize
, HTitleFontWeight
, HTitleLimit
,
HTitleOrient
, and HTitlePadding
.
The HyperlinkChannel
type has gained HBinned
.
The FacetChannel
type has gained FSort
, FTitle
, and FNoTitle
.
The TextChannel
type has gained TBinned
, TFormatAsNum
,
TFormatAsTemporal
, TTitle
, and TNoTitle
.
The TooltipContent
type was added, for use with MTooltip
.
The Symbol
type has gained: SymArrow
, SymStroke
, SymTriangle
,
SymTriangleLeft
, SymTriangleRight
, and SymWedge
.
Breaking Changes
Some of these are repeated from above.
The title
function now takes a second argument, a list of TitleConfig
values for configuring the appearance of the title.
The SReverse
construtor was removed from ScaleProperty
as it
represented a Vega, rather than Vega-Lite, property. The xSort
constructors are used to change the order of an item (e.g. PSort
,
MSort
).
The ScSequential
constructor was removed from Scale
as
ScLinear
should be used.
The SortProperty
type has had a number of changes: the Op
,
ByField
, and ByRepeat
constructors have been removed, and
ByRepeatOp
, ByFieldOp
, and ByChannel
constructors have been
added.
The AxTitleMaxLength
and TitleMaxLength
constructors have been
removed (from AxisProperty
and AxisConfig
respectively) as they
are invalid. The AxTitleLimit
(new in this release) and
TitleLimit
constructors should be used instead.
AxisProperty
: the AxValues
constructor has been changed from
accepting a list of doubles to DataValues
. The AxDates
constructor has been deprecated and AxValues
should be used
instead.
There have been significant changes to the LegendConfig
type: the
EntryPadding
, GradientHeight
, GradientLabelBaseline
,
GradientWIdth
, and SymbolColor
constructors have been removed;
the renaming constructors have been renamed so they all begin with
Le
(e.g. Orient
is now LeOrient
, and Orient
has been added
to AxisConfig
); and new constructors have been added.
The StackProperty
type has been renamed to StackOffset
and its
constructors have changed, and a new StackProperty
type has been added (that references the StackOffset
type).
The Average
constructor of Operation
was removed, and Mean
should be used instead.
The LEntryPadding
constructor of LegendProperty
was removed.
The arguments to the MDataCondition
, TDataCondition
, and
HDataCondition
constructors - of MarkChannel
, TextChannel
,
and HyperlinkChannel
respectively - have changed to support
accepting multiple expressions.
The MarkOrientation
type has been renamed Orientation
.
The constructors of the ViewConfig
type have been renamed so they
all begin with View
(to match ViewWidth
and ViewHeight
).
The constructors of the ProjectionProperty
type have been renamed
so that they begin with Pr
rather than P
(to avoid conflicts
with the PositionChannel
type).
The Divide
constructor of BinProperty
now takes a list of
Doubles rather than two.
The TitleConfig
type has gained the following constructors:
TFontStyle
, TFrame
, TStyle
, and TZIndex
. The TitleFrame
type was added for use with TFrame
.
The ArgMax
and 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 PAggregate
).
The “z index” value has changed from an Int
to the ZIndex
type.
The constructors for the Symbol
type now all start with Sym
, so
Cross
, Diamond
, TriangleUp
, TriangleDown
, and Path
have been
renamed to SymCross
, SymDiamond
, SymTriangleUp
,
SymTriangleDown
, and SymPath
, respectively.
The Legend
type has been renamed LegendType
and its constructors
have been renamed GradientLegend
and SymbolLegend
.
Improved testing
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).
0.3.0.1
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 @since
annotations.
0.3.0.0
The Channel
type has been extended to include ChFill
and ChStroke
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.
0.2.1.0
Added the toHtml
and toHtmlFile
functions which create the necessary
HTML to view the Vega-Lite visualization using
Vega Embed
(this is similar to how
ihaskell-hvega
works).
This functionality was provided by Gregory Schwartz; apologies for taking so long to get it released.
0.2.0.0
The constructors for the LegendOrientation type have been renamed (by
adding the prefix LO
) which avoids the name clash with Left
and Right
seen in earlier releases. This is a breaking API change.
Clarify how to use the library in the main hvega
module.
Thanks to contributions from Nicolas Mattia (nmattia) and Marco Zocca (ocramz).
0.1.0.3
The only change is to the cabal file, where cabal-version: >=1.18
has
been changed to cabal-version: 1.18
.
0.1.0.2
Updated the upper bounds of aeson
to really allow v1.4. This was not
released on Hackage.
0.1.0.1
Updated the upper bounds of aeson
from v1.2 to v1.4.
The cabal package now includes stack.yaml
and default.nix
(although
the latter is not guaranteed to be correct), as well as a
change log and an extra image.
0.1.0.0
This is the initial version of hvega
, which is based on
version 2.2.1 of the
Elm Vega library.