Kandy is an open-source plotting library for Kotlin that provides a powerful and flexible DSL for creating graphs and utilizes various popular engines.
- Cross-platform compatibility — Works effortlessly within Kotlin notebooks on various platforms, including IntelliJ IDEA, Datalore, and Jupyter, as well as in standard Kotlin projects.
- Swing rendering — Features Swing rendering for outputs in the Kotlin Notebook plugin.
- Interactive Chart features — Includes interactive tooltips for charts rendered in HTML and Swing.
- Multiple format export — Allows charts to be saved in various formats like
svg,png,html,jpg/jpeg, andtiff. - Kotlin collections and DataFrame support — Seamlessly integrates with Kotlin collections and allows graph construction using Kotlin DataFrame, especially suitable for hierarchical dataframes.
- Type and null safety — Ensures type safety and Kotlin null safety.
Inspired by The Grammar of Graphics.
Inside Kotlin Notebook, Datalore or Jupyter with Kotlin Kernel:
%use kandy
plot {
bars {
x(listOf("first", "second", "third"))
y(listOf(7, 3, 5))
}
}
For guidance on getting started, additional examples, and tutorials, please refer to our documentation.
Kandy is a Kotlin library that provides a flexible and idiomatic DSL for creating various types of charts, leveraging different visualization libraries. The library aims to make it easy and quick for users to create both basic and complex charts with many parameters and settings, without the need for lengthy documentation. Depending on the task, users can choose from different engines for the perfect visualization.
Kandy integrates with Kotlin DataFrame,
another Kotlin library for working with data, allowing for a seamless transition from data processing to final
visualization.
Additionally,
integration with kandy-lets-plot in Kotlin Notebook
enables high-speed chart rendering and the ability to work with large amounts of data without delays or waiting.
The library comprises the following modules:
kandy-api— This module provides a simple-to-use API for creating charts.kandy-lets-plot— This module offers an implementation of the Lets-Plot library, which is based by Leland Wilkinson work The Grammar of Graphics and is a proven tool for creating visualizations.kandy-echarts— This module provides an implementation of the Apache ECharts library, which is a widely used tool for creating interactive visualizations.
val weatherData = mapOf(
"time" to listOf(0, 1, 2, 4, 5, 7, 8, 9),
"temperature" to listOf(12.0, 14.2, 15.1, 15.9, 17.9, 15.6, 14.2, 24.3),
"humidity" to listOf(0.5, 0.32, 0.11, 0.89, 0.68, 0.57, 0.56, 0.5)
) // Combine data into a map
plot(weatherData) { // Begin plotting
x("time") // Set x-axis with time data
y("temperature") { // Set y-axis with temperature data
// Define scale for temperature (y-axis)
scale = continuous(0.0..25.5)
}
bars { // Add a bar layer
fillColor("humidity") { // Customizing bar colors based on humidity
// Setting the color range
scale = continuous(range = Color.YELLOW..Color.RED)
}
borderLine.width = 0.0 // Define border line width
}
line {
width = 3.0 // Set line width
color = Color.hex("#6e5596") // Define line color
type = LineType.DOTDASH // Specify the line type
}
layout { // Set plot layout
title = "Simple plot with kandy-lets-plot" // Add title
// Add caption
caption = "See `examples` section for more\n complicated and interesting examples!"
size = 700 to 450 // Plot dimension settings
}
}
You can get this example as a notebook, as Datalore notebook, or as a Kotlin project.
val dataset = mapOf(
"days_of_week" to listOf("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"),
"evaporation" to listOf(2.0, 4.9, 7.0, 23.2, 25.6, 76.7, 135.6),
"precipitation" to listOf(2.6, 5.9, 9.0, 26.4, 28.7, 70.7, 175.6),
"temp" to listOf(2.0, 2.2, 3.3, 4.5, 6.3, 10.2, 20.3)
)
plot(dataset) {
x("days_of_week"<String>())
bars {
name = "Precipitation"
y("precipitation"<Double>()) { scale = continuous(0.0..200.0) }
color("temp"<Double>()) { scale = continuous(range = Color.GREY..Color.BLUE) }
label {
position = LabelPosition.TOP
formatter = "{@precipitation} ml"
}
}
line {
name = "Evaporation"
y("evaporation"<Double>())
symbol = Symbol.diamond(20.0)
}
layout {
title.text = "Precipitation and evaporation per week"
legend {
left = 50.pct
bottom = 0.px
}
}
}
You can get this example as a notebook, as a Datalore notebook, or as a Kotlin project.
More examples of working with the library can be found here.
For more detailed instructions on how to get started with Kandy, refer to the Getting Started.
You can use Kandy in Kotlin-supported notebooks, namely in Kotlin Notebook, Datalore, and Kotlin Jupyter Notebook.
You can include all the necessary dependencies and imports in the notebook using line magic:
%use kandy
You can use %useLatestDescriptors
to get the latest stable version without updating the Kotlin kernel or manually specify the version:
%useLatestDescriptors
%use kandy
or
%use kandy($kandy_version)
Refer to the documentation on "line magic" for details.
Available descriptors:
kandy— includes an API, implementation of Lets-Plot, DSL features, and DataFrame supportkandy-echarts— includes an API, implementation of ECharts, DSL features, and DataFrame support
Add dependencies (you can also add other modules that you need):
dependencies {
implementation("org.jetbrains.kotlinx:kandy-lets-plot:$kandy_version")
}Make sure that you have mavenCentral() in the list of repositories:
repositories {
mavenCentral()
}Read the Contributing Guidelines.
This project and the corresponding community are governed by the JetBrains Open Source and Community Code of Conduct. Please make sure you read it.
Kandy is licensed under the Apache 2.0 License.
