diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,12 @@ For the latest version of this document, please see [https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md](https://github.com/DougBurke/hvega/blob/master/hvega/CHANGELOG.md). +## 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 diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -38,17 +38,20 @@ enc = encoding . position X [ PName "Horsepower", PmType Quantitative ] - . position Y [ PName "Miles_per_Gallon", PmType Quantitative ] + . position Y [ PName "Miles_per_Gallon", PmType Quantitative, PTitle "Miles per Gallon" ] . color [ MName "Origin", MmType Nominal ] bkg = background "rgba(0, 0, 0, 0.05)" -in toVegaLite [ bkg, cars, mark Circle [], enc [] ] +in toVegaLite [ bkg, cars, mark Circle [MTooltip TTEncoding], enc [] ] ``` -When the JSON is viewed with a Vega-Lite aware viewer, the resultant plot is +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](https://vega.github.io/editor/#/url/vega-lite/N4IgtghgTg1iBcoAuB7FAbJBLADg0AxigHZICmpCIFRAJlsQOYgC+ANCEgJ45lUFYoBdH3YhaEJBHwgArlHRUAFkiQ4AzvAD0WgG5lGEAHSMsSJbIBGRrCj0GIAWglT1ZJOq0uIWgtHVGAFbqJKwcACTqBEpkkMqqGtr2hiZmFta2WlExkMlO6GZkegAsQSHEIBw0KPRMMkToKFAyAGZYZOi0VADyUFimFRzcvFTEKGAMEIpiAB6t7Z1UABJNbjgoAO5kzUM8fPAgAI6yEKRmklj6YSBc8x1dBwCyWCLqAPq8UG8A4lONg5wzCIqM9XgACT5g37of6VTh7KjHU7YKTYK4sMSWCAEGCMKAoWTEB4gKCMLEACgADGxqbSjJSAKwASlYQA). +It can also be viewed as a PNG: -![Simple scatterplot](https://raw.githubusercontent.com/DougBurke/hvega/master/hvega/images/intro.png "Simple scatterplot") +![Simple scatterplot](https://raw.githubusercontent.com/DougBurke/hvega/master/hvega/images/example-car.png "Simple scatterplot") ### Betelgeuse @@ -154,9 +157,9 @@ - an [interactive version](https://vega.github.io/editor/#/url/vega-lite/N4KABGBEAuBOCGA7AzgMwPawLaQFxgG1wIxhJUBLAG2gFNY8oATeaAVywDpKb6A5eFloEADAF0wAXmlgA5ADVZkAL4AaYhDI86DfJBbsuWeAHNEFdk1pgAPGAAsK9SVKR4yRvvgBPD6qgAxvBUAWxUrLSeBhycAFZMYAC0YABM9gCsAByZ9gCcnCIqxGLOgeiIlCaMoC5uAB4UHvg1LlDQFlS0AGLl0ADqtBQmABbQnoiYxlSQpbXhAEa0VD2I0ADKFABekfgAjPazJDAd3b0b24y7AGwaYMrEasRe0PDVt5BssNN6o9AADshcAB6IEIADunBMFmGbHmbGQ9ACvVoq04SKwQIAIug2CYAEKfADWtCBwwAbrQTPAgcZkDpSRSqUCDNTFnQqCZaPDaIkUiI+YkRABmRK7fKxZDlSAPUqQMlIxBBMb4IguFq1YaDEbKsC7dIiQ4QSDGWCE6qQdB-eABCzeRgiTjpfwwbx-HZQP7oCirGZQHidJiMVDBBGPVpQMEUJjQYaMK4iA23I0IzoBdpS5pJo7zWDw2OZ8O1b0Wc11RgEXl8-y7BMlKB2lWCx3+FKOsRhwtGlFIpjekxNQiQMvOu0lLO1aCu92Qb06MnBaWd+7hju1bvoXuIKoFwuQJFUTBvTtGyhLQN6bT8QSRQ2tF1u8boLDehe3uaUlHn0jju8LJYrdYtndfY3zvdpoE6TwumoHQZh-CcTgA85gJuY87h-Vc72QYZ4AfZpyAoM9PEvWABCEX172nCZn0QBdMNqMsd07AiiL0FhfDgtDKM8ABHNgkHA1gKApTjj3qRpzXAyC9ExHxkDAZBvQCawACkkH42BvF1Ft+UKZdC3oo4G2-LjTyoL9jVMcxLBveCoGQIJpNcJgn3gb1y1FfwhXbUDk0wHV9FoBzPz7UTmMnPCoD4gSLCEkTfKgeAGgHMgpOnABZKyLDYKwiiXLN9IgTD1SOZA3QCI9d01IZRkufVQMs01zUta1bXtZs2inTxPVnCj-VoL9gyoUMGsjaN8zAeNE2Y9dN23EyxP3Q8mLEsyLJIsjbLQo0Iqop8X2mBKjU6TlEC-EquL-ZYziAy4DjshCIOnaDeAYI6jjSpDbr2VDtsKgyEsgbDcPdLRCPM4iYKvcjnV2x8aLowHGIW0zwYs9i-Ae+zHNB-RXPc-C1qiOSKJTWg0woDMoBzPMVEM8NuL0aLVli9p4qx8SUuOJ7GEQMIqH+ldAeMi7dyJvRjDMbLcveoGcfNFzjAJ1xxagSXrJym97KWcn00QTwaewunZclWAAqsYKztC2W4aZ-iWZeNmtu2znJJOXn+cF1ovaKgrbz3dAqA4FBLn94NlJ1UWTzRyHXs2sK701eArF0FHdyugBBRVhmWqBPwThmroAUTqP5U8gWQXp0fBZDAABqMBoi4K6C9-eBFioAAFZO5sYXl7su9v-xui4fsBtKPaoKhAczqghn1vRYBqsYMIa22oGog7F29-2ytardLhEW59LHI0ABIHM1YxPF+AFgSBRl4EhaFYU4SmgUv2hjAfyl4ESOe6AP3sHESU+tZQTxWjAWgdQAp4loOyD83JZDyXVtLawQh3CfC-iiaAyB-D7nCHQBI8wtIZwzvINYAB5BO5AR7AUyDKJ4FsAhLz+HrTwAAJdAYIwA4XknA9knIkHyRzMvRAQV5LziXgNfw8x3ADTAOURurB4BgAIREYhpDyFULAAAClvoCEEYJjGcHgPAMkkpOCYBMECAAlJwMAABNHECkc5hASCGdAYADzoEJGAVgvDoD-EMUCaAkYgn0DRE+IEbIljzHQNAfxZ1AnBPvlCGMr90SkgoH8P4xIYnwLiQkhxABJRJYJ3D+KnmAGM1gECckUYgBS6AbTBDAEIXsqiAm1IUi8M2ijUCpF0pwaUyggA) - - as a PNG: + - as a PNG: -![PNG version of the lightcurve](https://raw.githubusercontent.com/DougBurke/hvega/master/hvega/images/example.png "PNG version of the lightcurve") +![PNG version of the lightcurve](https://raw.githubusercontent.com/DougBurke/hvega/master/hvega/images/example-betelgeuse.png "PNG version of the lightcurve") ## Documentation @@ -178,21 +181,12 @@ sections have their own notebooks (with names of `VegaLiteGallery-
.ipynb`. -Unfortunately the plots created by VegaEmbed **do not always appear** -in the notebook when viewed with either GitHub's viewer or -[ipynb viewer](http://nbviewer.jupyter.org/github/DougBurke/hvega/blob/master/notebooks/VegaLiteGallery.ipynb), -but things seem better when using Jupyter Lab (rather than -notebook) to create the notebooks (since Vega is natively -supported in this environment). However, the native support is -for Vega-Lite version 1, and so many of the more-recent -capabilities are either ignored or cause the visualization to -fail. +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 re-created -using Jupyter Lab (thanks to Tweag I/O's -[JupyterWith environment](https://www.tweag.io/posts/2019-02-28-jupyter-with.html)), 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 have been created using Jupyter Lab (thanks to Tweag I/O's +[JupyterWith environment](https://www.tweag.io/posts/2019-02-28-jupyter-with.html)). ## Differences to Elm Vega diff --git a/hvega.cabal b/hvega.cabal --- a/hvega.cabal +++ b/hvega.cabal @@ -1,5 +1,5 @@ name: hvega -version: 0.9.0.0 +version: 0.9.0.1 synopsis: Create Vega-Lite visualizations (version 4) in Haskell. description: This is based on the elm-vegalite package () @@ -60,8 +60,8 @@ tests/specs/gallery/scatter/*.vl tests/specs/gallery/table/*.vl -extra-doc-files: images/example.png - images/intro.png +extra-doc-files: images/example-car.png + images/example-betelgeuse.png images/zindex.png images/vl/stripplot.png images/vl/stripplotwithbackground.png @@ -214,7 +214,7 @@ Gallery.Scatter Gallery.Table - build-depends: aeson >= 0.11 && < 1.6 + build-depends: aeson >= 1.4.2 && < 1.6 , aeson-pretty == 0.8.* , base >= 4 && < 5 , bytestring == 0.10.* diff --git a/hvega.nix b/hvega.nix --- a/hvega.nix +++ b/hvega.nix @@ -3,7 +3,7 @@ }: mkDerivation { pname = "hvega"; - version = "0.9.0.0"; + version = "0.9.0.1"; src = ./.; isLibrary = true; isExecutable = true; diff --git a/images/example-betelgeuse.png b/images/example-betelgeuse.png new file mode 100644 Binary files /dev/null and b/images/example-betelgeuse.png differ diff --git a/images/example-car.png b/images/example-car.png new file mode 100644 Binary files /dev/null and b/images/example-car.png differ diff --git a/images/example.png b/images/example.png deleted file mode 100644 Binary files a/images/example.png and /dev/null differ diff --git a/images/intro.png b/images/intro.png deleted file mode 100644 Binary files a/images/intro.png and /dev/null differ diff --git a/src/Graphics/Vega/Tutorials/VegaLite.hs b/src/Graphics/Vega/Tutorials/VegaLite.hs --- a/src/Graphics/Vega/Tutorials/VegaLite.hs +++ b/src/Graphics/Vega/Tutorials/VegaLite.hs @@ -1068,7 +1068,7 @@ -- are a number of measures of the \"spread\" of a population, such as -- the sample standard deviation ('Stdev'). -- --- You can also syntehsize new data based on existing data, with the +-- You can also synthesize new data based on existing data, with the -- 'transform' operation. Unlike the 'encoding' function, the order -- of the arguments to 'transform' do matter, as they control the -- data flow (e.g. you can not filter a data set if you have not diff --git a/src/Graphics/Vega/VegaLite.hs b/src/Graphics/Vega/VegaLite.hs --- a/src/Graphics/Vega/VegaLite.hs +++ b/src/Graphics/Vega/VegaLite.hs @@ -30,7 +30,7 @@ visualizations in an IHaskell notebook (using ). -== Example +== Examples Note that this module exports several symbols that are exported by the Prelude, such as 'VL.filter', 'VL.lookup', @@ -47,17 +47,60 @@ import Prelude hiding (filter, lookup, repeat) @ -In the following example, we'll assume the latter. -The aim is to create the following visualization: +In the following examples, we'll assume the latter. -<> +=== Example: viewing columns from a file -However this is missing the interactive elements of the visualization, primarily -selection and zooming in the top plot changes the axis ranges of the bottom two -plots. This interactivity requires a Vega-Lite viewer such as -. +The [Vega-Lite example gallery](https://vega.github.io/vega-lite/examples/) contain +a number of visualizations of the \"cars.json\" dataset (and many other +datasets ;-), 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: -It is rather lengthy, as it includes +@ +let cars = 'VL.dataFromUrl' \"https:\/\/vega.github.io\/vega-datasets\/data\/cars.json\" [] + + enc = 'VL.encoding' + . 'VL.position' 'VL.X' [ 'VL.PName' \"Horsepower\", 'VL.PmType' 'VL.Quantitative' ] + . 'VL.position' 'VL.Y' [ 'VL.PName' \"Miles_per_Gallon\", 'VL.PmType' 'VL.Quantitative', 'VL.PTitle' \"Miles per Gallon\" ] + . 'VL.color' [ 'VL.MName' \"Origin\", 'VL.MmType' 'VL.Nominal' ] + + bkg = 'VL.background' \"rgba(0, 0, 0, 0.05)\" + +in 'VL.toVegaLite' [ bkg, cars, 'VL.mark' 'VL.Circle' ['VL.MTooltip' 'VL.TTEncoding'], enc [] ] +@ + +When viewed with a Vega-Lite viewer (normally some form of a browser), you +can view the result. For instance: + + - the 'VL.fromVL' function will create the JSON representation of the + visualization, which can then be passed to a Vega-Lite viewer; + + - a routine like 'VL.toHtmlFile' can be used to create a HTML file + that will display the visualization using the + Javascript library; + + - users of the @Jupyter notebook@ environment can make use of the + automatic display of the `VL.VegaLite` type, using @ihaskell-hvega@, + to view an in-browser version of the plot (generated via Vega-Embed); + + - and users of @Jupyter lab@ can use the @vlShow@ method (from @ihaskell-hvega@), + but be aware that it is currently limited to only supporing features + from Vega-Lite version 2. + +The visualization can be viewed in the Vega Editor, which lets you +interact with the plot and modify its contents, as shown for +. + +It can also be viewed as a PNG version: + +<> + +=== Example: faceting, data transformation, and interaction + +The following example is rather lengthy, as it includes data tranformation (sub-setting the data and creating a new column), automatic faceting (that is, creating separate plots for unique values of a data column), interactive elements @@ -216,16 +259,14 @@ @ -The 'VL.fromVL' function will create the JSON representation of the visualization, -which can then be passed to a Vega-Lite viewer (or a routine like 'VL.toHtmlFile' -can be used to create a HTML file that will display the visualization using the - Javascript library). +The PNG version shows the basic features: -Output can be achieved in a Jupyter Lab session with the @vlShow@ function, -provided by @ihaskell-vega@, or 'VL.toHtmlFile' can be used to write out a page of -HTML that includes pointer to JavaScript files which will display a Vega-Lite -specification (there are also functions which provide more control over -the embedding). +<> + +However this is missing the interactive elements of the visualization, primarily +selection and zooming in the top plot changes the axis ranges of the bottom two +plots. This interactivity requires a Vega-Lite viewer such as +. -} diff --git a/tests/Gallery/Advanced.hs b/tests/Gallery/Advanced.hs --- a/tests/Gallery/Advanced.hs +++ b/tests/Gallery/Advanced.hs @@ -8,7 +8,7 @@ import Graphics.Vega.VegaLite -import Prelude hiding (filter, lookup) +import Prelude hiding (filter, lookup, repeat) import Data.Aeson (Value, toJSON) @@ -31,6 +31,7 @@ , ("layered2", layered2) , ("layered3", layered3) , ("benchmark", benchmark) + , ("irisScatterplotMatrix", irisScatterplotMatrix) ] @@ -360,6 +361,10 @@ in toVegaLite [ des, groupData, trans [], enc [], mark Bar [] ] +irisData :: Data +irisData = dataFromUrl "https://vega.github.io/vega-lite/data/iris.json" [] + + -- advanced14 in elm advanced8 :: VegaLite advanced8 = @@ -378,9 +383,6 @@ ] ) - dvals = - dataFromUrl "https://vega.github.io/vega-lite/data/iris.json" - fields = ["petalLength", "petalWidth", "sepalLength", "sepalWidth"] trans = transform @@ -441,7 +443,7 @@ , cfg [] , width 600 , height 300 - , dvals [] + , irisData , trans [] , layer [ specLine, specAxis, specAxisLabelsTop, specAxisLabelsMid, specAxisLabelsBot ] ] @@ -476,9 +478,7 @@ -- density1 :: VegaLite density1 = - let dvals = dataFromUrl "https://vega.github.io/vega-lite/data/iris.json" [] - - trans = transform + let trans = transform . foldAs [ "petalWidth", "petalLength", "sepalWidth", "sepalLength" ] "organ" "value" . density "value" [ DnBandwidth 0.3, DnGroupBy [ "organ" ] ] @@ -487,16 +487,14 @@ . position Y [ PName "density", pQuant ] . row [ FName "organ", fNominal ] - in toVegaLite [ width 300, height 50, dvals, trans [], enc [], mark Area [] ] + in toVegaLite [ width 300, height 50, irisData, trans [], enc [], mark Area [] ] -- advanced13 in elm -- density2 :: VegaLite density2 = - let dvals = dataFromUrl "https://vega.github.io/vega-lite/data/iris.json" [] - - trans = transform + let trans = transform . foldAs [ "petalWidth", "petalLength", "sepalWidth", "sepalLength" ] "measurement" "value" . density "value" [ DnBandwidth 0.3 @@ -510,7 +508,7 @@ . position Y [ PName "density", pQuant ] . color [ MName "measurement", mNominal ] - in toVegaLite [ width 400, height 100, dvals, trans [], enc [], mark Area [ MOpacity 0.5 ] ] + in toVegaLite [ width 400, height 100, irisData, trans [], enc [], mark Area [ MOpacity 0.5 ] ] -- advanced7 in elm @@ -745,3 +743,31 @@ , enc [] , layer [ specFalcon, specSquare ] ] + + +-- https://vega.github.io/vega-lite/docs/repeat.html#scatterplot-matrix-splom +irisScatterplotMatrix :: VegaLite +irisScatterplotMatrix = + let splom = [ width 150 + , height 150 + , mark Point [] + , encoding + . position X [ PRepeat Column + , PmType Quantitative + , PScale [SZero False] + ] + . position Y [ PRepeat Row + , PmType Quantitative + , PScale [SZero False] + ] + . color [MName "species", MmType Nominal] + $ [] + ] + + rows = ["petalWidth", "petalLength", "sepalWidth", "sepalLength"] + cols = ["sepalLength", "sepalWidth", "petalLength", "petalWidth"] + + in toVegaLite [ irisData + , repeat [RowFields rows, ColumnFields cols] + , specification (asSpec splom) + ] diff --git a/tests/specs/gallery/advanced/irisScatterplotMatrix.vl b/tests/specs/gallery/advanced/irisScatterplotMatrix.vl new file mode 100644 --- /dev/null +++ b/tests/specs/gallery/advanced/irisScatterplotMatrix.vl @@ -0,0 +1,49 @@ +{ + "data": { + "url": "https://vega.github.io/vega-lite/data/iris.json" + }, + "repeat": { + "row": [ + "petalWidth", + "petalLength", + "sepalWidth", + "sepalLength" + ], + "column": [ + "sepalLength", + "sepalWidth", + "petalLength", + "petalWidth" + ] + }, + "spec": { + "height": 150, + "mark": "point", + "width": 150, + "encoding": { + "color": { + "field": "species", + "type": "nominal" + }, + "x": { + "field": { + "repeat": "column" + }, + "scale": { + "zero": false + }, + "type": "quantitative" + }, + "y": { + "field": { + "repeat": "row" + }, + "scale": { + "zero": false + }, + "type": "quantitative" + } + } + }, + "$schema": "https://vega.github.io/schema/vega-lite/v4.json" +}