ggaction 0.0.4 → 0.0.5

package/src/actions/charts/histogram.js

@@ -0,0 +1,58 @@
+import { action } from "../../core/action.js";
+import { validateNonEmptyString } from "../../core/validation.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "field", "maxBins", "binStep",
+  "binBoundaries", "stack", "xScale", "yScale", "color", "bar", "guides"
+]);
+const BAR_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth"
+]);
+const HISTOGRAM_OPTIONS = Object.freeze([
+  "maxBins", "binStep", "binBoundaries", "stack", "xScale", "yScale"
+]);
+
+export const createHistogram = action(
+  {
+    op: "createHistogram",
+    description: "Create a binned count histogram from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createHistogram");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "histogram",
+      operation: "createHistogram"
+    });
+    const data = resolveFacadeData(this, args.data, "createHistogram");
+    const field = validateNonEmptyString(args.field, "createHistogram field");
+    const bar = normalizeAppearance(args.bar, BAR_OPTIONS, "createHistogram bar");
+    const color = normalizeEncoding(args.color, "createHistogram color");
+    const guides = normalizeGuides(args.guides, "createHistogram");
+    const histogram = Object.fromEntries(
+      HISTOGRAM_OPTIONS
+        .filter(key => Object.hasOwn(args, key))
+        .map(key => [key, args[key]])
+    );
+
+    let next = this
+      .createBarMark({ id, data, ...bar })
+      .encodeHistogram({
+        field,
+        target: id,
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+        ...histogram
+      });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/index.js

@@ -0,0 +1,15 @@
+import { createBarPlot } from "./bar.js";
+import { createHeatmap } from "./heatmap.js";
+import { createHistogram } from "./histogram.js";
+import { createLinePlot } from "./line.js";
+import { createScatterPlot } from "./scatter.js";
+import { createParallelCoordinates } from "./parallel.js";
+
+export function registerChartActions(ProgramClass) {
+  ProgramClass.prototype.createBarPlot = createBarPlot;
+  ProgramClass.prototype.createHeatmap = createHeatmap;
+  ProgramClass.prototype.createHistogram = createHistogram;
+  ProgramClass.prototype.createScatterPlot = createScatterPlot;
+  ProgramClass.prototype.createLinePlot = createLinePlot;
+  ProgramClass.prototype.createParallelCoordinates = createParallelCoordinates;
+}

package/src/actions/charts/line.js

@@ -0,0 +1,69 @@
+import { action } from "../../core/action.js";
+import { validateNonEmptyString } from "../../core/validation.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  normalizeStrokeDashEncoding,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "groupBy",
+  "strokeDash", "line", "guides"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "curve", "stroke", "opacity", "closed"
+]);
+
+export const createLinePlot = action(
+  {
+    op: "createLinePlot",
+    description: "Create a Cartesian line plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createLinePlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "linePlot",
+      operation: "createLinePlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createLinePlot");
+    const line = normalizeAppearance(
+      args.line,
+      LINE_OPTIONS,
+      "createLinePlot line"
+    );
+    if (line.closed === true) {
+      throw new Error(
+        "createLinePlot is Cartesian; closed lines require Polar line authoring."
+      );
+    }
+    const x = normalizeFieldEncoding(args.x, "createLinePlot x");
+    const y = normalizeFieldEncoding(args.y, "createLinePlot y");
+    const color = normalizeEncoding(args.color, "createLinePlot color");
+    const strokeDash = normalizeStrokeDashEncoding(args.strokeDash);
+    const groupBy = args.groupBy === undefined
+      ? undefined
+      : validateNonEmptyString(args.groupBy, "createLinePlot groupBy");
+    const guides = normalizeGuides(args.guides, "createLinePlot");
+
+    let next = this
+      .createLineMark({ id, data, ...line })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (groupBy !== undefined) {
+      next = next.encodeGroup({ field: groupBy, target: id });
+    }
+    if (strokeDash !== undefined) {
+      next = next.encodeStrokeDash(targetArgs(strokeDash, id));
+    }
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/parallel.js

@@ -0,0 +1,76 @@
+import { action } from "../../core/action.js";
+import { resolveParallelCoordinate } from "../coordinates/parallel.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeGuides,
+  normalizeStrokeDashEncoding,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "dimensions", "key", "missing",
+  "color", "strokeDash", "line", "guides"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "stroke", "opacity", "curve", "closed"
+]);
+
+export const createParallelCoordinates = action(
+  {
+    op: "createParallelCoordinates",
+    description: "Create a complete Parallel-coordinates chart."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createParallelCoordinates");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "parallelCoordinates",
+      operation: "createParallelCoordinates"
+    });
+    const data = resolveFacadeData(this, args.data, "createParallelCoordinates");
+    const coordinate = resolveParallelCoordinate(this, {
+      requested: args.coordinate,
+      operation: "createParallelCoordinates",
+      useCurrent: true
+    }).id;
+    const line = normalizeAppearance(
+      args.line,
+      LINE_OPTIONS,
+      "createParallelCoordinates line"
+    );
+    if (line.closed === true || (line.curve !== undefined && line.curve !== "linear")) {
+      throw new Error(
+        "createParallelCoordinates requires a linear open line."
+      );
+    }
+    const color = normalizeEncoding(
+      args.color,
+      "createParallelCoordinates color"
+    );
+    const strokeDash = normalizeStrokeDashEncoding(
+      args.strokeDash,
+      "createParallelCoordinates strokeDash"
+    );
+    const guides = normalizeGuides(args.guides, "createParallelCoordinates");
+
+    let next = this
+      .createCoordinate({ id: coordinate, type: "parallel" })
+      .createLineMark({ id, data, ...line })
+      .encodeParallelCoordinates({
+        target: id,
+        coordinate,
+        dimensions: args.dimensions,
+        ...(args.key === undefined ? {} : { key: args.key }),
+        ...(args.missing === undefined ? {} : { missing: args.missing })
+      });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (strokeDash !== undefined) {
+      next = next.encodeStrokeDash(targetArgs(strokeDash, id));
+    }
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/scatter.js

@@ -0,0 +1,56 @@
+import { action } from "../../core/action.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape",
+  "point", "guides"
+]);
+const POINT_OPTIONS = Object.freeze([
+  "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const createScatterPlot = action(
+  {
+    op: "createScatterPlot",
+    description: "Create a Cartesian scatter plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createScatterPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "scatterPlot",
+      operation: "createScatterPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createScatterPlot");
+    const point = normalizeAppearance(
+      args.point,
+      POINT_OPTIONS,
+      "createScatterPlot point"
+    );
+    const x = normalizeFieldEncoding(args.x, "createScatterPlot x");
+    const y = normalizeFieldEncoding(args.y, "createScatterPlot y");
+    const color = normalizeEncoding(args.color, "createScatterPlot color");
+    const size = normalizeEncoding(args.size, "createScatterPlot size");
+    const shape = normalizeEncoding(args.shape, "createScatterPlot shape");
+    const guides = normalizeGuides(args.guides, "createScatterPlot");
+
+    let next = this
+      .createPointMark({ id, data, ...point })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (size !== undefined) next = next.encodeSize(targetArgs(size, id));
+    if (shape !== undefined) next = next.encodeShape(targetArgs(shape, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/shared.js

@@ -0,0 +1,121 @@
+import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { hasLayer } from "../../selectors/layers.js";
+
+export function validateFacadeOptions(args, supported, operation) {
+  return validateOptionObject(args, supported, operation);
+}
+
+export function resolveFacadeData(program, requested, operation) {
+  if (requested !== undefined) {
+    const id = validateUserId(requested, `${operation} dataset id`);
+    if (findDataset(program, id) === undefined) {
+      throw new Error(`Unknown dataset "${id}".`);
+    }
+    return id;
+  }
+
+  const current = program.context.currentData;
+  if (current !== undefined && findDataset(program, current) !== undefined) {
+    return current;
+  }
+  const datasets = program.semanticSpec.datasets;
+  if (datasets.length === 1) return datasets[0].id;
+  if (datasets.length > 1) {
+    throw new Error(
+      `${operation} requires data when multiple datasets are available.`
+    );
+  }
+  throw new Error(`${operation} requires data or one inferable dataset.`);
+}
+
+export function resolveFacadeId(program, requested, {
+  defaultId,
+  operation
+}) {
+  return resolveOptionalUserId(requested, {
+    defaultId,
+    label: `${operation} id`,
+    operation,
+    ambiguous: hasLayer(program, defaultId) ||
+      program.graphicSpec.objects[defaultId] !== undefined
+  });
+}
+
+export function normalizeFieldEncoding(value, label) {
+  if (typeof value === "string") return { field: value };
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a field string or a plain object.`);
+  }
+  if (Object.hasOwn(value, "target") || Object.hasOwn(value, "coordinate")) {
+    throw new Error(
+      `${label} target and coordinate are owned by the chart facade.`
+    );
+  }
+  return { ...value };
+}
+
+export function normalizeEncoding(value, label) {
+  if (value === undefined) return undefined;
+  return normalizeFieldEncoding(value, label);
+}
+
+export function normalizeStrokeDashEncoding(
+  value,
+  label = "createLinePlot strokeDash"
+) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(
+      `${label} must be an encodeStrokeDash option object.`
+    );
+  }
+  if (Object.hasOwn(value, "target")) {
+    throw new Error(`${label} target is owned by the chart facade.`);
+  }
+  return { ...value };
+}
+
+export function normalizeAppearance(value, supported, label) {
+  if (value === undefined) return {};
+  validateOptionObject(value, supported, label);
+  return { ...value };
+}
+
+export function normalizeTargetOptions(value, label) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  if (Object.hasOwn(value, "target")) {
+    throw new Error(`${label} target is owned by the chart facade.`);
+  }
+  return { ...value };
+}
+
+export function normalizeGuides(value, operation) {
+  if (value === false) return false;
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${operation} guides must be false or a plain object.`);
+  }
+  return { ...value };
+}
+
+export function positionArgs(encoding, { target, coordinate }) {
+  return {
+    ...encoding,
+    target,
+    ...(coordinate === undefined ? {} : { coordinate })
+  };
+}
+
+export function targetArgs(encoding, target) {
+  return { ...encoding, target };
+}
+
+export function applyFacadeGuides(program, guides) {
+  return guides === false ? program : program.createGuides(guides);
+}

package/src/actions/coordinates/parallel.js

@@ -0,0 +1,50 @@
+import { validateUserId } from "../../core/identifiers.js";
+import { findCoordinate } from "../../selectors/coordinates.js";
+
+export function resolveParallelCoordinate(program, {
+  requested,
+  layer,
+  operation,
+  useCurrent = false
+}) {
+  const explicit = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Parallel coordinate id");
+  if (layer?.coordinate !== undefined) {
+    if (explicit !== undefined && explicit !== layer.coordinate) {
+      throw new Error(
+        `Layer "${layer.id}" already uses coordinate "${layer.coordinate}".`
+      );
+    }
+    const coordinate = findCoordinate(program, layer.coordinate);
+    if (coordinate?.type !== "parallel") {
+      throw new Error(`Coordinate "${layer.coordinate}" is not Parallel.`);
+    }
+    return { id: layer.coordinate, create: false };
+  }
+  if (explicit !== undefined) {
+    const coordinate = findCoordinate(program, explicit);
+    if (coordinate !== undefined && coordinate.type !== "parallel") {
+      throw new Error(`Coordinate "${explicit}" is not Parallel.`);
+    }
+    return { id: explicit, create: coordinate === undefined };
+  }
+  const current = useCurrent ? program.context.currentCoordinate : undefined;
+  if (current !== undefined && findCoordinate(program, current)?.type === "parallel") {
+    return { id: current, create: false };
+  }
+  const compatible = program.semanticSpec.coordinates.filter(
+    coordinate => coordinate.type === "parallel"
+  );
+  if (compatible.length > 1) {
+    throw new Error(
+      `${operation} requires coordinate when multiple Parallel coordinates are available.`
+    );
+  }
+  if (compatible.length === 1) return { id: compatible[0].id, create: false };
+  const conflict = findCoordinate(program, "parallel");
+  if (conflict !== undefined) {
+    throw new Error('Coordinate "parallel" already exists with a different type.');
+  }
+  return { id: "parallel", create: true };
+}

package/src/actions/data/bin2d.js

@@ -0,0 +1,137 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveBin2DRows,
+  normalizeBin2DTransform
+} from "../../grammar/bin2d.js";
+import { applyLayerDataRematerialization } from
+  "../../materialization/dependencies.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
+import {
+  findDataset,
+  findDatasetConsumer
+} from "../../selectors/datasets.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "x", "y", "bins", "extent", "includeEmpty", "members", "as"
+]);
+
+function ownerConfig(program, id) {
+  return program.materializationConfigs.data?.bin2d?.[id];
+}
+
+function requireCurrentBin2D(program, id, config) {
+  const current = findDataset(program, config.current);
+  if (
+    current?.source === undefined ||
+    current.transform?.length !== 1 ||
+    current.transform[0].type !== "bin2d"
+  ) {
+    throw new Error(`2D bin owner "${id}" has no current derived dataset.`);
+  }
+  return current;
+}
+
+function directLayerConsumers(program, data) {
+  return program.semanticSpec.layers
+    .filter(layer => layer.data === data)
+    .map(layer => layer.id);
+}
+
+function rejectDerivedConsumers(program, data) {
+  const dependent = findDatasetConsumer(program, data);
+  if (dependent !== undefined) {
+    throw new Error(
+      `Cannot replace 2D bin dataset "${data}" while derived dataset ` +
+      `"${dependent.id}" depends on it.`
+    );
+  }
+}
+
+function preflight(program, sourceId, transform) {
+  const source = findDataset(program, sourceId);
+  if (source?.values === undefined) {
+    throw new Error(`Source dataset "${sourceId}" has no values.`);
+  }
+  deriveBin2DRows(source.values, transform);
+}
+
+export const materializeBin2DData = action(
+  {
+    op: "materializeBin2DData",
+    description: "Materialize one immutable rectangular 2D-bin dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeBin2DData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "bin2d"
+    );
+    const result = deriveBin2DRows(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{ ...transform, resolved: result.resolved }]
+      })
+      .editSemantic({
+        property: `dataset[${id}].values`,
+        value: result.values
+      });
+  }
+);
+
+export const createBin2DData = action(
+  {
+    op: "createBin2DData",
+    description: "Create or revise immutable rectangular 2D-bin values."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createBin2DData");
+    const owner = validateUserId(args.id, "2D bin dataset id");
+    const config = ownerConfig(this, owner);
+    const previous = config === undefined
+      ? undefined
+      : requireCurrentBin2D(this, owner, config);
+    const source = validateUserId(
+      args.source ?? previous?.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const transform = normalizeBin2DTransform({ ...args, id: owner });
+    preflight(this, source, transform);
+
+    if (previous === undefined) {
+      return this
+        .createDerivedData({ id: owner, source, transform: [transform] })
+        .materializeBin2DData({ id: owner })
+        ._withMaterializationConfig(
+          ["data", "bin2d", owner],
+          { current: owner }
+        );
+    }
+
+    rejectDerivedConsumers(this, previous.id);
+    const consumers = directLayerConsumers(this, previous.id);
+    const revision = planDerivedDataRevision(this, {
+      owner,
+      role: "Bin2DData",
+      previous: previous.id,
+      consumers
+    });
+    let next = this
+      .createDerivedData({ id: revision.id, source, transform: [transform] })
+      .materializeBin2DData({ id: revision.id });
+    for (const rebind of revision.rebinds) {
+      next = next.rebindLayerData(rebind);
+      next = applyLayerDataRematerialization(next, rebind.id);
+    }
+    next = next.releaseDerivedData(revision.release);
+    return next._withMaterializationConfig(
+      ["data", "bin2d", owner],
+      { current: revision.id }
+    );
+  }
+);

package/src/actions/data/density.js

@@ -8,6 +8,23 @@ const OPTIONS = Object.freeze([
   "id", "source", "field", "groupBy", "bandwidth", "extent", "steps",
   "kernel", "normalization", "as"
 ]);
+const CATEGORICAL_OPTIONS = Object.freeze([...OPTIONS, "placement"]);
+
+function densityTransform(args, placement) {
+  return {
+    type: "density",
+    field: args.field,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bandwidth: args.bandwidth ?? "auto",
+    extent: args.extent ?? "auto",
+    steps: args.steps ?? 100,
+    kernel: args.kernel ?? "gaussian",
+    normalization: args.normalization ?? "unit",
+    as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
+    resolve: "shared",
+    ...(placement === undefined ? {} : { placement })
+  };
+}
 
 export const materializeDensityData = action(
   { op: "materializeDensityData", description: "Materialize one grouped kernel-density dataset." },
@@ -26,7 +43,10 @@ export const materializeDensityData = action(
           ...transform,
           resolved: {
             bandwidth: result.bandwidth,
-            extent: result.extent
+            extent: result.extent,
+            ...(result.splitDomain === undefined
+              ? {}
+              : { splitDomain: result.splitDomain })
           }
         }]
       })
@@ -49,20 +69,41 @@ export const createDensityData = action(
     if (typeof args.field !== "string" || args.field.length === 0) {
       throw new TypeError("createDensityData requires a non-empty field string.");
     }
-    const transform = {
-      type: "density",
-      field: args.field,
-      ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
-      bandwidth: args.bandwidth ?? "auto",
-      extent: args.extent ?? "auto",
-      steps: args.steps ?? 100,
-      kernel: args.kernel ?? "gaussian",
-      normalization: args.normalization ?? "unit",
-      as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
-      resolve: "shared"
-    };
+    const transform = densityTransform(args);
     return this
       .createDerivedData({ id, source, transform: [transform] })
       .materializeDensityData({ id });
   }
 );
+
+export const createCategoricalDensityData = action(
+  {
+    op: "createCategoricalDensityData",
+    description: "Create category-placed kernel-density values."
+  },
+  function (args = {}) {
+    validateKeys(args, CATEGORICAL_OPTIONS, "createCategoricalDensityData");
+    const id = validateUserId(args.id, "Density dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    if (typeof args.field !== "string" || args.field.length === 0) {
+      throw new TypeError(
+        "createCategoricalDensityData requires a non-empty field string."
+      );
+    }
+    if (args.placement?.type !== "category") {
+      throw new Error(
+        "createCategoricalDensityData requires normalized category placement."
+      );
+    }
+    return this
+      .createDerivedData({
+        id,
+        source,
+        transform: [densityTransform(args, args.placement)]
+      })
+      .materializeDensityData({ id });
+  }
+);