gicentre / elm-vega Goto Github PK

View Code? Open in Web Editor NEW

182.0 12.0 13.0 28.22 MB

Elm - Vega Integration for functional declarative visualization

Home Page: http://package.elm-lang.org/packages/gicentre/elm-vega/latest

License: BSD 3-Clause "New" or "Revised" License

Elm 99.87% Shell 0.13%

elm vega vega-lite visualization elm-vega

elm-vega's Introduction

elm-vega

Declarative visualization for Elm.

This package allows you to create Vega specifications in Elm providing a pure functional approach to declarative visualization. It does not generate graphical output directly, but instead allows you to create JSON specifications that can be sent to the Vega runtime to create the output.

Note: If you wish to create Vega-Lite specifications, use the sister-package elm-vegaLite.

Example

Visualizing a set of geospatial centroids as a Voronoi diagram:

let
    ds =
        dataSource
            [ data "centroids"
                [ daUrl (str "https://gicentre.github.io/data/uk/constituencySpacedCentroidsWithSpacers.csv")
                , daFormat [ csv, parseAuto ]
                ]
                |> transform
                    [ trGeoPoint "projection"
                        (field "longitude")
                        (field "latitude")
                    , trVoronoi (field "x")
                        (field "y")
                        [ voSize (numSignals [ "width", "height" ]) ]
                    ]
            ]

    pr =
        projections
            << projection "projection"
                [ prType transverseMercator
                , prScale (num 3700)
                , prTranslate (nums [ 320, 3855 ])
                ]

    sc =
        scales
            << scale "cScale" [ scType scOrdinal, scRange raCategory ]

    mk =
        marks
            << mark path
                [ mFrom [ srData (str "centroids") ]
                , mEncode
                    [ enEnter
                        [ maPath [ vField (field "path") ]
                        , maFill
                            [ ifElse "datum.region == 0"
                                [ transparent ]
                                [ vScale "cScale", vField (field "region") ]
                            ]
                        ]
                    ]
                ]
in
toVega
    [ width 420, height 670, ds, pr [], sc [], mk [] ]

This generates a JSON specification that when sent to the Vega runtime produces the following output:

Why elm-vega?

A rationale for Elm programmers

There is a demand for good visualization packages with Elm, especially ones that incorporate good practice in visualization design. Vega provides a theoretically robust and flexible grammar for specifying visualization design but is based on the JSON format. elm-vega provides a typed functional mapping of Vega, so affording the advantages of the Elm language in building up higher level visualization functions. Because Vega is widely used, you can take advantage of the many thousands of visualizations already shared in the Vega language.

Characteristics of elm-vega.

Built upon the widely used Vega specification that has an academic robustness and momentum behind its development.
Full access to lower level expressive visualization design.
Strict typing and friendly error messages means "the compiler is your friend" when building and debugging complex visualizations.

A rationale for data visualizers

In using JSON to fully encode a visualization specification Vega is portable across a range of platforms and sits well in the JavaScript / Web ecosystem. Yet JSON is really an interchange format rather than one suited directly for visualization design and construction.

By wrapping Vega within the Elm language, we can avoid working with JSON directly and instead take advantage of a typed functional programming environment for improved error support and customisation. This greatly improves reusability of code and integration with larger programming projects.

Elm and elm-vega provide an ideal environment for educators wishing to teach more advanced Data Visualization combining the beginner-friendly design of Elm with the robust and theoretically underpinned design of Vega.

Limitations

elm-vega does not render graphics directly, but instead generates data visualization specifications that may be passed to JavaScript for rendering.

Looking for an older version?

If you are using Elm 0.18, you will need to use elm-vega 3.0 and its API documentation. This older version combines modules for working with both Vega and Vega-Lite.

elm-vega's People

Contributors

Stargazers

Watchers

Forkers

silky insdami midfield knuton jeffesp dougburke yardsale8 digitalsatori momor666 ogreyard domoritz zeta1999 elm-review-bot

elm-vega's Issues

How to remove legends ?

Hi there !

I was just wondering if there is a way to remove the legends ?

Btw, your library is lovely to use. Thanks ! :)

Add autosize options to config

Now that the Vega config object bug has been fixed in Vega 3.0.9, add Autosize as an option to ConfigurationProperty.

Currently autosize properties can only be set directly as a top-level property rather than via a configuration option.

Support new test predicate

Vega-Lite v.2.1 now has support for explicit test predicates in channel encodings. e.g.:

"color": {
  "condition": {
    "test": "datum.IMDB_Rating === null || datum.Rotten_Tomatoes_Rating === null",
    "value": "#aaa"
  },
  "value": "#0099ff"
}

Previously, conditions only responded to selections, now they can respond to arbitrary predicates such as the data-related predicate above. We should support this new test predicate in elm-vega by adding an option to MCondition for test in addition to the current selection label.

Support for new Cursor mark property

Vega-Lite 2.1 now has an additional Cursor property for marks.

Add support for this in elm-vega.

AxValues should be able to take list of DateTime objects

Currently when customising an axis, only numbers may be provided to AxValues, e.g.

 PAxis [ AxGrid False, AxValues [ 12, 24, 36, 48, 60, 72 ] ]

Add ability to take a list of date objects too, as suggested in Vega-Lite documentation(see 'Ticks / Values').

As a workaround, can normally achieve desired effect with a combination of AxFormat and PScale [SNice [...]].

Is it possible to zoom on mobile ?

Hi there !

I found this link of a vega example to zoom on pinch gesture but I'm not sure how I can translate into elm-vega.
Is it possible at all ?

Thanks

Additional Properties - Bee Swarm Vega Example

Hello, I'm trying to make a plot based on the bee swarm Vega example: https://vega.github.io/vega/examples/beeswarm-plot/. It requires the use of "additional properties" (discussed here). I can't see a way to encode these in elm-vega, is it possible? Thanks for your help.

Upgrade to Elm 0.19

Thanks for your working on this project.

As our team plan to use Elm in a new project, and Vega for our visualization, glad to find elm-vega exists, It'll be nice to upgrade to Elm 0.19.

Support new Hyperlink channel

Vega-Lite v2.1 now supports a new Hyperlink channel – href for making marks clickable for sending to URLs.

Add support and documentation for this new channel.

Renaming eve.elm

Given that the project has been renamed in #7, should not src/eve.elm be renamed too? There are still some occurences of eve left in the code.
https://github.com/gicentre/elm-vega/search?utf8=%E2%9C%93&q=eve

I can do that if you approve.

`usermeta` section missing

At Humio we plan on using the usermeta section in vega specs to specify application specific properties e.g. the preprocessing the data needs before it is passed to Vega.
We use Elm and are looking at elm-vega (wonderful work btw). Currently the only no-go is the lack of custom usermeta which is defined in the vega JSON spec: https://vega.github.io/vega/docs/specification/

I would be happy to do a PR if you are strapped for time.

Add convenience function to convert list of specs into a spec

Currently, to send a list of Vega-Lite specs though a port for consumption by JavaScript, the specs are converted into a single JSON list with Json.Encode.list.

Rather than expose JSON encoding in this way (and require import Json.Encode), create a convenience function combineSpecs to do the encoding:

[vlSpec1, vlSpec2, vlSpec2] |> combineSpecs

This also has the advantage of keeping the API for encoding of specs agnostic should we ever need to encode specs in some way other than JSON.

Custom Element for rendering Vega specification

Hi,

What do you think about implementing custom element which could render visualisation from Vega specification? I imagine, we could then simply keep specification in model and pass in view function to custom element. Almost no configuration in JavaScript.

Of course current mechanism should stay in place for more complicated cases, where you want to use Vega.View in your code and for example manipulate signals or selections.

I understand it would be implemented in another, not elm package. But I would like to discuss such idea here, between elm-vega users.

Best,
Adrian

We might also consider validating against Vega-Lite and Vega schemas, although there are still some cases where working VL/V examples can invalidate schemas.