Skip to content


Browse files Browse the repository at this point in the history
Initial commit
  • Loading branch information
alexarchambault committed Aug 27, 2016
0 parents commit d61089a
Show file tree
Hide file tree
Showing 89 changed files with 5,415 additions and 0 deletions.
1 change: 1 addition & 0 deletions .gitignore
@@ -0,0 +1 @@
4 changes: 4 additions & 0 deletions .gitmodules
@@ -0,0 +1,4 @@
[submodule "plotly-documentation"]
path = plotly-documentation
url =
branch = source
159 changes: 159 additions & 0 deletions
@@ -0,0 +1,159 @@
# plotly-scala

Scala bindings for [plotly.js](

[![Build Status](](
[![Join the chat at](](
[![Maven Central](](


*plotly-scala* is a Scala library able to output JSON that can be passed to [plotly.js]( Its classes closely follow the API of plotly.js, so that one can use plotly-scala by following the [documentation]( of plotly.js. These classes can be converted to JSON, that can be fed directly to plotly.js.

It can be used from [jupyter-scala](, from scala-js, or from a Scala REPL like [Ammonite](, to plot things straightaway in the browser.

It runs demos of the plotly.js documentation during its tests, to ensure that it is fine with all their features. That allows it to reliably cover a wide range of the plotly.js features - namely, all the examples of the supported sections of the plotly.js documentation are guaranteed to be fine.

## Table of content

1. [Quick start](#quick-start)
2. [Rationale](#rationale)
3. [Internals](#internals)
4. [Supported features](#supported-features)

## Quick start

### From jupyter-scala

Simply add the `"org.plotly-scala" %% "plotly-jupyter-scala" % "0.1.0"` dependency to the notebook, like
classpath.add("org.plotly-scala" %% "plotly-jupyter-scala" % "0.1.0")

In a subsequent cell, initialize plotly-scala with
import plotly._
import plotly.element._
import plotly.layout._
import plotly.JupyterScala._


Then plot charts with, e.g.
val (x, y) = Seq(
"Banana" -> 10,
"Apple" -> 8,
"Grapefruit" -> 5

Bar(x, y).plot()

See this [notebook demo]( for a full example (rendered via Github gist, so the plots cannot be visualized from the link though).

### From scala-js

Add the corresponding dependency to your project, like
libraryDependencies += "org.plotly-scala" %%% "plotly-render" % "0.1.0"

From your code, add some imports for plotly,
import plotly._, element._, layout._, Plotly._

Then define plots like
val x = 0.0 to 10.0 by 0.1
val y1 = => 2.0 * d + util.Random.nextGaussian())
val y2 =

val plot = Seq(
x, y1, name = "Approx twice"
x, y2, name = "Exp"
and plot them with
title = "Curves"

### From Ammonite

Load the corresponding dependency, and some imports, like
import $ivy.`org.plotly-scala::plotly-render:0.1.0`
import plotly._, element._, layout._, Plotly._

Then plot things like
val labels = Seq("Banana", "Banano", "Grapefruit")
val valuesA = => util.Random.nextGaussian())
val valuesB = => 0.5 + util.Random.nextGaussian())

Bar(labels, valuesA, name = "A"),
Bar(labels, valuesB, name = "B")
title = "Level"

## Rationale

Most high-level Javascript libraries for plotting have well designed APIs, enforcing immutability and almost relying on typed objects, although not explicitly. Yet, the few existing Scala libraries for plotting still try to mimick [matplotlib]( or Matlab, and have APIs requiring users to mutate things, in order to do plots. They also tend to lack a lot of features, especially compared to the current high-end Javascript plotting libraries. *plotly-scala* aims at filling this gap, by providing a reliable bridge from Scala towards the renowned [plotly.js](

## Internals

*plotly-scala* consists in a bunch of definitions, mostly case classes and sealed class hierarchies, closely following the API of plotly.js. It also contains JSON codecs for those, allowing to convert them to JSON that can be passed straightaway to plotly.js.

Having the ability to convert these classes to JSON, the codecs can also go the other way around: from plotly.js-compatible JSON to plotly-scala Scala classes. This way of going is used by the tests of plotly-scala, to ensure that the examples of the plotly.js documentation, illustrating a wide range of the features of plotly.js, can be represented via the classes of plotly-scala. Namely, the Javascript examples of the documentation of plotly.js are run inside a [Rhino]( VM, with mocks of the plotly API. These mocks allow to keep the Javascript objects passed to the plotly.js API, and convert them to JSON. These JSON objects are then validated against the codecs of plotly-scala, to ensure that all their fields can be decoded by them. If these are fine, this gives a proof that all the features of the examples have a counterpart in plotly-scala.

Internally, plotly-scala uses [circe]( (along with custom codec derivation mechanisms) to convert things to JSON, then render them. The circe objects don't appear in the plotly-scala API - circe is only used internally. The plotly-scala API only returns JSON strings, that can be passed to plotly.js. In subsequent versions, plotly-scala will likely try to shade circe and its dependencies, or switch to a more lightweight JSON library.

## Supported features

plotly-scala supports the features illustrated in the following sections of the plotly.js documentation:
- [Scatter Plots](,
- [Bubble Charts](,
- [Line Charts](,
- [Bar Charts](,
- [Horizontal Bar Charts](,
- [Filled Area Plots](,
- [Time Series](,
- [Subplots](,
- [Multiple Axes](,
- [Histograms](,
- [Log Plots](

Some of these are illustrated in the [demo]( page.

## Adding support for extra plotly.js features

The following workflow can be followed to add support for extra sections of the plotly.js documentation:
- find the corresponding directory in the [source]( of the plotly.js documentation. These directories can also be found in the sources of plotly-scala, under `plotly-documentation/_posts/plotly_js`, if its repository has been cloned with the `--recursive` option,
- enabling testing of the corresponding documentation section examples in the `DocumentationTests` class, around [this line](,
- running the tests with `sbt ~test`,
- fixing the possible Javascript typos in the plotly-documentation submodule in the plotly-scala sources, so that the enabled JS snippets run fine with Rhino from the tests, then committing these fixes, either to [](`alexarchambault/plotly-documentation`) or [](`plotly/documentation`),
- add the required fields / class definitions, and possibly codecs, to have the added tests pass.

## About

Battlefield tested since early 2016 at [](

Released under the LGPL v3 license, copyright 2016 Alexandre Archambault.

Parts based on the original plotly.js API, which is copyright 2016 Plotly, Inc.

0 comments on commit d61089a

Please sign in to comment.