Skip to content

JetBrains/lets-plot-kotlin

Repository files navigation

Lets-Plot Kotlin API

A Grammar of Graphics for Kotlin.

official JetBrains project License MIT Latest Release

Lets-Plot Kotlin API is a Kotlin API for Lets-Plot Multiplatform plotting library,
which is built on the principles of layered graphics first described in the
Leland Wilkinson work The Grammar of Graphics.

book cover

Lets-Plot Kotlin API is largely based on the API
provided by ggplot2 package well-known to data scientists who use R.

To learn more about the Grammar of Graphics,
we recommend an excellent book called
“ggplot2: Elegant Graphics for Data Analysis”.

This will be a good prerequisite for further exploration of the Lets-Plot library.

Quickstart

Inside Kotlin Notebook, Datalore or Jupyter with Kotlin Kernel:

%use lets-plot
val rand = java.util.Random()
val data = mapOf(
    "rating" to List(200) { rand.nextGaussian() } + List(200) { rand.nextGaussian() * 1.5 + 1.5 },
    "cond" to List(200) { "A" } + List(200) { "B" }
)

var p = letsPlot(data)
p += geomDensity(color = "dark_green", alpha = .3) { x = "rating"; fill = "cond" }
p + ggsize(700, 350)

Couldn't load quickstart_notebook.png


See the "Quickstart" notebook in Datalore or Jupyter nbviewer.

Table of Contents

Usage

Notebooks

With the help of Lets-Plot Kotlin API you can easily create plots in Kotlin Notebook, Datalore, Jupyter with Kotlin Kernel
or any other notebook that supports Kotlin Kernel.

"Line Magics"

%use lets-plot

This "line magic" will apply Lets-Plot library descriptor which adds to your notebook all the boilerplate code necessary to create plots.

By default, library descriptor is bundled with the Kotlin Jupyter Kernel installed in your environment.
However, you can override the default settings using:

%useLatestDescriptors

In this case the latest library descriptor will be pulled from the Kotlin Jupyter Libraries repository.

Library Descriptor Parameters

%use lets-plot(v=4.11.0, isolatedFrame=false)
  • v - version of the Lets-Plot Kotlin API.
  • isolatedFrame - If false: load JS just once per notebook (default in Jupyter). If true: include Lets-Plot JS in each output (default in Datalore notebooks).

Compose Multiplatform

To learn how to embed Lets-Plot charts in Compose Multiplatform applications, please check out the Lets-Plot Skia Frontend project.

JVM and Kotlin/JS

To learn more about creating plots in JVM or Kotlin/JS environment please read USAGE_SWING_JFX_JS.md.

Examples

Examples of using of the Lets-Plot Kotlin API in JVM and Kotlin/JS applications are available in the Lets-Plot Kotlin Mini Apps (Demos) GitHub repository.

Documentation

What is new in 4.11.0

  • Time Series Plotting

    • Support temporal data types from kotlinx.datetime, java.time, and java.util.
    • Support for timezone-aware java.time.ZonedDateTime and java.time.OffsetDateTime objects.
    f-25b/images/time_date_datetime.png

    See Date-time cookbook.

    f-4.11.0/images/bitcoin_trading.png

    See Bitcoin trading demo.

  • geomSina() Geometry

    f-25b/images/geom_sina.png

    See: example notebook.

  • geomTextRepel() and geomLabelRepel() Geometries

    f-25b/images/geom_repel.png

    See: example notebook.

  • waterfallPlot() Chart

    • Annotations support via relativeLabels and absoluteLabels parameters.

      f-25b/images/waterfall_plot_annotations.png

      See: example notebook.

    • Support for combining waterfall bars with other geometry layers.

      f-25b/images/waterfall_plot_layers.png

      See: example notebook.

  • Continuous Data on Discrete Scales

    Continuous data when used with discrete positional scales is no longer transformed to discrete data.
    Instead, it remains continuous, allowing for precise positioning of continuous elements relative to discrete ones.

    f-25b/images/combo_discrete_continuous.png

    See: example notebook.

Tip

New way of handling continuous data on discrete scales could potentially break existing plots. If you want to restore a broken plot to its original form, you can use the asDiscrete() function to annotate continuous data as discrete.

  • Plot Layout

    The default plot layout has been improved to better accommodate axis labels and titles.
    Also, new theme() options axisTextSpacing, axisTextSpacingX, and axisTextSpacingY control spacing between axis ticks and labels.

    f-25b/images/plot_layout_diagram.png

    See new Plot Layout Diagrams showing various layout options and their effects on plot appearance.

  • And More

    See CHANGELOG.md for a full list of changes.

Recent Updates in the Gallery

Creating magnifier inset effect with ggbunch() Customize legend appearance Zoom and Pan interactivity The observable LP-verse Sunshine hours Unemployment in the US since 1967

Change Log

See CHANGELOG.md.

Code of Conduct

This project and the corresponding community are governed by the JetBrains Open Source and Community Code of Conduct. Please make sure you read it.

License

Code and documentation released under the MIT license. Copyright © 2019-2025, JetBrains s.r.o.