Hanami

Interactive arts and charts visualizations with Clojure(Script), Vega-lite, and Vega. Flower viewing 花見 (hanami)

Hanami is a Clojure(Script) library and framework for creating interactive visualization applications based in Vega-Lite (VGL) and/or Vega (VG) specifications. These specifications are declarative and completely specified by data (JSON maps). VGL compiles into the lower level grammar of VG which in turn compiles to a runtime format utilizting lower level runtime environments such as D3, HTML5 Canvas, and WebGL. In addition to VGL and VG, Hanami is built on top of Reagent and Re-Com.

Overview
Installation
Features
Examples
Templates, Substitution Keys and Transformations
Application Construction
Example Transform 'Gallery'

toc

Overview

In keeping with the central data oriented tenet, Hanami eschews the typical API approach for generating specifications in favor of using recursive transforms of parameterized templates. This is also in keeping with the data transformation focus in functional programming, which is espcially nice in Clojure(Script).

An important aspect of this approach is that parameterized templates can be used to build other such templates by being higher level substitutions. In addition templates can be composed and this is an important idiomatic use. Furthermore, templates may be merged, though typically this is after transformation. The overall result enables the construction of sharable libraries of templates providing reusable plots, charts, and entire visualizations. Generally these will be domain and/or task specific. Hanami itself provides only a small set of very generic templates, which have proven useful in constructing more domain/task specific end results.

Hence, templates are a means to abstract all manner of visualization aspects and requirements. In this sense they are similar to what Altair provides but without the complications and limitations of an OO class/method based approach.

Installation

To install, add the following to your project :dependencies:

[aerial.hanami "0.15.1"]

Features

Parameterized templates with recursive transformations
- Takes the place of the typical static procedural/functional API
- Purely data driven - no objects, classes, inheritance, whatever
- Completely open ended - users may define their own with their own defaults
- More general in scope than an API while capable of arbitrary specific detail
A tabbing system for named visulization groupings
- Multiple simultaneous independent and dependent visulizations per grouping
- Automatic grid layout
- Option system for customization
Enables specific application construction
- Application level page header instrumentation (re-com enabled)
- Application level external instrumentation of charts (re-com enabled)
- Full hiccup/re-com "picture framing" capability for independent charts
- Multiple simultaneous (named) applications
- Multiple sessions per application
  - Shared named sessions
- Application extensible messaging capability
- Data streaming capable
  - Realtime chart/plot updates with data updates
Uses light weight websocket messaging system

Examples

(ns hanami.examples
  (:require [aerial.hanami.common :as hc]
            [aerial.hanami.templates :as ht]
            [aerial.hanami.core :as hmi]
            ...)

In all of the documentation, these namespaces are referred to by the shorthand provided in this require example.

aerial.hanami.common == hc
aerial.hanami.templates == ht
aerial.hanami.core == hmi

Simple cars

As a first example let's compare a Hanami template with corresponding Altair code. This is a the typical scatter plot example from the Vega-Lite developers used in many tutorials and by others in various places. First, the Altair:

cars = data.cars()

alt.Chart(cars).mark_point().encode(
    x='Horsepower',
    y='Miles_per_Gallon',
    color='Origin',
    ).interactive()

Hanami template version:

(hc/xform ht/point-chart
  :UDATA "data/cars.json"
  :X "Horsepower" :Y "Miles_per_Gallon" :COLOR "Origin")

Which, using the standard default substitution keys transforms to this Vega-Lite JSON specification:

{:data {:url "data/cars.json"},
 :width 400,
 :height 300,
 :background "floralwhite",
 :encoding
   {:x {:field "Horsepower", :type "quantitative"},
    :y {:field "Miles_per_Gallon", :type "quantitative"},
    :color {:field "Origin", :type "nominal"},
    :tooltip
    [{:field "Horsepower", :type "quantitative"}
     {:field "Miles_per_Gallon", :type "quantitative"}]}}

When rendered, both the Altair code and Hanami template, result in the following visualization, where the mouse is hovering over the point given by [132, 32.7]:

Hanami pic 1

Instrumented barchart

Hanami visualizations may be instrumented with external active componets (react/reagent/re-com) to enable external transforms on them. An example of an instrumented chart:

(hc/xform ht/bar-chart
  :USERDATA
  (merge
   (hc/get-default :USERDATA)
   {:vid :bc1
    :slider `[[gap :size "10px"] [label :label "Add Bar"]
              [label :label ~minstr]
              [slider
               :model :m1
               :min ~mi

Hanami

Install / Use

README

Hanami

Table of Contents

Overview

Installation

Features

Examples

Simple cars

Instrumented barchart