Permalink
Browse files

Initial commit

  • Loading branch information...
alexarchambault committed Aug 27, 2016
0 parents commit d61089afef77e5abefa387e02f6f17291ad0259e
Showing with 5,415 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +4 −0 .gitmodules
  3. +159 −0 README.md
  4. +248 −0 build.sbt
  5. +1 −0 circe-alt-generic/README.md
  6. +21 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/derive/DerivedInstances.scala
  7. +63 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/derive/JsonProductCodec.scala
  8. +91 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/derive/JsonSumCodec.scala
  9. +182 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/derive/MkDecoder.scala
  10. +181 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/derive/MkEncoder.scala
  11. +5 −0 circe-alt-generic/shared/src/main/scala/io/circe/altgeneric/package.scala
  12. +46 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/DefaultTests.scala
  13. +38 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/Definitions.scala
  14. +153 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/LowPriorityTests.scala
  15. +25 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/PriorityTests.scala
  16. +20 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/PriorityTestsDefn.scala
  17. +237 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/ProductEncodeTests.scala
  18. +88 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/ShapelessTests.scala
  19. +148 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/SumEncodeTests.scala
  20. +15 −0 circe-alt-generic/shared/src/test/scala/io/circe/altgeneric/Util.scala
  21. +24 −0 core/shared/src/main/scala/plotly/Sequence.scala
  22. +188 −0 core/shared/src/main/scala/plotly/Trace.scala
  23. +13 −0 core/shared/src/main/scala/plotly/element/Anchor.scala
  24. +9 −0 core/shared/src/main/scala/plotly/element/AxisAnchor.scala
  25. +17 −0 core/shared/src/main/scala/plotly/element/AxisReference.scala
  26. +13 −0 core/shared/src/main/scala/plotly/element/AxisType.scala
  27. +3 −0 core/shared/src/main/scala/plotly/element/Bins.scala
  28. +14 −0 core/shared/src/main/scala/plotly/element/BoxMean.scala
  29. +16 −0 core/shared/src/main/scala/plotly/element/BoxPoints.scala
  30. +25 −0 core/shared/src/main/scala/plotly/element/Color.scala
  31. +10 −0 core/shared/src/main/scala/plotly/element/Dash.scala
  32. +20 −0 core/shared/src/main/scala/plotly/element/Element.scala
  33. +77 −0 core/shared/src/main/scala/plotly/element/Error.scala
  34. +9 −0 core/shared/src/main/scala/plotly/element/Fill.scala
  35. +11 −0 core/shared/src/main/scala/plotly/element/HistNorm.scala
  36. +32 −0 core/shared/src/main/scala/plotly/element/Line.scala
  37. +13 −0 core/shared/src/main/scala/plotly/element/LineShape.scala
  38. +35 −0 core/shared/src/main/scala/plotly/element/LocalDateTime.scala
  39. +41 −0 core/shared/src/main/scala/plotly/element/Marker.scala
  40. +13 −0 core/shared/src/main/scala/plotly/element/OneOrSeq.scala
  41. +9 −0 core/shared/src/main/scala/plotly/element/Orientation.scala
  42. +18 −0 core/shared/src/main/scala/plotly/element/ScatterMode.scala
  43. +11 −0 core/shared/src/main/scala/plotly/element/Side.scala
  44. +8 −0 core/shared/src/main/scala/plotly/element/SizeMode.scala
  45. +65 −0 core/shared/src/main/scala/plotly/element/Symbol.scala
  46. +4 −0 core/shared/src/main/scala/plotly/element/TextFont.scala
  47. +16 −0 core/shared/src/main/scala/plotly/element/TextPosition.scala
  48. +8 −0 core/shared/src/main/scala/plotly/element/Ticks.scala
  49. +43 −0 core/shared/src/main/scala/plotly/layout/Annotation.scala
  50. +100 −0 core/shared/src/main/scala/plotly/layout/Axis.scala
  51. +10 −0 core/shared/src/main/scala/plotly/layout/BarMode.scala
  52. +8 −0 core/shared/src/main/scala/plotly/layout/BoxMode.scala
  53. +25 −0 core/shared/src/main/scala/plotly/layout/Font.scala
  54. +8 −0 core/shared/src/main/scala/plotly/layout/HoverMode.scala
  55. +94 −0 core/shared/src/main/scala/plotly/layout/Layout.scala
  56. +43 −0 core/shared/src/main/scala/plotly/layout/Legend.scala
  57. +29 −0 core/shared/src/main/scala/plotly/layout/Margin.scala
  58. +11 −0 core/shared/src/main/scala/plotly/layout/Ref.scala
  59. +8 −0 core/shared/src/main/scala/plotly/layout/TraceOrder.scala
  60. +39 −0 demo/src/main/resources/index.html
  61. +142 −0 demo/src/main/scala/plotly/demo/Demo.scala
  62. +16 −0 demo/src/main/scala/plotly/demo/DemoChart.scala
  63. +31 −0 demo/src/main/scala/plotly/demo/area/BasicOverlaidAreaChart.scala
  64. +55 −0 demo/src/main/scala/plotly/demo/bar/BarChartWithDirectLabels.scala
  65. +24 −0 demo/src/main/scala/plotly/demo/bar/BasicBarChart.scala
  66. +37 −0 demo/src/main/scala/plotly/demo/bar/CustomizingIndividualBarColors.scala
  67. +36 −0 demo/src/main/scala/plotly/demo/bar/GroupedBarChart.scala
  68. +112 −0 demo/src/main/scala/plotly/demo/bar/WaterfallBarChart.scala
  69. +42 −0 demo/src/main/scala/plotly/demo/bubblecharts/HoverOnTextBubbleChart.scala
  70. +23 −0 demo/src/main/scala/plotly/demo/horizontalbarcharts/BasicHorizontalBarChart.scala
  71. +47 −0 demo/src/main/scala/plotly/demo/horizontalbarcharts/ColoredBarChart.scala
  72. +112 −0 demo/src/main/scala/plotly/demo/lineandscatter/CategoricalDotPlot.scala
  73. +30 −0 demo/src/main/scala/plotly/demo/linecharts/BasicLinePlot.scala
  74. +44 −0 demo/src/main/scala/plotly/demo/linecharts/LineAndScatterPlot.scala
  75. +23 −0 demo/src/main/scala/plotly/demo/timeseries/TimeSeries.scala
  76. +32 −0 joda-time/src/main/scala/plotly/Joda.scala
  77. +248 −0 jupyter-scala/src/main/scala/plotly/JupyterScala.scala
  78. +1 −0 plotly-documentation
  79. +1 −0 project/build.properties
  80. +22 −0 project/make-ghpages.sh
  81. +4 −0 project/plugins.sbt
  82. +1 −0 project/project/plugins.sbt
  83. +181 −0 render/js/src/main/scala/plotly/Plotly.scala
  84. +339 −0 render/jvm/src/main/scala/plotly/Plotly.scala
  85. +468 −0 render/shared/src/main/scala/plotly/Codecs.scala
  86. +49 −0 render/shared/src/main/scala/plotly/Enumerate.scala
  87. +277 −0 tests/src/test/scala/plotly/doc/DocumentationTests.scala
  88. +151 −0 tests/src/test/scala/plotly/doc/SchemaTests.scala
  89. +1 −0 version.sbt
@@ -0,0 +1 @@
target/
@@ -0,0 +1,4 @@
[submodule "plotly-documentation"]
path = plotly-documentation
url = https://github.com/alexarchambault/plotly-documentation.git
branch = source
159 README.md
@@ -0,0 +1,159 @@
# plotly-scala
Scala bindings for [plotly.js](https://plot.ly/javascript/)
[![Build Status](https://travis-ci.org/alexarchambault/plotly-scala.svg?branch=master)](https://travis-ci.org/alexarchambault/plotly-scala)
[![Join the chat at https://gitter.im/alexarchambault/plotly-scala](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/alexarchambault/plotly-scala?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Maven Central](https://img.shields.io/maven-central/v/org.plotly-scala/core_2.11.svg)](https://maven-badges.herokuapp.com/maven-central/org.plotly-scala/core_2.11)
[![ScalaDoc](http://javadoc-badge.appspot.com/org.plotly-scala/core_2.11.svg?label=scaladoc)](http://javadoc-badge.appspot.com/org.plotly-scala/core_2.11)
[Demo](https://alexarchambault.github.io/plotly-scala/)
*plotly-scala* is a Scala library able to output JSON that can be passed to [plotly.js](https://plot.ly/javascript/). Its classes closely follow the API of plotly.js, so that one can use plotly-scala by following the [documentation](https://plot.ly/javascript/) 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](https://github.com/alexarchambault/jupyter-scala), from scala-js, or from a Scala REPL like [Ammonite](https://github.com/lihaoyi/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
```scala
classpath.add("org.plotly-scala" %% "plotly-jupyter-scala" % "0.1.0")
```
In a subsequent cell, initialize plotly-scala with
```scala
import plotly._
import plotly.element._
import plotly.layout._
import plotly.JupyterScala._
plotly.JupyterScala.init()
```
Then plot charts with, e.g.
```scala
val (x, y) = Seq(
"Banana" -> 10,
"Apple" -> 8,
"Grapefruit" -> 5
).unzip
Bar(x, y).plot()
```
See this [notebook demo](https://gist.github.com/alexarchambault/b9e0b0441c0a804e0f11e1bcbb687afe) 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
```scala
libraryDependencies += "org.plotly-scala" %%% "plotly-render" % "0.1.0"
```
From your code, add some imports for plotly,
```scala
import plotly._, element._, layout._, Plotly._
```
Then define plots like
```scala
val x = 0.0 to 10.0 by 0.1
val y1 = x.map(d => 2.0 * d + util.Random.nextGaussian())
val y2 = x.map(math.exp)
val plot = Seq(
Scatter(
x, y1, name = "Approx twice"
),
Scatter(
x, y2, name = "Exp"
)
)
```
and plot them with
```scala
plot.plot(
title = "Curves"
)
```
### From Ammonite
Load the corresponding dependency, and some imports, like
```scala
import $ivy.`org.plotly-scala::plotly-render:0.1.0`
import plotly._, element._, layout._, Plotly._
```
Then plot things like
```scala
val labels = Seq("Banana", "Banano", "Grapefruit")
val valuesA = labels.map(_ => util.Random.nextGaussian())
val valuesB = labels.map(_ => 0.5 + util.Random.nextGaussian())
Seq(
Bar(labels, valuesA, name = "A"),
Bar(labels, valuesB, name = "B")
).plot(
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](http://matplotlib.org/) 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](https://plot.ly/javascript/).
## 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](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/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](https://github.com/travisbrown/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](https://plot.ly/javascript/line-and-scatter/),
- [Bubble Charts](https://plot.ly/javascript/bubble-charts/),
- [Line Charts](https://plot.ly/javascript/line-charts/),
- [Bar Charts](https://plot.ly/javascript/bar-charts/),
- [Horizontal Bar Charts](https://plot.ly/javascript/horizontal-bar-charts/),
- [Filled Area Plots](https://plot.ly/javascript/filled-area-plots/),
- [Time Series](https://plot.ly/javascript/time-series/),
- [Subplots](https://plot.ly/javascript/subplots/),
- [Multiple Axes](https://plot.ly/javascript/multiple-axes/),
- [Histograms](https://plot.ly/javascript/histograms/),
- [Log Plots](https://plot.ly/javascript/log-plot/).
Some of these are illustrated in the [demo](https://alexarchambault.github.io/plotly-scala/) 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](https://github.com/plotly/documentation/tree/gh-pages/_posts/plotly_js) 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](https://github.com/alexarchambault/plotly-scala/blob/master/tests/src/test/scala/plotly/doc/DocumentationTests.scala#L224),
- 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 [https://github.com/alexarchambault/plotly-documentation](`alexarchambault/plotly-documentation`) or [https://github.com/plotly/documentation](`plotly/documentation`),
- add the required fields / class definitions, and possibly codecs, to have the added tests pass.
## About
Battlefield tested since early 2016 at [Teads.tv](http://teads.tv)
Released under the LGPL v3 license, copyright 2016 Alexandre Archambault.
Parts based on the original plotly.js API, which is copyright 2016 Plotly, Inc.
Oops, something went wrong.

0 comments on commit d61089a

Please sign in to comment.