ggaction 0.0.3 → 0.0.5

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 });
+  }
+);

package/src/actions/data/derived.js

@@ -3,9 +3,11 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { hasDataset } from "../../selectors/index.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { requireLayer } from "../../selectors/layers.js";
 
 const OPTIONS = Object.freeze(["id", "source", "transform"]);
 const RELEASE_OPTIONS = Object.freeze(["id"]);
+const REBIND_OPTIONS = Object.freeze(["id", "data"]);
 
 export const createDerivedData = action(
   { op: "createDerivedData", description: "Create an immutable derived dataset definition." },
@@ -50,3 +52,23 @@ export const releaseDerivedData = action(
         });
   }
 );
+
+export const rebindLayerData = action(
+  {
+    op: "rebindLayerData",
+    description: "Rebind one semantic layer to an existing dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, REBIND_OPTIONS, "rebindLayerData");
+    const id = validateUserId(args.id, "Layer id");
+    const data = validateUserId(args.data, "Layer dataset id");
+    requireLayer(this, id);
+    if (!hasDataset(this, data)) {
+      throw new Error(`Layer dataset "${data}" does not exist.`);
+    }
+    return this.editSemantic({
+      property: `layer[${id}].data`,
+      value: data
+    });
+  }
+);

package/src/actions/data/filter.js

@@ -125,6 +125,11 @@ export const filterMarks = action(
         candidate.data !== undefined &&
         findSelectionPolicy(candidate.mark?.type) !== undefined
     });
+    if (this.markConfigs[layer.id]?.itemFilterable === false) {
+      throw new Error(
+        `filterMarks does not support composite mark "${layer.id}"; filter its source dataset first.`
+      );
+    }
     const derivedId = `${layer.id}FilteredData`;
     if (hasDataset(this, derivedId)) {
       throw new Error(`Dataset "${derivedId}" already exists.`);

package/src/actions/data/gradientProfile.js

@@ -0,0 +1,65 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveGradientProfiles,
+  normalizeGradientProfileTransform
+} from "../../grammar/gradientProfile.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "category", "field", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "center", "as"
+]);
+
+export const materializeGradientProfileData = action(
+  {
+    op: "materializeGradientProfileData",
+    description: "Materialize one categorical density-profile dataset."
+  },
+  function (args = {}) {
+    validateKeys(
+      args,
+      MATERIALIZE_OPTIONS,
+      "materializeGradientProfileData"
+    );
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "gradientProfile"
+    );
+    const result = deriveGradientProfiles(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{
+          ...transform,
+          resolved: {
+            bandwidth: result.bandwidth,
+            extent: result.extent,
+            intensityDomain: result.intensityDomain
+          }
+        }]
+      })
+      .editSemantic({ property: `dataset[${id}].values`, value: result.values });
+  }
+);
+
+export const createGradientProfileData = action(
+  {
+    op: "createGradientProfileData",
+    description: "Create one immutable categorical density-profile dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createGradientProfileData");
+    const id = validateUserId(args.id, "Gradient profile dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Gradient profile source dataset id"
+    );
+    const transform = normalizeGradientProfileTransform(args);
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeGradientProfileData({ id });
+  }
+);

package/src/actions/data/horizon.js

@@ -0,0 +1,71 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveHorizon,
+  validateHorizonTransform
+} from "../../grammar/horizon.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "x", "y", "groupBy", "bands", "baseline", "extent",
+  "resolve", "missing", "overflow", "palette", "as"
+]);
+
+function requestedTransform(args) {
+  return validateHorizonTransform({
+    type: "horizon",
+    x: args.x,
+    y: args.y,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bands: args.bands ?? 3,
+    baseline: args.baseline ?? 0,
+    extent: args.extent ?? "auto",
+    resolve: args.resolve ?? "shared",
+    missing: args.missing ?? "break",
+    overflow: args.overflow ?? "clip",
+    palette: args.palette ?? {},
+    as: args.as
+  });
+}
+
+export const materializeHorizonData = action(
+  {
+    op: "materializeHorizonData",
+    description: "Materialize one immutable Horizon band dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeHorizonData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "horizon"
+    );
+    const result = deriveHorizon(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{ ...result.transform, resolved: result.resolved }]
+      })
+      .editSemantic({
+        property: `dataset[${id}].values`,
+        value: result.values
+      });
+  }
+);
+
+export const createHorizonData = action(
+  {
+    op: "createHorizonData",
+    description: "Create one immutable Horizon band dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createHorizonData");
+    const id = validateUserId(args.id, "Horizon dataset id");
+    const source = validateUserId(args.source, "Horizon source dataset id");
+    const transform = requestedTransform(args);
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeHorizonData({ id });
+  }
+);

package/src/actions/data/index.js

@@ -1,5 +1,9 @@
 import { createData } from "./create.js";
-import { createDerivedData, releaseDerivedData } from "./derived.js";
+import {
+  createDerivedData,
+  rebindLayerData,
+  releaseDerivedData
+} from "./derived.js";
 import {
   filterData,
   filterMarks,
@@ -7,24 +11,47 @@ import {
   materializeMarkFilteredData
 } from "./filter.js";
 import { createRegressionData, materializeRegressionData } from "./regression.js";
-import { createDensityData, materializeDensityData } from "./density.js";
+import {
+  createCategoricalDensityData,
+  createDensityData,
+  materializeDensityData
+} from "./density.js";
+import {
+  createGradientProfileData,
+  materializeGradientProfileData
+} from "./gradientProfile.js";
 import { createIntervalData, materializeIntervalData } from "./interval.js";
+import { createHorizonData, materializeHorizonData } from "./horizon.js";
+import { createWindowData, materializeWindowData } from "./window.js";
+import { createBin2DData, materializeBin2DData } from "./bin2d.js";
 import { createBoxSummaryData, createBoxOutlierData, materializeBoxSummaryData, materializeBoxOutlierData } from "./box.js";
 
 export function registerDataActions(ProgramClass) {
   ProgramClass.prototype.createData = createData;
   ProgramClass.prototype.createDerivedData = createDerivedData;
   ProgramClass.prototype.releaseDerivedData = releaseDerivedData;
+  ProgramClass.prototype.rebindLayerData = rebindLayerData;
   ProgramClass.prototype.createDensityData = createDensityData;
+  ProgramClass.prototype.createCategoricalDensityData =
+    createCategoricalDensityData;
   ProgramClass.prototype.materializeFilteredData = materializeFilteredData;
   ProgramClass.prototype.materializeMarkFilteredData = materializeMarkFilteredData;
   ProgramClass.prototype.filterData = filterData;
   ProgramClass.prototype.filterMarks = filterMarks;
   ProgramClass.prototype.materializeRegressionData = materializeRegressionData;
   ProgramClass.prototype.materializeDensityData = materializeDensityData;
+  ProgramClass.prototype.createGradientProfileData = createGradientProfileData;
+  ProgramClass.prototype.materializeGradientProfileData =
+    materializeGradientProfileData;
   ProgramClass.prototype.createRegressionData = createRegressionData;
   ProgramClass.prototype.materializeIntervalData = materializeIntervalData;
   ProgramClass.prototype.createIntervalData = createIntervalData;
+  ProgramClass.prototype.createHorizonData = createHorizonData;
+  ProgramClass.prototype.materializeHorizonData = materializeHorizonData;
+  ProgramClass.prototype.createWindowData = createWindowData;
+  ProgramClass.prototype.materializeWindowData = materializeWindowData;
+  ProgramClass.prototype.createBin2DData = createBin2DData;
+  ProgramClass.prototype.materializeBin2DData = materializeBin2DData;
   ProgramClass.prototype.createBoxSummaryData = createBoxSummaryData;
   ProgramClass.prototype.createBoxOutlierData = createBoxOutlierData;
   ProgramClass.prototype.materializeBoxSummaryData = materializeBoxSummaryData;

package/src/actions/data/regression.js

@@ -4,7 +4,7 @@ import { validateKeys } from "../../core/validation.js";
 import {
   deriveRegression,
   normalizeRegressionParameters
-} from "../../grammar/regression.js";
+} from "../../grammar/regression/index.js";
 import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
 
 const OPTIONS = Object.freeze([

package/src/actions/data/window.js

@@ -0,0 +1,50 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveWindowRows,
+  normalizeWindowTransform
+} from "../../grammar/window.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "partitionBy", "sortBy", "operations"
+]);
+
+export const materializeWindowData = action(
+  {
+    op: "materializeWindowData",
+    description: "Materialize one immutable window-derived dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeWindowData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "window"
+    );
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: deriveWindowRows(source.values, transform)
+    });
+  }
+);
+
+export const createWindowData = action(
+  {
+    op: "createWindowData",
+    description: "Create immutable partitioned window values."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createWindowData");
+    const id = validateUserId(args.id, "Window dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const transform = normalizeWindowTransform(args);
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeWindowData({ id });
+  }
+);

package/src/actions/encodings/appearance.js

@@ -4,7 +4,7 @@ import {
   readQuantitativeField,
   readScaleField,
   validateOpacityValue
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import {
   resolveAppearanceScaleDefinition,
   resolveOpacityScaleDefinition