Vegas

[![TravisCI](https://travis-ci.org/aishfenton/Vegas.svg?branch=master)](https://travis-ci.org/aishfenton/Vegas) [![codecov.io](https://codecov.io/github/aishfenton/Vegas/coverage.svg?branch=master)](https://codecov.io/github/aishfenton/Vegas?branch=master)

Vegas aims to be the missing MatPlotLib for the Scala and Spark world. Vegas wraps around Vega-Lite but provides syntax more familar (and type checked) for use within Scala.

Quick start

Add the following jar as an SBT dependacy

libraryDependencies += "com.github.aishfenton" %% "vegas_2.11" % "0.2.3"

And then use the following code to render a plot into a pop-up window (see below for more details on controlling how and where Vegas renders).

import vegas._
import vegas.render.WindowRenderer._

val chart = Vegas("Country Pop").
  withData(
    Map("country" -> "USA", "population" -> 314),
    Map("country" -> "UK", "population" -> 64),
    Map("country" -> "DK", "population" -> 80)
  ).
  encodeX("country", Nominal).
  encodeY("population", Quantitative).
  mark(Bar)

chart.show

See further examples here

Rendering

Vegas provides a number of options for rendering charts out to. The primary focus is using Vegas within interactive notebook environments, such as Jupyter and Zeppelin.

Notebooks

Jupyter - Scala

If you're using jupyter-scala, then you must incldue the following in your notebook before using Vegas.

classpath.add("com.github.aishfenton" %% "vegas" % "{vegas-version}")

import vegas._
import vegas.render.HTMLRenderer._
implicit val displayer: String => Unit = display.html(_)

Jupyter - Apache Toree

And if you're using Apache Toree, then this:

%AddDeps com.github.aishfenton vegas_{scala-version} {vegas-version} --transitive

import vegas._
import vegas.render.HTMLRenderer._
implicit val displayer: String => Unit = { s => kernel.display.content("text/html", s) }

Zeppelin

And lastly if you're using Apache Zeppelin Zeppelin then use the following to initialize the notebook.

%dep
z.load("com.github.aishfenton:vegas_{scala-version}:{vegas-version}")

import vegas._
import vegas.render.HTMLRenderer._
implicit val displayer: String => Unit = { s => print("%html " + s) }

The last line in each of the above is required to connect Vegas to the notebook's HTML renderer (so that the returned HTML is rendered instead of displayed as a string).

See a comprehensive list example notebook of plots here

Standalone

Vegas can also be used to produce standalone HTML or even render plots within a built-in display app (useful if you wanted to display charts for a command-line-app).

HTML or JSON

The following renders the plot as both HTML (which is printed to the console), and as JSON containing the Vega-lite spec, which can copy-and-pasted into the Vega-lite editor.

import vegas._
import vegas.render.HTMLRenderer._

val chart = Vegas("Country Pop").
  withData(
    Map("country" -> "USA", "population" -> 314),
    Map("country" -> "UK", "population" -> 64),
    Map("country" -> "DK", "population" -> 80)
  ).
  encodeX("country", Nominal).
  encodeY("population", Quantitative).
  mark(Bar)

println(chart.pageHTML())
println(chart.spec.toJson())

Window

Vegas also contains a self-contained display app for displaying plots (internally JavaFX's HTML renderer is used). The following demonstrates this and can be used from the command line.

import vegas._
import vegas.render.WindowRenderer._

val chart = Vegas("Country Pop").
  withData(
    Map("country" -> "USA", "population" -> 314),
    Map("country" -> "UK", "population" -> 64),
    Map("country" -> "DK", "population" -> 80)
  ).
  encodeX("country", Nominal).
  encodeY("population", Quantitative).
  mark(Bar)

chart.show

Spark integration

Vegas comes with an optional extension package that makes it easier to work with Spark DataFrames and RDDs. First you'll need an extra import

libraryDependencies += "com.github.aishfenton" % "vegas-spark_{scala-version}" % "{vegas-version}"

import vegas.spark.Spark._

This adds the following new methods:

withDataFrame(df: DataFrame)
withRDD(rdd: RDD[Product])

In the first case, each DataFrame column is exposed as a field keyed using the column's name. In the second case, an RDD of case classes is expected, and reflection is used to map the case class's fields to fields within Vegas.

Flink integration

Vegas also comes with an optional extension package that makes it easier to work with Flink DataSets. You'll also need to import:

libraryDependencies += "com.github.aishfenton % "vegas-flink_{scala-version} % "{vegas-version}"

To use:

import vegas.flink.Flink._

This adds the following method:

* withData[T <: Product](ds: DataSet[T])

Similarly, to the RDD concept in Spark, a DataSet of case classes or tuples is expected and reflection is used to map the case class' fields to fields within Vegas. In the case of tuples you can encode the fields using "_1", "_2" and so on.

Plot Options

TODO

Contributing

See here for more information on contributing bug fixes and features.

spacelis/Vegas