diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,13 @@ For the latest version of this document, please see [https://github.com/DougBurke/hvega/blob/master/ihaskell-hvega/CHANGELOG.md](https://github.com/DougBurke/hvega/blob/master/ihaskell-hvega/CHANGELOG.md). +## 0.2.0.0 + +Added the `vlShow` helper to allow Vega-Lite visualizations to be +viewed directly in Jupyter lab (rather than Jupyter notebook). + +Try it out in [Tweag's jupyterWith environment](https://github.com/tweag/jupyterWith). + ## 0.1.0.3 The only change is to the cabal file, where `cabal-version: >=1.10` has diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright Author name here (c) 2018 +Copyright Douglas Burke (c) 2018, 2019 All rights reserved. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,8 +1,18 @@ # ihaskell-hvega View [Vega-Lite](https://vega.github.io/vega-lite/) visualizations -created by the `hvega` package in IHaskell notebooks. It relies on +created by the `hvega` package in IHaskell notebooks. + +When used with Jupyter notebooks ut relies on [Vega-Embed](https://vega.github.io/vega-lite/usage/embed.html) to do the hard work of parsing and displaying the Vega Lite specification. + +If run in a Jupyter Lab then the native Vega support is used for +displaying the Vega Lite specifications. I recommend using +[Tweag I/O's jupyterWith environment](https://github.com/tweag/jupyterWith) +to set this up, and have a rudimentary +[`shell.nix` example](https://github.com/DougBurke/hvega/blob/master/notebooks/shell.nix) +in the +[notebooks directory](https://github.com/DougBurke/hvega/tree/master/notebooks). This code is released under the BSD3 license. diff --git a/default.nix b/default.nix --- a/default.nix +++ b/default.nix @@ -1,10 +1,10 @@ { mkDerivation, aeson, base, hvega, ihaskell, stdenv, text }: mkDerivation { pname = "ihaskell-hvega"; - version = "0.1.0.0"; + version = "0.2.0.0"; src = ./.; libraryHaskellDepends = [ aeson base hvega ihaskell text ]; - homepage = "https://github.com/githubuser/ihaskell-hvega#readme"; + homepage = "https://github.com/DougBurke/hvega"; description = "IHaskell display instance for hvega types"; license = stdenv.lib.licenses.bsd3; } diff --git a/ihaskell-hvega.cabal b/ihaskell-hvega.cabal --- a/ihaskell-hvega.cabal +++ b/ihaskell-hvega.cabal @@ -1,5 +1,5 @@ name: ihaskell-hvega -version: 0.1.0.3 +version: 0.2.0.0 synopsis: IHaskell display instance for hvega types. description: Support Vega-Lite visualizations in IHaskell notebooks. homepage: https://github.com/DougBurke/hvega @@ -8,7 +8,7 @@ license-file: LICENSE author: Douglas Burke maintainer: dburke.gw@gmail.com -copyright: 2018 Douglas Burke +copyright: 2018, 2019 Douglas Burke category: Development build-type: Simple extra-source-files: README.md @@ -22,8 +22,8 @@ exposed-modules: IHaskell.Display.Hvega build-depends: base >= 4.7 && < 5 , aeson >= 0.11 && < 1.5 - , hvega < 0.2 - , ihaskell >= 0.6.2 && < 0.10 + , hvega < 0.3 + , ihaskell >= 0.9.1 && < 0.10 , text == 1.2.* default-language: Haskell2010 diff --git a/src/IHaskell/Display/Hvega.hs b/src/IHaskell/Display/Hvega.hs --- a/src/IHaskell/Display/Hvega.hs +++ b/src/IHaskell/Display/Hvega.hs @@ -1,7 +1,54 @@ {-# LANGUAGE OverloadedStrings #-} -module IHaskell.Display.Hvega where +{-| +Module : IHaskell.Display.Hvega +Copyright : (c) Douglas Burke 2018, 2019 +License : BSD3 +Maintainer : dburke.gw@gmail.com +Stability : unstable +Portability : OverloadedStrings + +Allow VegaLite visualizations to be displayed directly in Jupyter notebooks +or Jupyter Lab. For the moment they are handled separately, in that the Jupyter +Lab version requires use of the `vlShow` routine. + +Jupyter Lab can be installed with nix using the + setup. + +== Example + +If we have the following Vega-Lite definition: + +@ +\{\-\# language OverloadedStrings \#\-\} + +import Graphics.Vega.VegaLite + +vl1 = 'toVegaLite' ['description' desc, 'background' "white", 'dat' [], 'mark' 'Bar' 'barOpts', 'enc' []] where + desc = "A very exciting bar chart" + + dat = 'dataFromRows' ['Parse' [("start", 'FoDate' "%Y-%m-%d")]] + . 'dataRow' [("start", 'Str' "2011-03-25"), ("count", 'Number' 23)] + . dataRow [("start", Str "2011-04-02"), ("count", Number 45)] + . dataRow [("start", Str "2011-04-12"), ("count", Number 3)] + + barOpts = ['MOpacity' 0.4, 'MColor' "teal"] + + enc = 'encoding' + . 'position' 'X' ['PName' "start", 'PmType' 'Temporal', 'PAxis' ['AxTitle' "Inception date"]] + . position Y [PName "count", PmType Quantitative] +@ + +then it can be displayed automatically in Jupyter Lab by + +> vlShow vl1 + +where @vlShow@ should be imported automatically by IHaskell. +-} + +module IHaskell.Display.Hvega (vlShow) where + import qualified Data.Text.Lazy as LT import Data.Aeson.Text (encodeToLazyText) @@ -9,11 +56,12 @@ import Graphics.Vega.VegaLite (VegaLite, fromVL) -import IHaskell.Display (IHaskellDisplay(..), Display(..), javascript) +import IHaskell.Display (IHaskellDisplay(..), Display(..) + , javascript, vegalite) --- ^ Use --- to include the Vega-Lite visualization in an IHaskell notebook. +-- ^ View a Vega-Lite visualization in a Jupyter *notebook*. Use 'vlShow' +-- instead if you are using Jupyter *lab*. -- -- There is currently no way to pass -- @@ -73,3 +121,36 @@ ds = [javascript (config <> makeDiv <> plot)] in pure (Display ds) + +-- | A wrapper around 'VegaLite' so that we can write a 'Display' +-- instance for JupyterLab and not end up with "overlapping +-- instances". +-- +-- Is there a better way to do this (other than drop support for +-- Jupyter notebook users)? +-- +newtype VegaLiteLab = VLL VegaLite + +-- | Convert a VegaLite visualization so that it can be auto-displayed +-- in Jupyter Lab. +-- +vlShow :: VegaLite -> VegaLiteLab +vlShow = VLL + +-- ^ Display Vega-Lite visualizations in an IHaskell notebook when +-- using Jupyter Lab. +-- +-- Use the @IHaskell.Display.Hvega@ module when using IHaskell from +-- a Jupyter notebook. +-- +-- Note that local file access is __not__ guaranteed to work - e.g. +-- @dataFromUrl@ where the file name refers to a local file - +-- since the JavaScript @fs@ module may not be loaded. +-- +-- It would be nice to create a PNG version for non-browser viewers, +-- but I am not sure how to get Jupyter to do this (and if it would +-- even do what I hope it does). +-- +instance IHaskellDisplay VegaLiteLab where + display (VLL vl) = let js = LT.unpack (encodeToLazyText (fromVL vl)) + in pure (Display [vegalite js])