explicit facet option in a mark (#450)

* make the data.slice() technique secondary in README
* computes the facet exclusion index only once.

Author: Fil

README.md

@@ -376,7 +376,12 @@ The following *facet* constant options are also supported:
 * facet.**marginLeft** - the left margin
 * facet.**grid** - if true, draw grid lines for each facet
 
-Marks whose data is strictly equal to (`===`) the facet data will be filtered within each facet to show the current facet’s subset, whereas other marks will be repeated across facets. You can disable faceting for an individual mark by giving it a shallow copy of the data, say using [*array*.slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice).
+Faceting can be explicitly enabled or disabled on a mark with the *facet* option, which accepts the following values:
+
+* *auto* (default) - marks whose data is strictly equal to (`===`) the facet data will be filtered within each facet to show the current facet’s subset (see *include*), whereas other marks will be repeated across facets.
+* *include* - enable faceting for this mark (shorthand: *true*)
+* *exclude* - enable exclusion faceting for this mark (each facet receives all the data except the facet’s subset)
+* null - (or false) disable faceting for this mark
 
 ```js
 Plot.plot({
@@ -386,12 +391,14 @@ Plot.plot({
   },
   marks: {
     Plot.frame(), // draws an outline around each facet
-    Plot.dot(penguins.slice(), {x: "culmen_length_mm", y: "culmen_depth_mm", fill: "#eee"}), // draws all penguins on each facet
+    Plot.dot(penguins, {x: "culmen_length_mm", y: "culmen_depth_mm", fill: "#eee", facet: "exclude"}), // draws excluded penguins on each facet
     Plot.dot(penguins, {x: "culmen_length_mm", y: "culmen_depth_mm"}) // draws only the current facet’s subset
   }
 })
 ```
 
+The strict equality check means that an individual mark that receives a shallow copy of the data, say using [*array*.slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) or [*array*.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) has faceting disabled by default.
+
 ## Marks
 
 [Marks](https://observablehq.com/@data-workflows/plot-marks) visualize data as geometric shapes such as bars, dots, and lines. An single mark can generate multiple shapes: for example, passing a [Plot.barY](#plotbarydata-options) to [Plot.plot](#plotplotoptions) will produce a bar for each element in the associated data. Multiple marks can be layered into [plots](#plotplotoptions).

src/facet.js

@@ -1,4 +1,4 @@
-import {cross, groups, InternMap} from "d3";
+import {cross, difference, groups, InternMap} from "d3";
 import {create} from "d3";
 import {Mark, values, first, second} from "./mark.js";
 
@@ -36,26 +36,30 @@ class Facet extends Mark {
     for (const facetKey of facetsKeys) {
       marksIndexByFacet.set(facetKey, new Array(this.marks.length));
     }
+    let facetsExclude;
     for (let i = 0; i < this.marks.length; ++i) {
       const mark = this.marks[i];
-      const markFacets = mark.data === this.data ? facetsIndex : undefined;
-      const {index, channels} = mark.initialize(markFacets);
+      const {facet} = mark;
+      const markFacets = facet === "auto" ? mark.data === this.data ? facetsIndex : undefined
+        : facet === "include" ? facetsIndex
+        : facet === "exclude" ? facetsExclude || (facetsExclude = facetsIndex.map(f => Uint32Array.from(difference(index, f))))
+        : undefined;
+      const {index: I, channels} = mark.initialize(markFacets);
       // If an index is returned by mark.initialize, its structure depends on
       // whether or not faceting has been applied: it is a flat index ([0, 1, 2,
       // …]) when not faceted, and a nested index ([[0, 1, …], [2, 3, …], …])
-      // when faceted. Faceting is only applied if the mark data is the same as
-      // the facet’s data.
-      if (index !== undefined) {
+      // when faceted.
+      if (I !== undefined) {
         if (markFacets) {
           for (let j = 0; j < facetsKeys.length; ++j) {
-            marksIndexByFacet.get(facetsKeys[j])[i] = index[j];
+            marksIndexByFacet.get(facetsKeys[j])[i] = I[j];
           }
           marksIndex[i] = []; // implicit empty index for sparse facets
         } else {
           for (let j = 0; j < facetsKeys.length; ++j) {
-            marksIndexByFacet.get(facetsKeys[j])[i] = index;
+            marksIndexByFacet.get(facetsKeys[j])[i] = I;
           }
-          marksIndex[i] = index;
+          marksIndex[i] = I;
         }
       }
       for (const [, channel] of channels) {

src/mark.js

@@ -7,9 +7,10 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
 const objectToString = Object.prototype.toString;
 
 export class Mark {
-  constructor(data, channels = [], options = {}) {
+  constructor(data, channels = [], {facet = "auto", ...options} = {}) {
     const names = new Set();
     this.data = data;
+    this.facet = facet ? keyword(facet === true ? "include" : facet, "facet", ["auto", "include", "exclude"]) : null;
     const {transform} = maybeTransform(options);
     this.transform = transform;
     this.channels = channels.filter(channel => {