Plot Spec design, function chaining & semantics

[ericemc3]

Compared to vega or vega-lite specs, vega-lite API brought me a much better programming comfort: chained & structured syntax, function composition, explicit verbs with few arguments, which is what D3 is originally all about.

So when I discovered Plot's syntax, I felt a great moment of perplexity, especially when reading some highly nested snippets like :
Plot.text(stocks, Plot.selectLast(Plot.normalizeY({})
or
Plot.rectY(povcalnet, {...Plot.stackX({filter: d => ["N", "A"].includes(d.CoverageType)

I'm still struggling to read many of Plot "specifications", this large, composite, heterogeneous JS object. It requires a real memorizing effort to remember what each parameter is used for, the order in which they should appear (Plot.group...), which parameters are mandatory and which are optional.

It also requires a good knowledge of D3 concepts (scales, axis, channels...) and a high level of JS mastery. It is not easy to make this accessible to beginners in web data-visualization.

I understand that such a structure is easier to deal with for the library designers, but would it be possible to improve the overall readability, by introducing a little bit more semantics?

Currently, I discern two high-level "concepts": marks and facet, and a more heterogeneous succession of properties which can be channels (mixing scale and axis definitions) or general composition options.

I would see the following general structure:

• config: sizing properties, margins, locale, titles/sources, legend position, associated CSS styles, rendering format (svg/png)...
• scales/channels: visual properties, associated conversion functions, axis and legend configurations
• marks (or layers)
• facet

ggplot2 and vega-lite Api use a chained, functional syntax, it would be interesting to know why Plot's design is different, which criterias are favoured (extensibility, legibility, intuitiveness, performance, compatibility with Observable?)

PS: Plot is a great library, very intellectually stimulating, and the 21 beautifully written articles in the https://observablehq.com/collection/@observablehq/plot collection should be read by all data scientists!