mark initializers

[mbostock]

This introduces a concept of a mark “initializer” which is allowed to redefine the mark’s (possibly faceted) index and channels, and by extension, the plot’s scales. The mark’s initialize option is a function that is passed the facets and channels returned previously by mark.initialize, and returns an object which may specify new facets and channels. This PR includes an example of implementing hexbins as an initializer. This is a refinement of the previous design of “layouts” #648 #711 #713 #740 #775; I wanted to move away from the term “layout” since it implies position whilst initializers are more generic. But I am open to going back to “layout” or other alternatives.

Building on #799, this also makes a few improvements to internal APIs:

• mark.initialize now returns a {facets, channels} object rather than {index, channels} (like transforms).
• channels are now represented as an object e.g. {x: {value}} rather than an array ["x", {value}].

While it is possible to call mark.initialize externally and hence this could be considered a backwards-incompatible change, this method is undocumented so I think it is acceptable to make this change. Also, it is now more convenient for debugging.

TODO:

• Throw an error if initializers define new positional (x and y) scaled channels? Not going to worry about it.
• When initializers return new scaled channels, merge with existing scaled channels when reconstructing scales.
• Add hexagon symbol.
• Decide on the definition of radius for hexagons.
• Add hexgrid decoration mark.
• Add circle and hexagon dot shorthand.
• Implement the hexbin transform as an initializer (including support for faceting).
• Implement the filter option for the hexbin transform (to show empty hexbins)? Not now.
• Implement implicit group by z in the hexbin transform? z hexbins #810
• Implement sorting of hexbins? z hexbins #810
• Is radius the right name of the option that controls hexbin size? binWidth? z hexbins #810
• Inline and optimize the implementation of d3-hexbin z hexbins #810
• Implement the dodge transform as an initializer. dodge #809
• Add documentation. document layouts (as "scale-aware transforms") #819
• Add tests. z hexbins #810
• Allow composition/chaining of initializers? exploring initializers composition #818

[Fil]

#803 for the radius of hexagons

[Fil]

#804 tries to implement hexbin as an options transform (adding an initializer)

[Fil]

Re: the name radius, I scoured the documentation of other libraries quickly and found that (I may have missed some information):

• matplotlib, pandas, holoviz use gridsize which can be given two numbers (integers?) to set the correct aspect-ratio. The numbers represent the actual number of hexagons in the x and y dimensions.
• bokeh uses size (in data space) and aspect_scale.
• ggplot2 uses binwidth (a 2d vector in data space); and defaults to nice ticks in data space.

In that regard, Plot's approach of binning in screen space is rather unique (and imho preferable).

(Note that some of these libs also offer a choice of orientation (pointy-top vs flat-top); we could do arbitrary orientation.)

Overall this doesn't tell us which name to use if we want to move away from radius—only a few names to avoid :)

[Fil]

Still on the todo-list

• "filter: null" (not actually a filter, it means we'll have to actively enumerate the centers)

Ready:

• z hexbins #810 (includes sort hex bins by radius (descending) #808 and inline/optimized hex bins)
• dodge #809

[Fil]

Browsed a base of synonyms, here are a few words that could replace layout:

design, layout, encoding/encode, variation/variant, derivation, profile, blueprint, organization, plan, outline, formation, pattern, construction, structure, disposition, makeup, skeleton, anatomy, architecture, stencil, markings, mold, cast, stamp, arrangement/arrange.

In bold a few of the ones that could "work".

[Fil]

For the hexbin radius, another name could be the step (ie distance between neighboring hex centers); however in that case it should be sqrt(3) times the current radius. But it might be easier to explain!

[Fil]

For composition of initializers, see #818

[Fil]

I've added refs to several pull-requests in the original description.

[mbostock]

I have extensively reviewed (and amended) this PR and plan on merging tomorrow. If anyone wishes to make any final words before I merge please speak now! 🙏

[mbostock]

We should probably draw the axes on top? Although the grid lines should still be underneath…

[Fil]

draw the axes on top?

This should be a generic issue (in my view the axes should be displayed on top of areas and below lines… which is neither top nor bottom). Also we could use clip: true in this example.

[mbostock]

I’ve reverted the default sort by descending r for the hexbin transform because it feels like it should be handled more appropriately at the dot mark level, or possibly at the generic mark level. And in a sense it is already by the basic sort transform, but that isn’t supported after an initializer, and maybe we want to have default sorting for dots, too.