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!

[Fil]

the povcalnet example can be simpler:

  Plot.rectY(povcalnet, Plot.stackX({
      filter: d => ["N", "A"].includes(d.CoverageType),
      x: "ReqYearPopulation",
      order: "HeadCount",
      reverse: true,
      y2: "HeadCount", // using y2 to escape Plot.stackX's default stacking by *y*
      title: d => `${d.CountryName}\n${(d.HeadCount * 100).toFixed(1)}%`,
      insetLeft: 0.2,
      insetRight: 0.2
    })),

Plot fully embraces ES6 and it can take some time to get used to splatting and destructuring, but is it really more difficult to grasp than the rest of javascript syntax? (Honest question.)

[git-ashish]

I agree and feel that it does take some time to get used to these ES6 JavaScript syntax. Additionally, seeing such syntax in examples for the first time may appear perplexing because one may not be aware of what something like Plot.stackX({..}) is doing/returning, especially for beginners.
Maybe in documentation, the examples could be split between beginner and advanced usage guides. Also, the default examples could use simpler notations assuming a general user is not adept in JavaScript. Thoughts?