DevLog 20250610: Plotting in Divooka

#plotting #librarydevelopment #divooka #analytics

Overview

Plotting is one of those things people take for granted - only when you need it does its absence become painfully obvious. It's often viewed as "solved" - until it's time to implement your own.

The Design Principles

The goal of the plotting API in Divooka is to provide a very high-level, easy-to-use (ideally single-node) setup for common plot types: you just supply the source data, pick the plot type, behold and voila - you get the resulting chart. In the case of the Plotting toolbox, the results are static images.

This scheme allows some fairly complex plot types, as seen here:

However, things can become tricky when we want to support advanced style configurations, for which the convention is to expose data on a node as direct inputs and style configurations as a separate Configurations input, as discussed in this blog article.

The real challenge is to support creating advanced custom plot types without sacrificing clarity - in which case we have to use OOP under the dataflow (functional programming) constraint:

For convenience and other practical reasons, we also want to support text-based methods like Mermaid - in our case, it's called Dhole.

Designing API for Custom Plot Types on Top of ScottPlot

We have chosen ScottPlot as our underlying drawing backend, and we know it supports a host of features - now we need to design a Divooka API or wrapper of some sort so that it exposes the same feature set without exposing underlying ScottPlot types to avoid explicit dependencies.

ScottPlot 5.0 has a nice compositional API built in:

ScottPlot.Plot myPlot = new(); myPlot.Add.Signal(Generate.Sin(51)); myPlot.Add.Signal(Generate.Cos(51)); myPlot.Layout.Frameless(); myPlot.DataBackground.Color = Colors.WhiteSmoke;

And you can procedurally add elements with object instances:

ScottPlot.Plot myPlot = new(); ScottPlot.Plottables.LinePlot line = new() { Start = new Coordinates(1, 2), End = new Coordinates(3, 4), }; myPlot.Add.Plottable(line);

One way to create a wrapper library is to create wrappers for all types and Add.XXX methods in Divooka:

// ScottPlot.PlottableAdder namespace ScottPlot { public class PlottableAdder { public PlottableAdder(ScottPlot.Plot plot); public ScottPlot.Plot Plot { get; } public ScottPlot.IPalette Palette { get; set; } public ScottPlot.Color GetNextColor(System.Boolean incrementCounter); public ScottPlot.Plottables.Annotation Annotation(System.String text, ScottPlot.Alignment alignment); public ScottPlot.Plottables.Ellipse AnnularEllipticalSector(ScottPlot.Coordinates center, System.Double outerRadiusX, System.Double outerRadiusY, System.Double innerRadiusX, System.Double innerRadiusY, ScottPlot.Angle startAngle, ScottPlot.Angle sweepAngle, Nullable<ScottPlot.Angle> rotation); // ... more methods ... public ScottPlot.Plottables.VerticalSpan VerticalSpan(System.Double y1, System.Double y2, Nullable<ScottPlot.Color> color); } }

Which, as you can see above, is a lot.

ScottPlot Plottable Types: ScottPlot.IPlottable.cs ScottPlot.Plottables.Annotation.cs ScottPlot.Plottables.Arrow.cs ScottPlot.Plottables.AxisLine.cs ScottPlot.Plottables.AxisSpan.cs ScottPlot.Plottables.BarPlot.cs ScottPlot.Plottables.Benchmark.cs ScottPlot.Plottables.BoxPlot.cs ScottPlot.Plottables.Bracket.cs ScottPlot.Plottables.Callout.cs ScottPlot.Plottables.CandlestickPlot.cs ... ScottPlot.Plottables.VerticalLine.cs ScottPlot.Plottables.VerticalSpan.cs ScottPlot.Plottables.ZoomRectangle.cs

Creating a wrapper for each of those is not too difficult - it's mechanical and can probably be sped up with ChatGPT, but the biggest concern is maintainability and the process can be error-prone during initial setup. A shortcut is to expose the ScottPlot namespace and types directly, since the API already sort of supports compositional use, but we don't want to create such explicit dependencies.

A workaround (or middle ground) is that in Divooka we can create a bunch of factory methods and indirectly expose the Plottables as return values.

internal class CustomPlot { public record OtherConfigurations(string Title, string XAxisLabel, string YAxisLabel); public static PixelImage GeneratePlot(int width, int height, IPlottable[] plottables, OtherConfigurations styles) { ScottPlot.Plot plot = new(); foreach (var item in plottables) plot.Add.Plottable(item); if (!string.IsNullOrEmpty(styles.Title)) plot.Title(styles.Title); if (!string.IsNullOrEmpty(styles.XAxisLabel)) plot.Axes.Bottom.Label.Text = styles.XAxisLabel; if (!string.IsNullOrEmpty(styles.YAxisLabel)) plot.Axes.Left.Label.Text = styles.YAxisLabel; return plot.ConvertScottPlotToPixelImage(width, height); } }

However, this is not enough shielding - to vamp it up a level, we just need to define our own Plottable.

public class Plottable { internal IPlottable Underlying; public void SetProperty(string attribute, object value) { // Set actual property of the underlying object... } }; public static PixelImage GeneratePlot(int width, int height, Plottable[] plottables, OtherConfigurations styles) { ScottPlot.Plot plot = new(); foreach (var item in plottables) plot.Add.Plottable(item.Underlying); // ... }

In addition to factory methods, we can provide a bunch of text-based WithXXX methods to provide a functional re-configuration of data and plottable-specific properties:

public static Plottable WithData(Plottable original, double[] vector) { // ... } public static Plottable WithLegendText(Plottable original, string text) { // ... }

The end result is that we wrote minimal code, avoided having to create a custom wrapper for every plottable, while still largely making use of existing ScottPlot components and exposing a fully functional API in Divooka for custom plotting.