ggaction 0.0.1

package/src/actions/data/density.js

@@ -0,0 +1,62 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { deriveKernelDensity } from "../../grammar/density.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "field", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "as"
+]);
+
+export const materializeDensityData = action(
+  { op: "materializeDensityData", description: "Materialize one grouped kernel-density dataset." },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeDensityData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "density"
+    );
+    const result = deriveKernelDensity(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{ ...transform, bandwidth: result.bandwidth }]
+      })
+      .editSemantic({
+        property: `dataset[${id}].values`,
+        value: result.values
+      });
+  }
+);
+
+export const createDensityData = action(
+  { op: "createDensityData", description: "Create grouped kernel-density values." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createDensityData");
+    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("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"
+    };
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeDensityData({ id });
+  }
+);

package/src/actions/data/derived.js

@@ -0,0 +1,52 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { hasDataset } from "../../selectors/index.js";
+import { findDataset } from "../../selectors/datasets.js";
+
+const OPTIONS = Object.freeze(["id", "source", "transform"]);
+const RELEASE_OPTIONS = Object.freeze(["id"]);
+
+export const createDerivedData = action(
+  { op: "createDerivedData", description: "Create an immutable derived dataset definition." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createDerivedData");
+    const id = validateUserId(args.id, "Derived dataset id");
+    const source = validateUserId(args.source, "Source dataset id");
+    if (hasDataset(this, id)) {
+      throw new Error(`Dataset "${id}" already exists.`);
+    }
+    if (!hasDataset(this, source)) {
+      throw new Error(`Unknown source dataset "${source}".`);
+    }
+    return this
+      .editSemantic({ property: `dataset[${id}].source`, value: source })
+      .editSemantic({ property: `dataset[${id}].transform`, value: args.transform });
+  }
+);
+
+export const releaseDerivedData = action(
+  {
+    op: "releaseDerivedData",
+    description: "Release one unreferenced derived dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, RELEASE_OPTIONS, "releaseDerivedData");
+    const validatedId = validateUserId(args.id, "Derived dataset id");
+    const dataset = findDataset(this, validatedId);
+    if (dataset === undefined || dataset.source === undefined) {
+      throw new Error(`Unknown derived dataset "${validatedId}".`);
+    }
+    const referenced = this.semanticSpec.layers.some(
+      layer => layer.data === validatedId
+    ) || this.semanticSpec.datasets.some(
+      candidate => candidate.source === validatedId
+    );
+    return referenced
+      ? this
+      : this.editSemantic({
+          property: `dataset[${validatedId}]`,
+          remove: true
+        });
+  }
+);

package/src/actions/data/filter.js

@@ -0,0 +1,168 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveFilteredRows,
+  normalizeFilterTransform
+} from "../../grammar/filter.js";
+import {
+  deriveMarkFilteredRows,
+  normalizeMarkFilterTransform
+} from "../../grammar/markFilter.js";
+import { resolveMarkFilterSelection } from "../../materialization/selection/filter.js";
+import {
+  applyLayerDataRematerialization
+} from "../../materialization/dependencies.js";
+import {
+  hasDataset,
+  requireLayer,
+  resolveEligibleLayer
+} from "../../selectors/index.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "field", "oneOf", "predicate", "range"
+]);
+const MARK_SELECTOR_KEYS = Object.freeze([
+  "grain", "field", "channel", "property", "op", "value", "values",
+  "min", "max", "inclusive", "count", "groupBy", "ties"
+]);
+const MARK_OPTIONS = Object.freeze(["target", ...MARK_SELECTOR_KEYS]);
+
+function retainedHistogramBoundaries(layer, items) {
+  if (layer.mark?.type !== "bar" || layer.encoding?.x?.bin === undefined) {
+    return undefined;
+  }
+  const boundaries = [...new Set(items.flatMap(item => [
+    item.channels.x,
+    item.channels.x2
+  ]).filter(Number.isFinite))].sort((left, right) => left - right);
+  return boundaries.length < 2 ? undefined : boundaries;
+}
+
+export const materializeFilteredData = action(
+  { op: "materializeFilteredData", description: "Materialize one filtered derived dataset." },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeFilteredData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "filter"
+    );
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: deriveFilteredRows(source.values, transform)
+    });
+  }
+);
+
+export const filterData = action(
+  { op: "filterData", description: "Create a named dataset from one field filter." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "filterData");
+    const id = validateUserId(args.id, "Filtered dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const transform = normalizeFilterTransform(args);
+    return this
+      .createDerivedData({
+        id,
+        source,
+        transform: [transform]
+      })
+      .materializeFilteredData({ id });
+  }
+);
+
+export const materializeMarkFilteredData = action(
+  {
+    op: "materializeMarkFilteredData",
+    description: "Materialize member rows retained by one final-item mark selection."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeMarkFilteredData");
+    const { id, dataset, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "markFilter"
+    );
+    const layer = requireLayer(this, transform.target);
+    if (layer?.data !== dataset.source) {
+      throw new Error(
+        `Mark filter target "${transform.target}" must still use source dataset "${dataset.source}".`
+      );
+    }
+    const resolved = resolveMarkFilterSelection(
+      this,
+      transform.target,
+      transform.selector
+    );
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: deriveMarkFilteredRows(source.values, resolved.items, resolved.keys)
+    });
+  }
+);
+
+export const filterMarks = action(
+  {
+    op: "filterMarks",
+    description: "Retain selected final mark items through immutable derived data."
+  },
+  function (args = {}) {
+    validateKeys(args, MARK_OPTIONS, "filterMarks");
+    const target = args.target === undefined
+      ? undefined
+      : validateUserId(args.target, "Filter mark target id");
+    const layer = resolveEligibleLayer(this, {
+      target,
+      label: "filter mark",
+      predicate: candidate =>
+        candidate.data !== undefined &&
+        ["point", "bar", "line", "area", "rule"].includes(candidate.mark?.type)
+    });
+    const derivedId = `${layer.id}FilteredData`;
+    if (hasDataset(this, derivedId)) {
+      throw new Error(`Dataset "${derivedId}" already exists.`);
+    }
+    const selector = Object.fromEntries(
+      MARK_SELECTOR_KEYS.flatMap(key =>
+        Object.hasOwn(args, key) ? [[key, args[key]]] : []
+      )
+    );
+    const resolved = resolveMarkFilterSelection(this, layer.id, selector);
+    if (resolved.keys.length === 0) {
+      throw new Error("filterMarks requires at least one matching mark item.");
+    }
+    const transform = normalizeMarkFilterTransform(layer.id, resolved.selector);
+    const boundaries = retainedHistogramBoundaries(layer, resolved.items);
+    let next = this
+      .createDerivedData({
+        id: derivedId,
+        source: layer.data,
+        transform: [transform]
+      })
+      .materializeMarkFilteredData({ id: derivedId });
+    if (boundaries !== undefined) {
+      for (const property of ["maxBins", "step"]) {
+        if (Object.hasOwn(layer.encoding.x.bin, property)) {
+          next = next.editSemantic({
+            property: `layer[${layer.id}].encoding.x.bin.${property}`,
+            remove: true
+          });
+        }
+      }
+      next = next.editSemantic({
+        property: `layer[${layer.id}].encoding.x.bin.boundaries`,
+        value: boundaries
+      });
+    }
+    next = next.editSemantic({
+      property: `layer[${layer.id}].data`,
+      value: derivedId
+    });
+    return applyLayerDataRematerialization(next, layer.id);
+  }
+);

package/src/actions/data/index.js

@@ -0,0 +1,32 @@
+import { createData } from "./create.js";
+import { createDerivedData, releaseDerivedData } from "./derived.js";
+import {
+  filterData,
+  filterMarks,
+  materializeFilteredData,
+  materializeMarkFilteredData
+} from "./filter.js";
+import { createRegressionData, materializeRegressionData } from "./regression.js";
+import { createDensityData, materializeDensityData } from "./density.js";
+import { createIntervalData, materializeIntervalData } from "./interval.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.createDensityData = createDensityData;
+  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.createRegressionData = createRegressionData;
+  ProgramClass.prototype.materializeIntervalData = materializeIntervalData;
+  ProgramClass.prototype.createIntervalData = createIntervalData;
+  ProgramClass.prototype.createBoxSummaryData = createBoxSummaryData;
+  ProgramClass.prototype.createBoxOutlierData = createBoxOutlierData;
+  ProgramClass.prototype.materializeBoxSummaryData = materializeBoxSummaryData;
+  ProgramClass.prototype.materializeBoxOutlierData = materializeBoxOutlierData;
+}

package/src/actions/data/interval.js

@@ -0,0 +1,69 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveInterval,
+  normalizeIntervalTransform
+} from "../../grammar/interval.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id",
+  "source",
+  "field",
+  "groupBy",
+  "center",
+  "extent",
+  "level",
+  "as"
+]);
+
+export const materializeIntervalData = action(
+  {
+    op: "materializeIntervalData",
+    description: "Materialize one grouped interval-summary dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeIntervalData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "interval"
+    );
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: deriveInterval(source.values, transform)
+    });
+  }
+);
+
+export const createIntervalData = action(
+  {
+    op: "createIntervalData",
+    description: "Create immutable grouped interval-summary values."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createIntervalData");
+    const id = validateUserId(args.id, "Interval dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const as = args.as ?? {
+      center: `__${id}_center`,
+      lower: `__${id}_lower`,
+      upper: `__${id}_upper`
+    };
+    const transform = normalizeIntervalTransform({
+      field: args.field,
+      groupBy: args.groupBy,
+      center: args.center,
+      extent: args.extent,
+      level: args.level,
+      as
+    });
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeIntervalData({ id });
+  }
+);

package/src/actions/data/regression.js

@@ -0,0 +1,71 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveRegression,
+  normalizeRegressionParameters
+} from "../../grammar/regression.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "x", "y", "groupBy", "method", "degree", "span",
+  "confidence", "interval"
+]);
+
+export const materializeRegressionData = action(
+  { op: "materializeRegressionData", description: "Materialize one regression derived dataset." },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeRegressionData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "regression"
+    );
+    const result = deriveRegression(source.values, {
+      x: transform.x,
+      y: transform.y,
+      groupBy: transform.groupBy,
+      method: transform.method,
+      degree: transform.degree,
+      span: transform.span,
+      confidence: transform.confidence,
+      interval: transform.interval
+    });
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: result.values
+    });
+  }
+);
+
+export const createRegressionData = action(
+  { op: "createRegressionData", description: "Create grouped regression values and optional interval bounds." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createRegressionData");
+    const parameters = normalizeRegressionParameters(args);
+    const id = validateUserId(args.id, "Regression dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const transform = {
+      type: "regression",
+      method: parameters.method,
+      x: args.x,
+      y: args.y,
+      ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+      ...(parameters.method === "polynomial"
+        ? { degree: parameters.degree }
+        : {}),
+      ...(parameters.method === "loess"
+        ? { span: parameters.span }
+        : {
+            confidence: parameters.confidence,
+            interval: parameters.interval
+          })
+    };
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeRegressionData({ id });
+  }
+);

package/src/actions/data/shared.js

@@ -0,0 +1,25 @@
+import { validateUserId } from "../../core/identifiers.js";
+import { findDataset } from "../../selectors/datasets.js";
+
+export const MATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+export function requireDerivedDataset(program, id, type) {
+  const validatedId = validateUserId(id, "Derived dataset id");
+  const dataset = findDataset(program, validatedId);
+  if (dataset === undefined || dataset.source === undefined) {
+    throw new Error(`Unknown derived dataset "${validatedId}".`);
+  }
+  if (dataset.values !== undefined) {
+    throw new Error(`Derived dataset "${validatedId}" is already materialized.`);
+  }
+  const source = findDataset(program, dataset.source);
+  if (source?.values === undefined) {
+    throw new Error(`Source dataset "${dataset.source}" has no values.`);
+  }
+  if (dataset.transform?.length !== 1 || dataset.transform[0].type !== type) {
+    throw new Error(
+      `Derived dataset "${validatedId}" requires one ${type} transform.`
+    );
+  }
+  return { id: validatedId, dataset, source, transform: dataset.transform[0] };
+}