-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #73 from mipt-npm/dev
0.4.0
- Loading branch information
Showing
181 changed files
with
3,429 additions
and
2,900 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,4 +4,4 @@ build/ | |
| out/ | ||
|
|
||
| #gradle.properties | ||
| /notebooks/.ipynb_checkpoints/ | ||
| /examples/notebooks/.ipynb_checkpoints/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,39 @@ | ||
| plugins { | ||
| kotlin("js") apply false | ||
| id("ru.mipt.npm.project") | ||
| kotlin("jupyter.api") apply false | ||
| id("ru.mipt.npm.gradle.project") | ||
| } | ||
|
|
||
| val ktorVersion by extra("1.5.0") | ||
| val dataforgeVersion by extra("0.3.0") | ||
| val htmlVersion by extra("0.7.2") | ||
|
|
||
| val bintrayRepo by extra("kscience") | ||
| val githubProject by extra("plotly.kt") | ||
| val dataforgeVersion by extra("0.4.0") | ||
|
|
||
| allprojects { | ||
| group = "kscience.plotlykt" | ||
| version = "0.3.1" | ||
| group = "space.kscience" | ||
| version = "0.4.0" | ||
|
|
||
| repositories { | ||
| mavenLocal() | ||
| maven("https://dl.bintray.com/kotlin/kotlin-eap") | ||
| maven("https://repo.kotlin.link") | ||
| maven("https://kotlin.bintray.com/kotlinx") | ||
| } | ||
|
|
||
| if(name.startsWith("plotlykt")){ | ||
| apply<MavenPublishPlugin>() | ||
| } | ||
| } | ||
|
|
||
| apiValidation { | ||
| ignoredProjects.addAll(listOf("examples", "fx-demo", "js-demo")) | ||
| } | ||
|
|
||
| ksciencePublish{ | ||
| spaceRepo = "https://maven.pkg.jetbrains.space/mipt-npm/p/sci/maven" | ||
| github("plotly.kt") | ||
| space() | ||
| sonatype() | ||
| } | ||
|
|
||
| readme { | ||
| readmeTemplate = file("docs/templates/README-TEMPLATE.md") | ||
| } | ||
|
|
||
| changelog{ | ||
| version = project.version.toString() | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| > #### Artifact: | ||
| > | ||
| > This module artifact: `${group}:${name}:${version}`. | ||
| > | ||
| > | ||
| > [](https://search.maven.org/search?q=g:%22space.kscience%22%20AND%20a:%22${name}%22) | ||
| > | ||
| > **Gradle:** | ||
| > | ||
| > ```gradle | ||
| > repositories { | ||
| > maven { url 'https://repo.kotlin.link' } | ||
| > } | ||
| > | ||
| > dependencies { | ||
| > implementation '${group}:${name}:${version}' | ||
| > } | ||
| > ``` | ||
| > **Gradle Kotlin DSL:** | ||
| > | ||
| > ```kotlin | ||
| > repositories { | ||
| > maven("https://https://repo.kotlin.link") | ||
| > } | ||
| > | ||
| > dependencies { | ||
| > implementation("${group}:${name}:${version}") | ||
| > } | ||
| > ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) | ||
| [](https://zenodo.org/badge/latestdoi/186020000) | ||
|  | ||
| [](https://kotl.in/jsirsupported) | ||
|
|
||
|  | ||
|
|
||
| ## Artifact details | ||
|
|
||
| **TBD** | ||
|
|
||
| ## Compatibility note | ||
| The current `$version` version of the library is compatible with kotlin 1.4 with JS-IR and kotlinx-serialization 1.1.0. The JVM part requires JVM 11 to run. | ||
|
|
||
| # TL;DR | ||
| See [examples](./examples/src/main/kotlin). | ||
| See [original library samples](https://plotly.com/javascript/) 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](https://github.com/Kotlin/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](./examples/src/main/kotlin/staticPlot.kt) and | ||
| [customPage](./examples/src/main/kotlin/customPage.kt) for examples. | ||
|
|
||
| ## Ktor-based server with dynamic updates | ||
| (JVM only) A Ktor CIO server with full multi-page and update capabilities. | ||
|
|
||
| See [simpleServer](./examples/src/main/kotlin/simpleServer.kt) and | ||
| [dynamicServer](./examples/src/main/kotlin/dynamicServer.kt) 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](./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](./fx-demo). | ||
|
|
||
| ## Kotlin jupyter kernel (experimental) | ||
| Plotly.kt comes with (beta-version) support for integration with [Kotlin Jupyter kernel](https://github.com/Kotlin/kotlin-jupyter). See details [here](./docs/tutorials/jupyter.md). | ||
|
|
||
| The examples of the notebooks are shown in [notebooks](./examples/notebooks) directory. Plotly.kt uses Kotlin jupyter notebook API for integration (available in kernel version `0.8.3.236` and later). In order to load the library together with automatic imports one need to simply load a library in a following way: | ||
|
|
||
| ```kotlin | ||
| @file:Repository("https://repo.kotlin.link") | ||
| @file:DependsOn("space.kscience:plotlykt-jupyter:$version") | ||
| //@file:DependsOn("space.kscience:plotlykt-server:$version") // Use this one for sever integration. | ||
| ``` | ||
|
|
||
| The module `plotly` allows rendering 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](./notebooks/plotlykt-demo-classic.ipynb)). | ||
|
|
||
| The module `plotly-server` adds server capabilities and allows to render dynamic plots in notebooks (see [demo notebook](./notebooks/plotlykt-server-demo.ipynb)). 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](https://github.com/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](./plotlykt-script) module for details. | ||
|
|
||
| # The feature I need is not implemented! | ||
|
|
||
| There are three ways to solve it: | ||
| 1. Contribute! It is easy! Just add a model you need. | ||
| 2. Create a model you need in your project or add an extension. Since the inner model is dynamic, you can add features on flight. | ||
| 3. You can dynamically add missing features directly into configuration | ||
| like it done in [unsupportedFeature](./examples/src/main/kotlin/unsupportedFeature.kt) example. | ||
|
|
||
| # Build and usage | ||
|
|
||
| In order to use the library, one needs to use following `gradle.kts` configuration: | ||
|
|
||
| ```kotlin | ||
| plugins { | ||
| kotlin("jvm") | ||
| } | ||
|
|
||
| repositories { | ||
| maven("https://repo.kotlin.link") | ||
| } | ||
|
|
||
| dependencies { | ||
| implementation("kscience.plotlykt:plotlykt-server:$version") | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| If you do not need the server, then use plotlykt-core instead. | ||
|
|
||
| # 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](https://research.jetbrains.org/researchers/vchernov) - initial project foundation | ||
| * [Alexander Nozik](https://research.jetbrains.org/researchers/altavir) - dynamic core and server | ||
| * [Mikhail Zeleniy](https://research.jetbrains.org/researchers/gama_sennin) - basic models | ||
| * [Ekaterina Samorodova](https://github.com/ebsamorodova) (JBR-2020 summer internship) - Model refactoring, tutorials and `0.2` release. | ||
|
|
||
| The project was partially founded by JetBrains Research grant. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Plotly.kt Jupyter kernel integration | ||
| Being a JavaScript library with a Kotlin-JVM backend, Plotly.kt is ideally suited for [Jupyter kotlin kernel](https://github.com/Kotlin/kotlin-jupyter) integration. The integration is supported in two modes: | ||
|
|
||
| * Static rendering in [plotlykt-jupyter](../../plotlykt-jupyter) module. | ||
| * Dynamic updates processing via [plotlykt-server](../../plotlykt-server) module. | ||
|
|
||
| ## Loading the library | ||
|
|
||
| * Install or update [Jupyter kotlin kernel](https://github.com/Kotlin/kotlin-jupyter) to version `0.9` or later. | ||
| * Launch kotlin kernel in `jupyter lab` (classic jupyter notebook is not supported). | ||
| * Use `@file:DependsOn("space.kscience:plotlykt-jupyter:$plotlyVersion")` annotation directive to load library, where `$plotlyVersion` is the required version of the library. This approach uses [Kotlin jupyter notebook API](https://github.com/Kotlin/kotlin-jupyter/blob/master/docs/libraries.md#Integration-using-Kotlin-API). For dynamic version one should replace `plotlykt-server` instead of `plotlykr-jupyter`. | ||
| * Alternatively one could use `%use plotly` [directive](https://github.com/Kotlin/kotlin-jupyter#supported-libraries). For dynamic version one should replace `plotly-server` instead of `plotly`. | ||
|
|
||
| ## Automatic rendering | ||
|
|
||
| The integration automatically imports `space.kscience.plotlykt.*` and `space.kscience.plotlykt.models.*` and provides automatic rendering for three basic plotly objects: `Plot`, `PlotlyFragment` and `PlotlyPage`. One needs to return those object as result of last expressions in a cell in order to automatically render them. | ||
|
|
||
| ## Dynamic update server | ||
|
|
||
| **TODO** | ||
|
|
||
| ## What about classic notebook? | ||
|
|
||
| **TODO** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
Oops, something went wrong.