mark-level facets (#1085)

* define facets from each mark

* allow facet: "exclude" in mark faceting

this changes one unit test as it does not maintain the data order in the exclude facet. but that order was kinda arbitrary anyway. Use an explicit sort transform if necessary.

* a bit more documentation

* unnecessarily polish multiplication table test

* stricter/looser facet validation

* add TODO

* remove and simplify the weird parts (j, empty facet determination)
add a test plot with mark-level facets and exclude
clarify comments
simplify
proper facet look-up for grid lines

* clean up filterFacets

* fix comments

* regroup all facet handling, simplify

* inline maybeFacet; improve backwards compatibility

* minimize diff

* comments

* clean

* fix tests

* minimize diff

* keep top-level facet state separate

* avoid re-initializing fx and fy channels

* TODO re. applyScaleTransforms

* prettier

* adopt InternMap; remove sorting

* nullish, not undefined

* style

* remove TODO

* fx and fy aren’t in mark.channels

* remove todo

* fix comment

* use groups

* tighten state

* sparse facetsIndex

* simpler facetsIndex initialization

* small consolidation

* compute exclude facet index earlier

* simpler facet channels collection

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

README.md

@@ -569,6 +569,21 @@ Plot.plot({
 
 When the *include* or *exclude* facet mode is chosen, the mark data must be parallel to the facet data: the mark data must have the same length and order as the facet data. If the data are not parallel, then the wrong data may be shown in each facet. The default *auto* therefore requires strict equality (`===`) for safety, and using the facet data as mark data is recommended when using the *exclude* facet mode. (To construct parallel data safely, consider using [*array*.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on the facet data.)
 
+Alternatively, facets can be defined for each individual mark by specifying the channel options **fx** or **fy**. In that case, the **facet** option only considers the mark data, and the default *auto* setting is equivalent to *include*. Other values of the *facet* option are unchanged: null or false disable faceting, and *exclude* draws the subset of the mark’s data *not* in the current facet.
+
+```js
+Plot.plot({
+  marks: [
+    Plot.dot(penguins, {
+      x: "culmen_length_mm",
+      y: "culmen_depth_mm",
+      fx: "sex",
+      fy: "island"
+    })
+  ]
+})
+```
+
 ## Legends
 
 Plot can generate legends for *color*, *opacity*, and *symbol* [scales](#scale-options). (An opacity scale is treated as a color scale with varying transparency.) For an inline legend, use the *scale*.**legend** option:

src/channel.js

@@ -16,11 +16,7 @@ export function Channel(data, {scale, type, value, filter, hint}) {
 }
 
 export function Channels(descriptors, data) {
-  return Object.fromEntries(
-    Object.entries(descriptors).map(([name, channel]) => {
-      return [name, Channel(data, channel)];
-    })
-  );
+  return Object.fromEntries(Object.entries(descriptors).map(([name, channel]) => [name, Channel(data, channel)]));
 }
 
 // TODO Use Float64Array for scales with numeric ranges, e.g. position?

src/plot.js

@@ -139,13 +139,15 @@ export {default as morleyBoxplot} from "./morley-boxplot.js";
 export {default as moviesProfitByGenre} from "./movies-profit-by-genre.js";
 export {default as moviesRatingByGenre} from "./movies-rating-by-genre.js";
 export {default as musicRevenue} from "./music-revenue.js";
+export {default as multiplicationTable} from "./multiplication-table.js";
 export {default as ordinalBar} from "./ordinal-bar.js";
 export {default as penguinAnnotated} from "./penguin-annotated.js";
 export {default as penguinCulmen} from "./penguin-culmen.js";
 export {default as penguinCulmenArray} from "./penguin-culmen-array.js";
 export {default as penguinCulmenDelaunay} from "./penguin-culmen-delaunay.js";
 export {default as penguinCulmenDelaunayMesh} from "./penguin-culmen-delaunay-mesh.js";
 export {default as penguinCulmenDelaunaySpecies} from "./penguin-culmen-delaunay-species.js";
+export {default as penguinCulmenMarkFacet} from "./penguin-culmen-mark-facet.js";
 export {default as penguinCulmenVoronoi} from "./penguin-culmen-voronoi.js";
 export {default as penguinVoronoi1D} from "./penguin-voronoi-1d.js";
 export {default as penguinDensity} from "./penguin-density.js";
@@ -154,6 +156,8 @@ export {default as penguinDensityZ} from "./penguin-density-z.js";
 export {default as penguinDodge} from "./penguin-dodge.js";
 export {default as penguinDodgeHexbin} from "./penguin-dodge-hexbin.js";
 export {default as penguinDodgeVoronoi} from "./penguin-dodge-voronoi.js";
+export {default as penguinFacetAnnotated} from "./penguins-facet-annotated.js";
+export {default as penguinFacetAnnotatedX} from "./penguins-facet-annotated-x.js";
 export {default as penguinFacetDodge} from "./penguin-facet-dodge.js";
 export {default as penguinFacetDodgeIdentity} from "./penguin-facet-dodge-identity.js";
 export {default as penguinFacetDodgeIsland} from "./penguin-facet-dodge-island.js";

test/output/multiplicationTable.svg

@@ -0,0 +1,44 @@
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+
+export default async function () {
+  const numbers = d3.range(2, 10);
+  return Plot.plot({
+    height: 450,
+    width: 450,
+    padding: 0,
+    color: {type: "categorical"},
+    fx: {axis: "top", tickSize: 6},
+    fy: {tickSize: 6},
+    marks: [
+      // This rect is faceted by y and repeated across x, and hence all rects in
+      // a row have the same fill. With rect, the default definitions of x1, x2,
+      // y1, and y2 will fill the entire frame, similar to Plot.frame.
+      Plot.rect(numbers, {
+        fy: numbers,
+        fill: numbers,
+        inset: 1
+      }),
+      // This dot is faceted by x and repeated across y, and hence all dots in a
+      // column have the same fill. With dot, the default definitions of x and y
+      // would assume that the data is a tuple [x, y], so we set the frameAnchor
+      // to middle to draw one dot in the center of each frame.
+      Plot.dot(numbers, {
+        frameAnchor: "middle",
+        r: 19,
+        fx: numbers,
+        fill: numbers,
+        stroke: "white"
+      }),
+      // This text is faceted by x and y, and hence we need the cross product of
+      // the numbers. Again there is just one text mark per facet.
+      Plot.text(d3.cross(numbers, numbers), {
+        frameAnchor: "middle",
+        text: ([x, y]) => x * y,
+        fill: "white",
+        fx: ([x]) => x,
+        fy: ([, y]) => y
+      })
+    ]
+  });
+}