stacks

[Fil]

(this is #132, rebased on #176)

• Negative values always result in diverging stacking. (By contrast, in d3-shape an explicit diverging offset must be invoked.)
• Offsets: expand and silhouette are similar to d3-shape, but taking into account negative values. wiggle…
• Series can be grouped by z, fill, stroke, title…
• The cumulative sum happens in a configurable ranking order; built-in orders are:
• data order (will be passed up to the stackArea or stackLine mark)
• stacking works as expected with faceting (see https://observablehq.com/@data-workflows/u-s-population-by-state-1790-1990)

changes wrt #132:

• makes y optional when stacking (defaults to unit y: () => 1 )
• compared to Stack #132 it removes stacked lines and the "mid" value — but the price is high in terms of complexity (see the policeDeaths example, as well as https://observablehq.com/@data-workflows/u-s-population-by-state-1790-1990 )
• adds test plots
• data transform ƒ and filtering is left to the general discussion (A generic filter transform to hide marks (perhaps usable together with sort for line and area)? #138)

See API documentation at https://observablehq.com/@data-workflows/plot-stack-options

Test plots:

• caltrain stem & leaf
• wiggle streamgraph (RIAA music industry US revenue)
• police deaths
• unemployment by industry
• congress members by age (stack = unit)
• congress members by age/gender
• https://observablehq.com/@data-workflows/u-s-population-by-state-1790-1990

supersedes #110
supersedes #132
closes #109
closes #22
closes #113

[mbostock]

Two outstanding questions:

There are a number of places that call array.indexOf (the sort option, rank = sum, rank = appearance, rank = insideOut, and rank = array of values). This probably means quadratic performance. Can we implement these so they are more efficient?

Do we need the sort option? There aren’t any examples that use it yet. That would eliminate one of the uses of array.indexOf, too.

[Fil]

The sort option is used only in the case of the wiggle offset, which tries to minimize the differences from one location to the next. We could ignore it, with a caveat that the wiggle offset needs data sorted on x to get the correct result. And in any case, the option is passed up to areaY.
Re: indexOf, most of those could be changed to a Map, where performance is a concern?

[mbostock]

The sort option is a subset of the transform composition problem we were discussing in the other thread. I think it’s best to remove the option for now and instead implement a more general solution such as an array of transforms. Also, while the sort option is passed through to the next mark, it will be ignored because Plot.stack defines the transform option which takes priority over the sort option; the sort option is just shorthand for a transform, but is ignored if a transform is explicitly specified.

Yes, I think we should use a Map or similar instead of indexOf. Are you able to do that this morning, or should I?

[mbostock]

Okay, a few last (?) things:

• The offset option should be coerced to a string and lower-cased (if not nully), similar to how we parse the curve option for line and area, and scheme for color scales.
• The rank option similarly needs some sort of normalization, but it’s more complicated because we don’t want to lower-case if it’s a field name (and I’m still wondering if we can avoid ambiguity somehow).
• The rank.indexOf test should be replaced… There isn’t a strong array-or-iterable test, so maybe we should just assume it’s an array of iterable if it’s not a string, null, undefined, or a function. We want it to crash if it’s not one of the expected values.

[mbostock]

Oh, and z || fill || stroke || title probably needs to use undefined or null testing.

[mbostock]

Almost there. Question: should rank be renamed to order to match D3’s stack.order? I know they are not exactly the same, but I don’t totally grok whether “rank” is a more expressive term than “order” here, or if it’s different just for the sake of being different. Related #179.

[mbostock]

I realized I misunderstood the behavior of the order (formerly rank) option: when an array of values, it’s effectively an ordinal domain for the z dimension; it’s a partial ordering of series rather than a complete ordering of data as suggested in #179. This also means that the array interpretation is different than the function and field variants, as the latter produce complete orderings. I’m going to break things for a bit as I think through this design some more.

[Fil]

Naïve Q: I don't understand what this optimizes?

[mbostock]

array.unshift is an O(N) operation on an array of length N, so if it’s done O(N) times the total is O(N²). Where as array.push is O(1) and array.reverse and array.concat are O(N), so the total is O(N). It won’t matter much in practice since N is typically very low here (the number of distinct values in z), but it’s not hard to do efficiently either, so I did.