Zero-dimensional grouping.

[mbostock]

Fixes #261.

This introduces a new groupZ transform that groups only on the first of {z, fill, stroke}; it ignores x and y. The default output channel is fill, but convenience aliases groupZX, groupZY, and groupZR are provided to output to those respective channels.

The x channel is now optional to the groupX transform; if missing, it groups only on the first of {z, fill, stroke}, like groupZY. Same for the y channel for the groupY transform, and the x and y channels for the group transform.

The groupX transform now never groups on y and the groupY transform now never groups on x; use the group transform if this is desired.

For example, for a one-dimensional stacked bar chart:

Plot.barX(penguins, Plot.stackX(Plot.groupZX({fill: "species", normalize: true})))

There’s still a lot of overlap between the group transform and the reduce transform, which behaves differently. I think we should try to unify the code, and I think the grouping behavior of the reduce transform should probably behave like the group transform in this PR (meaning there probably should be a variant of reduce that groups on x and y, and a variant that groups on neither).

[mbostock]

This is needed to detect Plot.identity as the default value. Related #262.

[mbostock]

Like, I think if the group transform supported configurable outputs like the reduce transform currently does, rather than only being able to compute the frequency channel (L), then the group transform could subsume the reduce transform.

Edit: Although, reducing code duplication isn’t particularly urgent. I think the real urgency is that the API feels consistent from the outside.

[Fil]

I can see how Plot.barY(data, groupX({x: "dim"})) is similar to:

Plot.barY(data, Plot.reduceX({ x: ([x]) => x, y: d => d.length  }, {x: "dim", y: "dim"}))

(But this can't be extended to normalize, I think?).

Not sure if unifying means that groupX would become a shorthand for a more complete reduceX, or would share a similar API with {outputs}, {options}.

Sorry this is not super helpful, I'm beginning to get a bit lost with all the new names. I think I'll need an index card for transforms, like the one for marks.

[mbostock]

• group - group on x, y, and {z, fill, stroke}, output to fill (by default)
• groupR - group on x, y, and {z, fill, stroke}, output to r
• groupX - group on x and {z, fill, stroke}, output to y (by default)
• groupY - group on y and {z, fill, stroke}, output to x (by default)
• groupZ - group on {z, fill, stroke}, output to fill (by default)
• groupZX - group on {z, fill, stroke}, output to x
• groupZY - group on {z, fill, stroke}, output to y
• groupZR - group on {z, fill, stroke}, output to r

[mbostock]

Okay, I’m going to land this so I can resume working on documentation, but let me know if you have thoughts.

[Fil]

The current list is convenient, but I wonder if it would not be more memorable if we did this list:

• groupXY - group on x, y and z, out: fill (by default)
• groupX - group on x and z, out: y (by default)
• groupY - group on y and z, out: x (by default)
• group - group on z, out: fill (by default)

any non-default output would have to use an explicit {out: "r"}. Maybe less convenient though.

[mbostock]

@Fil If we did that, then I think we’d need to rename marks e.g. Plot.cell ↦ Plot.cellXY, Plot.dot ↦ Plot.dotXY.

[Fil]

Ah, true. Here's another suggestion, where the capital letter only denotes the out channel:

• group - group on x, y, z, out: fill (by default)
• groupX - group on x, y, z, out: x, y: identity (by default)
• groupY - group on x, y, z, out: y, x: identity (by default)
• groupR - group on z, out: r

This would mean switching groupX and groupY.

In the examples:

• barY(…groupX) would become barY(…groupY)
• Plot.barY(data, Plot.stackY(Plot.groupX({x: "species", fill: "island"}))) would become Plot.barY(data, Plot.stackY(Plot.groupY({x: "species", fill: "island"})))

(If I'm not mistaken) this approach seems more consistent (the letter denotes only the out channel instead of in/out; we use X throughout for horizontal bars), and introduces less symbols. I've created a branch to test it: #266