Release version

Plotly.kt core on Bintray:

Plotly.kt ktor server on Bintray:

Development version

Plotly.kt core on Bintray:

Plotly.kt ktor server on Bintray:

Compatibility note

The current 0.3.0 version of the library is compatible with kotlin 1.4 with JS-IR and kotlinx-serialization 1.0.0. It is not guaranteed to work with kotlin 1.3.

TL;DR

See examples. See original library samples to understand capabilities.

Description

This project is developed to allow simple access to plotly functionality from kotlin-multiplatform. The API allows to create plotly configuration and render it as a plotly chart.

The library supports three drawable plot objects:

Plot itself stands for a stand-alone plot frame. It requires external infrastructure to load appropriate JavaScript libraries.
PlotFragment (JVM only) is an HTML fragment possibly including several plots. The API for html is provided by kotlinx-html library.
PlotlyPage (JVM only) is a complete page, including body fragment and page headers (needed to load JavaScript part of Plotly).

The work with plotly graphs could be rendered in following modes:

HTML page export

(JVM only) Export plot or a plot grid in a standalone html file, which uses CDN based plotly distribution. This mode does not support updates.

See staticPlot and
customPage for examples.

Ktor-based server with dynamic updates

(JVM only) A Ktor CIO server with full multi-page and update capabilities.

See simpleServer and
dynamicServer for examples.

Kotlin-JS

Plotly is a JavaScript library, yet it is convenient to have a type-safe API when using in with Kotlin-JS. The sample application is available in js-demo module. One should node that Plotly.kt for JS is not a zero-cost wrapper like TypeScript definitions, it maintains its own object structure, could generate stand-alone models and some internal optimizations.

JavaFX browser

Plotly.kt could be run in a JavaFX browser. An example project is presented in fx-demo.

Kotlin jupyter kernel (experimental)

Plotly.kt comes with (for now experimental) support for integration with Kotlin Jupyter kernel.

The examples of the notebooks are shown in notebooks directory. There are two module descriptor plotly.json and plotly-server.json in the same directory. They should be loaded according to Kotlin kernel documentation (either copied to ~/jypyter_kotlin/libraries or loaded directly).

The module plotly allows to render static plots in Jupyter. Jupyter lab is currently supported. Jupyter notebook (classic) is able to render only PlotlyPage objects, so one must convert plots to pages to be able to use notebook (see demo notebook).

The module plotly-server adds server capabilities and allows to render dynamic plots in notebooks (see demo notebook). One must note that for dynamic pages, one must pass renderer parameter explicitly to plot like it is done in examples.

Direct image render via Orca (experimental)

Plotly Orca application allows direct rendering of plots (not fragments or pages) to raster of vector images. Plot.export extension could be used to call it. It requires for orca to be installed in the system and available on the system path.

Kotlin-scripting (experimental)

It is possible to separate script logic into stand-alone plotly.kts script file and generate an html from the command line. See plotlykt-script module for details.

The feature I need is not implemented!

There are three ways to solve it:

Contribute! It is easy! Just add a model you need.
Create a model you need in your project or add an extension. Since the inner model is dynamic, you can add features on flight.
You can dynamically add missing features directly into configuration like it done in unsupportedFeature example.

Build and usage

In order to use the library, one needs to use following gradle.kts configuration:

plugins {
    kotlin("jvm")
}

repositories {
    jcenter()
    maven("https://dl.bintray.com/mipt-npm/dataforge")
    maven("https://dl.bintray.com/mipt-npm/kscience")
}

dependencies {
    implementation("kscience.plotlykt:plotlykt-server:0.3.0")
}

When using development versions (if version contains dev), one should also add

    maven("https://dl.bintray.com/mipt-npm/dev")

into the repository list.

If you do not need the server, then use plotlykt-core instead and remove ktor repository.

Naming

The library keeps original Plotly API naming wherever it is possible. There are some usability shortcuts, usually provided via kotlin extensions, included in order to simplify user interaction. For example, text and shape extensions in the top level API.

Keeping the original naming sometimes causes clashes with Kotlin code style. For example enum names are unorthodox.

Planned features

Table widgets
Serverside plot events
Online plot editor
Dynamic data
Mathjax and latex support

Contributions and thanks

Vasily Chernov - initial project foundation
Alexander Nozik - dynamic core and server
Mikhail Zeleniy - basic models
Ekaterina Samorodova (JBR-2020 summer internship) - Model refactoring, tutorials and 0.2 release.

The project was partially founded by JetBrains Research grant.

ArtificialPB/plotly.kt