Koala Plot – Documentation

Docs: Line & Scatter Plots

Mon, 01 Jan 0001 00:00:00 +0000

Basics

A line plot requires a list of data points, (x, y) pairs, with the data type and in the coordinate system of the axes provided to the enclosing XYGraph. As an example, we want to plot the function \( y=x^2 \) with x from 1 to 10 with two Float axes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 val data = buildList {
 for (i in 1..10) {
 add(DefaultPoint(i.toFloat(), i * i.toFloat()))
 }
 }

 XYGraph(
 rememberFloatLinearAxisModel(data.autoScaleXRange()),
 rememberFloatLinearAxisModel(data.autoScaleYRange())
 ) {
 LinePlot(
 data,
 lineStyle = LineStyle(SolidColor(Color.Blue))
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Line1.kt

Lines 1-5 generate the data to plot. The data for Line plots is a list of x, y coordinates provided by an implementation of the Point interface. This example uses the provided implementation, DefaultPoint.

Lines 8 and 9 provide an AxisModel for each of the x and y axes to XYChart. In this case, we are using linear axes with floating point values (other types are covered in XY Graphs) and ranges that are calculated with the calls to autoScaleXRange() and autoScaleYRange().

Lines 11 through 13 call the LineChart Composable to render the line itself, using a solid blue style.

Adding a Second Line

Now lets add a second line plotting the function \( y=e^{\sqrt{x}} \), which looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


 XYGraph(
 rememberFloatLinearAxisModel(dataSquared.autoScaleXRange()),
 rememberFloatLinearAxisModel(dataSquared.autoScaleYRange())
 ) {
 LinePlot(
 dataSquared,
 lineStyle = LineStyle(SolidColor(Color.Blue))
 )
 LinePlot(
 dataExp,
 lineStyle = LineStyle(
 SolidColor(Color(0, 200, 0)),
 2.dp,
 dashPathEffect(floatArrayOf(20f, 10f))
 )
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Line2.kt

Scatter Plots

A scatter plot is very similar to a line plot, and uses the same LinePlot Composable function, except instead of lines connecting data points a symbol is drawn at each data point. In Koala Plot, the symbols are themselves Composables, and to make it even simpler provides the Symbol Composable to make it easy to use a Shape with any fill and outline. Beyond the standard Compose circle and rectangle shapes, Koala Plot also defines additional shapes that are common for graphs, such as the TriangleShape and DiamondShape.

The below example illustrates a scatter plot using the default RectangleShape used by Symbol.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


 val data = buildList {
 val random = Random(10)
 for (i in 1..50) {
 val x = random.nextDouble(1.0, 10.0).toFloat()
 val y = (x + (random.nextDouble() - 0.5) * 2.0).toFloat()

 add(DefaultPoint(x, y))
 }
 }

 XYGraph(
 rememberFloatLinearAxisModel(0f..12f),
 rememberFloatLinearAxisModel(0f..12f)
 ) {
 LinePlot(
 data,
 symbol = { Symbol(fillBrush = SolidColor(Color.Blue), outlineBrush = SolidColor(Color.Black)) }
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Scatter1.kt

Combining Lines & Symbols

Combining lines and symbols on a single XYGraph is as simple as repeatedly using LinePlot for each data series to be plotted. The below example illustrates the scatter plot from the previous example, together with a plot of a line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 val data = buildList {
 val random = Random(10)
 for (i in 1..50) {
 val x = random.nextDouble(1.0, 10.0).toFloat()
 val y = (x + (random.nextDouble() - 0.5) * 2.0).toFloat()

 add(DefaultPoint(x, y))
 }
 }
 val line = buildList {
 add(DefaultPoint(-5f, -5f))
 add(DefaultPoint(15f, 15f))
 }

 XYGraph(
 rememberFloatLinearAxisModel(0f..12f),
 rememberFloatLinearAxisModel(0f..12f)
 ) {
 LinePlot(line, lineStyle = LineStyle(SolidColor(Color.Blue)))
 LinePlot(
 data,
 symbol = { Symbol(fillBrush = SolidColor(Color.Blue), outlineBrush = SolidColor(Color.Black)) }
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Scatter2.kt

The z-order of the plots corresponds to the order in which they appear in the XYGraph, so in this example the line is plotted first, and the rectangle symbols are plotted second and draw over the line.

It is also possible to plot both lines and symbols with the same LinePlot, as illustrated below, which is a modification of the previous example plotting the function \( y=x^2 \).

1
2
3
4
5


 LinePlot(
 data,
 lineStyle = LineStyle(SolidColor(Color.Blue)),
 symbol = { Symbol(fillBrush = SolidColor(Color.Blue), outlineBrush = SolidColor(Color.Black)) }
 )

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Line3.kt

StairStep Plots

The StairstepPlot is a variant of a line plot that draws series as points and stairsteps between points. A simple example is shown below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 val data = buildList {
 for (i in 1..10) {
 add(DefaultPoint(i.toFloat(), i * i.toFloat()))
 }
 }

 XYGraph(
 rememberFloatLinearAxisModel(data.autoScaleXRange()),
 rememberFloatLinearAxisModel(data.autoScaleYRange())
 ) {
 StairstepPlot(
 data,
 lineStyle = LineStyle(SolidColor(Color.Blue))
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Stairstep1.kt

A variant of StairstepPlot lets you specify a line style for each level. This is illustrated below where the coloring of the step at each level is varied according to the y-axis value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 val data = buildList {
 for (i in 1..10) {
 add(DefaultPoint(i.toFloat(), i * i.toFloat()))
 }
 }

 XYGraph(
 rememberFloatLinearAxisModel(data.autoScaleXRange()),
 rememberFloatLinearAxisModel(data.autoScaleYRange())
 ) {
 StairstepPlot(
 data,
 lineStyle = LineStyle(SolidColor(Color.Transparent)),
 levelLineStyle = { y ->
 LineStyle(SolidColor(Color(red = y / 100f, green = 0f, blue = 0f)), strokeWidth = 4.dp)
 }
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Stairstep2.kt

Docs: Area Plots

Mon, 01 Jan 0001 00:00:00 +0000

Area plots are like line plots but with a shaded area between the line being plotted and a second reference line, referred to as the Baseline. The Baseline can be either a horizontal line (constant y-axis value) or an arbitrary line, like another line on the same XYGraph.

There are two ways to create an area plot:

Using AreaPlot with an areaBaseline, to plot 1 or more separate lines with filled areas
Using StackedAreaPlot to plot multiple lines that stack on top of each other, with filled areas between them

Plotting individual areas

The below example demonstrates plotting two separate area plots where the baseline is set to be the x-axis (horizontal line at which y=0). The lines are each plots of a normal distribution with different means and standard deviations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 AreaPlot(
 data = distribution1,
 lineStyle = LineStyle(brush = SolidColor(Color(0xFF00498F)), strokeWidth = 2.dp),
 areaStyle = AreaStyle(
 brush = SolidColor(Color(0xFF00498F)),
 alpha = 0.5f,
 ),
 areaBaseline = AreaBaseline.ConstantLine(0f)
 )
 AreaPlot(
 data = distribution2,
 lineStyle = LineStyle(brush = SolidColor(Color(0xFF37A78F)), strokeWidth = 2.dp),
 areaStyle = AreaStyle(
 brush = SolidColor(Color(0xFF37A78F)),
 alpha = 0.5f,
 ),
 areaBaseline = AreaBaseline.ConstantLine(0f)
 )

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Area1.kt

Areas can also be plotted between two arbitrary lines. The below example plots the lines \(y = 10 \times 1.04^x\) and \(y= 10 \times 1.06^x\) with a shaded area between them.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


 val data1 = buildList {
 for (i in 1..10) {
 add(DefaultPoint(i.toFloat(), 10f * (1.04).pow(i).toFloat()))
 }
 }
 val data2 = buildList {
 for (i in 1..10) {
 add(DefaultPoint(i.toFloat(), 10f * (1.06).pow(i).toFloat()))
 }
 }

 XYGraph(
 rememberFloatLinearAxisModel(0f..12f),
 rememberFloatLinearAxisModel(0f..20f),
 xAxisTitle = "",
 yAxisTitle = "",
 xAxisLabels = { it.toString(1) },
 yAxisLabels = { it.toString(1) }
 ) {
 LinePlot(
 data = data1,
 lineStyle = LineStyle(brush = SolidColor(Color(0xFF00498F)), strokeWidth = 2.dp),
 )
 AreaPlot(
 data = data2,
 lineStyle = LineStyle(brush = SolidColor(Color(0xFF37A78F)), strokeWidth = 2.dp),
 areaStyle = AreaStyle(
 brush = SolidColor(Color(0xFF37A78F)),
 alpha = 0.5f,
 ),
 areaBaseline = AreaBaseline.ArbitraryLine(data1)
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/Area2.kt

Tip

The x-axis data values for each line do not have to be the same, however for best results the first and last values should be the same, or the plot clipped by limiting the x-axis range.

Plotting stacked areas

A stack of area plots can be created by using multiple AreaPlot Composables within an XYGraph with appropriate choice of baselines. While this provides the most flexibility, it may not be the most convenient approach. For this reason Koala Plot provides StackedAreaPlot for the common situation where the first baseline is a horizontal line, typically the x-axis.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


 fun makeRandomLine(): List<Float> = buildList {
 var last = 0f
 for (i in 1..10) {
 last += random.nextFloat()
 add(last)
 }
 }

 val randomLines = List(4) { makeRandomLine() }
 val stackData = StackedAreaPlotDataAdapter(randomLines[0].indices.toList().map { (it + 1).toFloat() }, randomLines)
 val styles = List(4) {
 StackedAreaStyle(
 LineStyle(SolidColor(Color.Black), strokeWidth = 2.dp),
 AreaStyle(SolidColor(Color.Blue.copy(alpha = 0.20f * (it + 1))))
 )
 }

 XYGraph(
 rememberFloatLinearAxisModel(0f..12f),
 rememberFloatLinearAxisModel(0f..25f),
 xAxisTitle = "",
 yAxisTitle = "",
 xAxisLabels = { it.toString(1) },
 yAxisLabels = { it.toString(1) }
 ) {
 StackedAreaPlot(
 stackData,
 styles,
 AreaBaseline.ConstantLine(0f)
 )
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/StackedArea1.kt

This example uses a List<Float> for the x-axis coordinates and a List<List<Float>> for the y-axis coordinates, created on line 9. It then uses StackedAreaPlotDataAdapter, which implements List<StackedAreaPlotEntry<Float, Float>>, to present the source data in the form expected by StackedAreaPlot. This is convenient if your data is already in the form of a list for the x-axis data points and a list of lists for the y-axis data points. If not, it will be necessary to directly implement the data as List<StackedAreaPlotEntry<X, Y>> or provide a custom adapter for it.

Docs: Bar Plots

Mon, 01 Jan 0001 00:00:00 +0000

Bar Plots are also 2-D plots and are therefore plotted within an XYGraph parent. They are typically used with discrete data, and accordingly all of the examples on this page will use CategoryAxisModel for the x-axis. The y-axis can be of any data type, but the examples will all use LinearAxisModel.

Single Vertical Bar Plot

The simplest type of vertical bar plot has a single series of data, and there is a VerticalBarPlot overload to make this use case easy when using Float values for the y-axis. The below example demonstrates this to plot the population of each New York City burrough.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


@OptIn(ExperimentalKoalaPlotApi::class)
fun main() = singleWindowApplication {
 val boroughs = listOf("Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island")
 val population = listOf(1.446788f, 2.648452f, 1.638281f, 2.330295f, 0.487155f)

 XYGraph(
 xAxisModel = remember { CategoryAxisModel(boroughs) },
 yAxisModel = rememberFloatLinearAxisModel(0f..3f, minorTickCount = 0),
 yAxisTitle = "Population (Millions)"
 ) {
 VerticalBarPlot(
 xData = boroughs,
 yData = population,
 bar = { _, _, _ ->
 DefaultBar(
 brush = SolidColor(Color.Blue),
 modifier = Modifier.fillMaxWidth(),
 )
 }
 )
 }
}

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/VerticalBar1.kt

In the above example, all bars were automatically extended to the origin of the y-axis, 0. In some cases it is desirable to plot vertical bars with starting positions that are not at 0. To support this use case, there is a second form of VerticalBarPlot that allows specifying the starting and ending coordinates of each bar. The below example demonstrates using this flexibility to create a waterfall chart:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


@OptIn(ExperimentalKoalaPlotApi::class)
fun main() = singleWindowApplication {
 val categories = listOf("Initial Cash", "Q1", "Q2", "Q3", "Q4", "Final Cash")
 val colors =
 listOf(
 Color.DarkGray,
 Color(0xFF00498F),
 Color(0xFFED7D31),
 Color(0xFF00498F),
 Color(0xFF00498F),
 Color.DarkGray,
 )
 val data =
 listOf(
 verticalBarPlotEntry(categories[0], 0f, 100f),
 verticalBarPlotEntry(categories[1], 100f, 120f),
 verticalBarPlotEntry(categories[2], 120f, 90f),
 verticalBarPlotEntry(categories[3], 90f, 110f),
 verticalBarPlotEntry(categories[4], 110f, 130f),
 verticalBarPlotEntry(categories[5], 0f, 130f),
 )

 XYGraph(
 xAxisModel = remember { CategoryAxisModel(categories) },
 yAxisModel = rememberFloatLinearAxisModel(0f..150f, minorTickCount = 0),
 ) {
 VerticalBarPlot(
 data,
 bar = { index, _, _ ->
 DefaultBar(
 brush = SolidColor(colors[index]),
 modifier = Modifier.fillMaxWidth(),
 )
 }
 )
 }
}

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/VerticalBar2.kt

There is also a builder DSL for vertical bar plots, that slightly improves on the syntax. The previous example can also be implemented as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13



 XYGraph(
 xAxisModel = remember { CategoryAxisModel(categories) },
 yAxisModel = rememberFloatLinearAxisModel(0f..150f, minorTickCount = 0),
 ) {
 VerticalBarPlot {
 item("Initial Cash", 0f, 100f, solidBar(Color.DarkGray))
 item("Q1", 100f, 120f, solidBar(Color(0xFF00498F)))
 item("Q2", 120f, 90f, solidBar(Color(0xFFED7D31)))
 item("Q3", 90f, 110f, solidBar(Color(0xFF00498F)))
 item("Q4", 110f, 130f, solidBar(Color(0xFF00498F)))
 item("Final Cash", 0f, 130f, solidBar(Color.DarkGray))
 }

Tip

For improved type safety, consider using an enumeration for the CategoryAxisModel categories. If an item is added with a category value that is not a member of the list provided to the CategoryAxisModel constructor, a runtime exception will be thrown.

Stacked Bars

A stacked bar chart consists of multiple series of data, each of which have data points at the same set of x-axis values. The bars for the data at each x-axis value accumulate and stack on top of each other to form a total. The below example demonstrates a stacked bar plot showing the population for each of the 5 New York City boroughs by year.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 val boroughs = listOf("Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island")
 val years = listOf(1980, 1990, 2000, 2010, 2020)
 val colors =
 listOf(
 Color.hsv(0f, 1f, 0.7f),
 Color.hsv(72f, 1f, 0.7f),
 Color.hsv(144f, 1f, 0.7f),
 Color.hsv(216f, 1f, 0.7f),
 Color.hsv(288f, 1f, 0.7f)
 ) // 1 color per borough

 // Population data is in order of borough, then year
 val population = listOf(
 listOf(1168972, 1203789, 1332650, 1385108, 1446788), // Bronx
 listOf(2230936, 2300664, 2465326, 2552911, 2648452), // Brooklyn
 listOf(1428285, 1487536, 1537195, 1585873, 1638281), // Manhattan
 listOf(1891325, 1951598, 2229379, 2250002, 2330295), // Queens
 listOf(352121, 378977, 443728, 468730, 487155), // Staten Island
 )

 XYGraph(
 xAxisModel = remember { CategoryAxisModel(years) },
 yAxisModel = rememberFloatLinearAxisModel(0f..10f, minorTickCount = 0),
 yAxisTitle = "Population (Millions)"
 ) {
 StackedVerticalBarPlot {
 boroughs.forEachIndexed { index, _ ->
 series(solidBar(colors[index])) {
 years.forEachIndexed { yearIndex, year ->
 item(year, population[index][yearIndex].toFloat() / 1E6f)
 }
 }
 }
 }
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/StackedVerticalBar1.kt

This example uses a StackedVerticalBarPlot overload that initiates a builder api for specifying the data series and items within each series. This builder will automatically accumulate the values in a stack, and is currently implemented only for vertical axes that use Float values. An alternative is to use the other variant of StackedVerticalBarPlot, which is lower level but directly receives a List of the data regardless of types used, and requires the user to pre-accumulate the stack values.

Grouped Bars

Like stacked bars, grouped bars also plot multiple series of data with a common set of x-axis values. However in grouped bars, each series is plotted side by side in a group centered on the common x-axis value for the group. The below example demonstrates creating a grouped vertical bar plot with Koala Plot.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 val boroughs = listOf("Bronx", "Brooklyn", "Manhattan", "Queens", "Staten Island")
 val years = listOf(1980, 1990, 2000, 2010, 2020)
 val colors =
 listOf(
 Color.hsv(0f, 1f, 0.7f),
 Color.hsv(72f, 1f, 0.7f),
 Color.hsv(144f, 1f, 0.7f),
 Color.hsv(216f, 1f, 0.7f),
 Color.hsv(288f, 1f, 0.7f)
 ) // 1 color per year

 // Population data is in order of borough, then year
 val population = listOf(
 listOf(1168972, 1203789, 1332650, 1385108, 1446788), // Bronx
 listOf(2230936, 2300664, 2465326, 2552911, 2648452), // Brooklyn
 listOf(1428285, 1487536, 1537195, 1585873, 1638281), // Manhattan
 listOf(1891325, 1951598, 2229379, 2250002, 2330295), // Queens
 listOf(352121, 378977, 443728, 468730, 487155), // Staten Island
 )

 XYGraph(
 xAxisModel = remember { CategoryAxisModel(boroughs) },
 yAxisModel = rememberFloatLinearAxisModel(0f..3f, minorTickCount = 0),
 yAxisTitle = "Population (Millions)"
 ) {
 GroupedVerticalBarPlot {
 years.indices.forEach {
 series(solidBar(colors[it])) {
 boroughs.forEachIndexed { index, borough ->
 item(borough, 0f, population[index][it].toFloat() / 1E6f)
 }
 }
 }
 }
 }

/examples/src/jvmMain/kotlin/io/github/koalaplot/example/GroupedVerticalBar1.kt

Most of this example is establishing the data and the colors to use for each data series. The data series are the years, and the x-axis data values are the boroughs that make up the category axis. The key call is GroupedVerticalBarPlot which initiates a builder API for the plot. Within that api, series is used to add a new data series, which for this data are the years, and item is used to add an item to the series at a specific x-axis value and with minimum and maximum y-axis values for the corresponding bar, in this case the population data.

In this example, a unique Composable to generate a bar is provided for each series. It is also possible to specify a bar Composable for the individual item as well, if it should be rendered differently than the other bars in the series.

Note

There are two overloaded variants of GroupedVerticalBarPlot. The api builder described above, and a lower level variant that takes all of the plot data in a single parameter. The builder api delegates to the second variant, and depending on the initial form of the data to be plotted one form may be more convenient than the other.