More control over series formatting

[colin-young]

While automated assignment of colors makes for a quick and easy initial setup, sometimes it would be nice to have more control, e.g. where you have multiple charts showing a mix of shared and unique series, you might want to be able to have the shared series show up with the same style and color across all charts.

e.g. in this example, the short trend line (green in top, red in bottom chart) should be the same color in both charts, and ideally it would be dashed, while all others are solid.

One possible implementation, keeping in mind I'm not an expert in the grammar of graphics:

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'amount', color: 'series')
  .geomLine(strokeWidth: 1.0)
  .seriesLine(key: 'trend', style: LineStyle.dashed, strokeWidth: 3.0, color: Colors.green)
  .seriesLine(key: 'current', strokeWidth: 3.0)
  // ...
  .build();

Where seriesLine overrides the auto-selected color/style that is set from the theme and geomLine settings for the line identified by the value of the 'series' property. Any values in 'series' that do not have an override will use existing behavior for color and line style, e.g. for series = current since there is no override for color, it will use the colorPalette of the theme. For simplicity of implementation, if a color should not be used for any series other than the override, it should not be included in the theme's colorPalette. i.e. if we did not want to allow green solid lines for any other series, we would exclude green from the palette; if instead we wanted to allow other series to appear as a green solid line, we would include green in the palette. There would be similar seriesArea, seriesPoint, etc. to allow override of other representations.

An alternative syntax could be (shamelessly stolen adapted from Google's LLM summary of ggplot2):

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'amount', color: 'series')
  .geomLine(strokeWidth: 1.0)
  .geomLine(data: subset(key: 'trend'), style: LineStyle.dashed, strokeWidth: 3.0, color: Colors.green)
  .geomLine(data: subset(key: 'current'), strokeWidth: 3.0)
  // ...
  .build();

[colin-young]

On further thought, the second syntax is more flexible, as it would allow for:

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'amount', color: 'series')
  .geomLine(strokeWidth: 1.0)
  .geomArea(data: subset(key: 'trend'), style: LineStyle.dashed, strokeWidth: 3.0, color: Colors.green)
  .geomRange(data: subset(keys: ['min', 'max']), barWidth: 3.0) // EDIT: this won't work, at least not as presented
  // ...
  .build();

Which would draw an area for 'trend', a new type I just invented called 'range' for the 'min' and 'max' series, and lines for all other series. This shares some features of the secondary axis, but would offer the ability to use more representations, and free the secondary axis for having a different scaling than the primary (I'll assume the user has good reason for doing so).

EDIT: The geomRange concept isn't going to work, at least not the way I've presented it here. Shouldn't have tried to combine 2 concepts in one post. I'll have to think on that one a bit more.

[rudi-q]

Hey again👋 @colin-young

Thanks for suggesting this.
I thought about it and implemented a solution for the color consistency and better per-category color customization in v1.4.0.

You can find the full code in the example app and here: https://docs.cristalyse.com/features/theming#using-custompalette

You can now use the 'customPalette()' method to set colors for categories. I hope this helps with what you were trying to achieve 🙂

// Now you can ensure 'trend' is always green across all charts:
final sharedColors = {
  'trend': Colors.green,
  'current': Colors.blue,
  'baseline': Colors.grey,
};

// Chart 1
CristalyseChart()
  .data(data1)
  .mapping(x: 'time', y: 'amount', color: 'series')
  .geomLine()
  .customPalette(categoryColors: sharedColors)
  .build();

// Chart 2 - 'trend' will be the same green!
CristalyseChart()
  .data(data2) 
  .mapping(x: 'time', y: 'amount', color: 'series')
  .geomLine()
  .customPalette(categoryColors: sharedColors)
  .build();

Regarding the per-series stroke control, it would be nice to have that feature but I would need sometime to think about the implementation.

[colin-young]

Nice. I especially like the addition of copyWith to the theme. That was on my list to make a suggestion about.

For a per-series stroke control, I think that the same mechanism as color could be leveraged. e.g. _drawLinesAnimated takes a ColorScale (effectively a map of group name to color) and a LineGeometry, a single definition of a line. Enhancing that with a similar LineGeometryScale would allow managing multiple line type definitions. As for creating the definitions of the line types, a similar approach to colors should work. At least that's my first impression from a cursory examination of the code.

That said, I think my second syntax is more concise and easier to read, by keeping the full definition of the aesthetic specification together. I also think it can be easily implemented in a backward-compatible way with the 1.4.0 implementation, e.g.

if key not in colorScale then
  insert key and color into colorScale
else
  update colorScale key with color
end if

You'd retain the option of explicitly setting a customPalette, but in the background both mechanisms would just merge their specifications into the colorScale. This assumes later definitions override earlier ones.

I also think that syntax makes it easier to generate more sophisticated charts, e.g. a plot of points and a best-fit line, or for a more complex example see chart 3 here, without resorting to hacks like a second axis, unless you do in fact need a second axis with a different scale, in which case it's not a hack.

Using a GeometryScale could also simplify supporting multiple representations, if instead of having a geometry manage drawing all the data it only managed drawing the data it was assigned to. At least at a very high level that's how I'd approach solving it. I might even go so far as to create a AestheticScale that contains color, geometry, stroke, fill, etc. rather than tracking color and geometry separately.

Updated proposed syntax, maintaining compatibility with existing code:

CristalyseChart()
  .data(data)
  .mapping(x: 'time', y: 'amount', group: 'series') // new 'group' for grouping, color still supported for backward compatibility
  .geomLine(aesthetic: {strokeWidth: 1.0}) // default, existing functionality
  .geomArea(
        data: {key: 'trend'}, 
        aesthetic: {
            style: LineStyle.dashed, 
            strokeWidth: 3.0, 
            color: Colors.green,
        },
  ) // applies to 'trend' group
  .geomRange(
        data: {
                key: 'range',
                mapping: {
                    min: 'min',
                    max: 'max',
                },
        },
        aesthetic: {barWidth: 3.0},
  ) // applies to 'range' group and defines an additional mapping
  // ...
  .build();

[colin-young]

I made some progress:

• scaling for axis (in particular, respecting min value)
• dashed and dotted strokes for line charts
• specify full aesthetics per series for line charts (color, stroke, style)
• new range area type

I still need to verify backwards compatibility (should be, but must verify), add test coverage, create examples, and documentation. I'll work on those and get a PR cleared to submit, hopefully later this week.

Here's the code:

return CristalyseChart()
    .data(data)
    .theme(getChartTheme(context, showAxis, showGridLines))
    .mapping(x: 'time', y: 'amount', color: 'series', size: 'amount')
    .scaleXContinuous(
      labels: (val) => DateFormat(DateFormat.ABBR_MONTH_DAY,).format(DateTime.fromMillisecondsSinceEpoch(val.toInt())),
      min: minDate.millisecondsSinceEpoch.toDouble(),
      max: DateTime.now().millisecondsSinceEpoch.toDouble(),
    )
    .scaleYContinuous(min: 0, max: maxValue)
    .animate(duration: Duration(milliseconds: 0))
    .geomLine(key: 'current', color: Colors.green, style: LineStyle.solid, strokeWidth: 3.0, dotSpacing: 3.0)
    .geomLine(key: 'trend', color: Colors.blueGrey, style: LineStyle.dashed, strokeWidth: 3.0, dashPattern: [12.0, 8.0])
    .geomRange(key: 'current', lower: 'min', upper: 'max', color: Colors.lightBlueAccent, alpha: 0.25)
    .build();

Here's a better view of the dashed lines. I'm particularly happy about the way they are continuous around the points:

But dotted lines are still giving me grief at the ends of segments: