ggaction 0.0.3 → 0.0.5

package/src/grammar/arcs.js

@@ -4,7 +4,7 @@ import {
   mapOrdinalPositionValues,
   readNominalField,
   readQuantitativeField
-} from "./scales.js";
+} from "./scales/index.js";
 
 function requireArcLayer(layer) {
   if (layer?.mark?.type !== "arc") {
@@ -36,42 +36,79 @@ function colorValues(rows, encoding) {
     : readNominalField(rows, encoding.field);
 }
 
-function countSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
+export function readArcThetaWeights(rows, field, layerId = "arc") {
+  if (!Array.isArray(rows)) throw new TypeError("Arc theta weights require rows.");
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("Arc theta weight must be a non-empty string.");
+  }
+  const weights = rows.map((row, index) => {
+    const value = row?.[field];
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TypeError(
+        `Arc theta weight field "${field}" must contain non-negative finite numbers at row ${index}.`
+      );
+    }
+    return value;
+  });
+  if (weights.every(value => value === 0)) {
+    throw new Error(`Arc mark "${layerId}" theta weights must have a positive total.`);
+  }
+  return cloneAndFreeze(weights);
+}
+
+function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
   const theta = layer.encoding.theta;
-  if (theta.aggregate !== "count") {
-    throw new Error(`Arc mark "${layer.id}" requires count or radial layout.`);
+  if (!["count", "sum"].includes(theta.aggregate)) {
+    throw new Error(`Arc mark "${layer.id}" requires count, sum, or radial layout.`);
   }
   const values = readNominalField(rows, theta.field);
   const colors = colorValues(rows, layer.encoding?.color);
+  const weights = theta.aggregate === "count"
+    ? rows.map(() => 1)
+    : readArcThetaWeights(rows, theta.weight, layer.id);
   const groups = new Map(thetaScale.domain.map(value => [value, []]));
   for (let index = 0; index < rows.length; index += 1) {
     const group = groups.get(values[index]);
     if (group === undefined) {
       throw new Error(`Arc theta value "${values[index]}" is outside the scale domain.`);
     }
-    group.push({ row: rows[index], color: colors[index], sourceIndex: index });
+    group.push({
+      row: rows[index],
+      color: colors[index],
+      sourceIndex: index,
+      weight: weights[index]
+    });
   }
-  const total = [...groups.values()].reduce((sum, group) => sum + group.length, 0);
-  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no rows to count.`);
+  const total = [...groups.values()].reduce(
+    (sum, group) => sum + group.reduce((groupSum, item) => groupSum + item.weight, 0),
+    0
+  );
+  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no positive theta weight.`);
   const start = thetaScale.range[0];
   const span = thetaScale.range[1] - thetaScale.range[0];
   const innerRadius = frame.availableRadius * innerRadiusRatio;
   let cursor = start;
   const sectors = [];
-  for (const value of thetaScale.domain) {
+  const positiveValues = thetaScale.domain.filter(value =>
+    groups.get(value).some(item => item.weight > 0)
+  );
+  for (const [positiveIndex, value] of positiveValues.entries()) {
     const group = groups.get(value);
-    if (group.length === 0) continue;
-    const endTheta = cursor + group.length / total * span;
+    const aggregateValue = group.reduce((sum, item) => sum + item.weight, 0);
+    const endTheta = positiveIndex === positiveValues.length - 1
+      ? thetaScale.range[1]
+      : cursor + aggregateValue / total * span;
     const distinctColors = [...new Set(group.map(item => item.color))];
     if (distinctColors.length > 1) {
       throw new Error(
-        `Count arc theta group "${value}" must resolve to one color value.`
+        `Aggregated arc theta group "${value}" must resolve to one color value.`
       );
     }
     sectors.push({
       key: value,
       theta: value,
       count: group.length,
+      aggregateValue,
       color: distinctColors[0],
       startTheta: cursor,
       endTheta,
@@ -147,8 +184,8 @@ export function deriveArcSectors(rows, layer, {
   ) {
     throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
   }
-  const sectors = theta.aggregate === "count"
-    ? countSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
+  const sectors = ["count", "sum"].includes(theta.aggregate)
+    ? proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
     : radialSectors(rows, layer, thetaScale, radiusScale);
   return cloneAndFreeze({ sectors });
 }

package/src/grammar/areaSeries.js

@@ -3,17 +3,19 @@ import {
   readNominalField,
   readQuantitativeField,
   readTemporalField
-} from "./scales.js";
+} from "./scales/index.js";
 import {
   layoutSeriesPartition,
   validateColorLayout
 } from "./seriesLayout.js";
+import { stableOrderPathValues } from "./pathOrder.js";
+import { deriveCategoricalDensitySeries } from "./categoricalDensity.js";
 
 export function deriveAreaSeries(rows, layer) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Area series derivation requires a semantic area mark.");
   }
-  const { x, y, x2, y2, group } = layer.encoding ?? {};
+  const { x, y, x2, y2, group, color } = layer.encoding ?? {};
   const vertical =
     ["quantitative", "temporal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
@@ -46,24 +48,44 @@ export function deriveAreaSeries(rows, layer) {
   const groupValues = group === undefined
     ? rows.map(() => undefined)
     : readNominalField(rows, group.field);
+  const colorValues = color === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, color.field);
+  const pathOrder = layer.encoding?.pathOrder;
+  const orderValues = pathOrder === undefined
+    ? undefined
+    : readQuantitativeField(rows, pathOrder.field);
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
     const key = groupValues[index];
     const series = groups.get(key) ?? {
-      key: group === undefined ? {} : { [group.field]: key },
+      key: {
+        ...(group === undefined ? {} : { [group.field]: key }),
+        ...(color === undefined ? {} : { [color.field]: colorValues[index] })
+      },
       values: []
     };
+    if (
+      color !== undefined &&
+      !Object.is(series.key[color.field], colorValues[index])
+    ) {
+      throw new Error(
+        `Area series "${String(key)}" must have one color value.`
+      );
+    }
     series.values.push(vertical
       ? {
           x: independentValues[index],
           y: lower[index],
-          y2: upper[index]
+          y2: upper[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         }
       : {
           x: lower[index],
           x2: upper[index],
-          y: independentValues[index]
+          y: independentValues[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         });
     groups.set(key, series);
   }
@@ -72,7 +94,13 @@ export function deriveAreaSeries(rows, layer) {
   }
   const series = [...groups.values()].map(item => {
     const key = vertical ? "x" : "y";
-    const values = item.values.sort((left, right) => left[key] - right[key]);
+    const values = pathOrder === undefined
+      ? item.values.sort((left, right) => left[key] - right[key])
+      : stableOrderPathValues(
+          item.values.map(({ pathOrder: _pathOrder, ...value }) => value),
+          item.values.map(value => value.pathOrder),
+          pathOrder.order
+        );
     if (values.length < 2) {
       throw new Error(
         `Area series on mark "${layer.id}" requires at least two points.`
@@ -96,9 +124,17 @@ export function deriveDensityAreaSeries(rows, layer, transform) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Density area derivation requires a semantic area mark.");
   }
+  if (layer.encoding?.pathOrder !== undefined) {
+    throw new Error(
+      `Density area mark "${layer.id}" does not support path order.`
+    );
+  }
   if (transform?.type !== "density" || !Array.isArray(transform.as)) {
     throw new Error(`Area mark "${layer.id}" requires density provenance.`);
   }
+  if (transform.placement?.type === "category") {
+    return deriveCategoricalDensitySeries(rows, layer, transform);
+  }
   const { x, y, group } = layer.encoding ?? {};
   if (
     x?.fieldType !== "quantitative" ||

package/src/grammar/bars/aggregate.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
-import { readNominalField, readTemporalField } from "../scales.js";
+import { readNominalField, readTemporalField } from "../scales/index.js";
 import {
   aggregateRows,
   validateAggregateFieldType,

package/src/grammar/bin2d.js

@@ -0,0 +1,333 @@
+import {
+  cloneAndFreeze,
+  isPlainObject
+} from "../core/immutable.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "x", "y", "bins", "extent", "includeEmpty", "members", "as",
+  "resolved"
+]);
+const BIN_KEYS = Object.freeze(["x", "y"]);
+const EXTENT_KEYS = Object.freeze(["x", "y"]);
+const FIELD_KEYS = Object.freeze(["x0", "x1", "y0", "y1", "count", "members"]);
+const RESOLVED_KEYS = Object.freeze([
+  "extent", "edges", "eligibleCount", "occupiedCount"
+]);
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function rejectUnknownKeys(value, supported, label) {
+  const unknown = Object.keys(value).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ${label} property "${unknown}".`);
+  }
+}
+
+function requirePositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(`${label} must be a positive integer.`);
+  }
+  return value;
+}
+
+function normalizeBins(value) {
+  if (value === undefined) return { x: 10, y: 10 };
+  if (Number.isInteger(value)) return { x: value, y: value };
+  if (!isPlainObject(value)) {
+    throw new TypeError(
+      "2D bin bins must be a positive integer or an object with x and y."
+    );
+  }
+  rejectUnknownKeys(value, BIN_KEYS, "2D bin bins");
+  return { x: value.x, y: value.y };
+}
+
+function validateBins(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin bins must be an object.");
+  }
+  rejectUnknownKeys(value, BIN_KEYS, "2D bin bins");
+  requirePositiveInteger(value.x, "2D bin x bins");
+  requirePositiveInteger(value.y, "2D bin y bins");
+}
+
+function normalizeRequestedExtent(value) {
+  if (value === undefined) return { x: "auto", y: "auto" };
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin extent must be an object.");
+  }
+  rejectUnknownKeys(value, EXTENT_KEYS, "2D bin extent");
+  return {
+    x: value.x ?? "auto",
+    y: value.y ?? "auto"
+  };
+}
+
+function validateExtentValue(value, label, { allowAuto = true } = {}) {
+  if (allowAuto && value === "auto") return;
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    !value.every(Number.isFinite) ||
+    value[0] >= value[1]
+  ) {
+    throw new RangeError(`${label} must be two increasing finite numbers.`);
+  }
+}
+
+function validateRequestedExtent(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin extent must be an object.");
+  }
+  rejectUnknownKeys(value, EXTENT_KEYS, "2D bin extent");
+  validateExtentValue(value.x, "2D bin x extent");
+  validateExtentValue(value.y, "2D bin y extent");
+}
+
+function normalizeOutputFields(id, value, members) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError("2D bin as must be an object.");
+  }
+  if (value !== undefined) rejectUnknownKeys(value, FIELD_KEYS, "2D bin as");
+  if (!members && value?.members !== undefined) {
+    throw new Error("2D bin as.members requires members: true.");
+  }
+  return {
+    x0: value?.x0 ?? `__${id}_x0`,
+    x1: value?.x1 ?? `__${id}_x1`,
+    y0: value?.y0 ?? `__${id}_y0`,
+    y1: value?.y1 ?? `__${id}_y1`,
+    count: value?.count ?? `__${id}_count`,
+    ...(members ? { members: value?.members ?? `__${id}_members` } : {})
+  };
+}
+
+function validateOutputFields(value, members) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin as must be an object.");
+  }
+  rejectUnknownKeys(value, FIELD_KEYS, "2D bin as");
+  const required = ["x0", "x1", "y0", "y1", "count"];
+  if (members) required.push("members");
+  if (!members && value.members !== undefined) {
+    throw new Error("2D bin as.members requires members: true.");
+  }
+  const fields = required.map(role => requireField(
+    value[role],
+    `2D bin ${role} output field`
+  ));
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("2D bin output fields must be unique.");
+  }
+}
+
+function validateEdges(value, extent, count, axis) {
+  if (
+    !Array.isArray(value) ||
+    value.length !== count + 1 ||
+    !value.every(Number.isFinite)
+  ) {
+    throw new TypeError(`Resolved 2D bin ${axis} edges are invalid.`);
+  }
+  if (value[0] !== extent[0] || value.at(-1) !== extent[1]) {
+    throw new Error(`Resolved 2D bin ${axis} edges must match its extent.`);
+  }
+  for (let index = 1; index < value.length; index += 1) {
+    if (value[index] <= value[index - 1]) {
+      throw new Error(`Resolved 2D bin ${axis} edges must be increasing.`);
+    }
+  }
+}
+
+function validateResolved(value, bins) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Resolved 2D bin state must be a plain object.");
+  }
+  rejectUnknownKeys(value, RESOLVED_KEYS, "resolved 2D bin");
+  if (!isPlainObject(value.extent) || !isPlainObject(value.edges)) {
+    throw new TypeError("Resolved 2D bin extent and edges must be objects.");
+  }
+  rejectUnknownKeys(value.extent, EXTENT_KEYS, "resolved 2D bin extent");
+  rejectUnknownKeys(value.edges, EXTENT_KEYS, "resolved 2D bin edges");
+  for (const axis of ["x", "y"]) {
+    validateExtentValue(
+      value.extent[axis],
+      `Resolved 2D bin ${axis} extent`,
+      { allowAuto: false }
+    );
+    validateEdges(value.edges[axis], value.extent[axis], bins[axis], axis);
+  }
+  for (const property of ["eligibleCount", "occupiedCount"]) {
+    if (!Number.isInteger(value[property]) || value[property] < 0) {
+      throw new RangeError(`Resolved 2D bin ${property} must be a non-negative integer.`);
+    }
+  }
+  if (value.occupiedCount > bins.x * bins.y) {
+    throw new RangeError("Resolved 2D bin occupiedCount exceeds the grid size.");
+  }
+}
+
+export function validateBin2DTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("2D bin transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "2D bin transform");
+  if (transform.type !== "bin2d") {
+    throw new Error(`Unsupported 2D bin transform "${transform.type}".`);
+  }
+  requireField(transform.x, "2D bin x field");
+  requireField(transform.y, "2D bin y field");
+  validateBins(transform.bins);
+  validateRequestedExtent(transform.extent);
+  if (typeof transform.includeEmpty !== "boolean") {
+    throw new TypeError("2D bin includeEmpty must be a boolean.");
+  }
+  if (typeof transform.members !== "boolean") {
+    throw new TypeError("2D bin members must be a boolean.");
+  }
+  validateOutputFields(transform.as, transform.members);
+  if (transform.resolved !== undefined) {
+    validateResolved(transform.resolved, transform.bins);
+  }
+  return transform;
+}
+
+export function normalizeBin2DTransform({
+  id,
+  x,
+  y,
+  bins,
+  extent,
+  includeEmpty = false,
+  members = false,
+  as
+} = {}) {
+  const normalizedBins = normalizeBins(bins);
+  const transform = {
+    type: "bin2d",
+    x,
+    y,
+    bins: normalizedBins,
+    extent: normalizeRequestedExtent(extent),
+    includeEmpty,
+    members,
+    as: normalizeOutputFields(id, as, members)
+  };
+  validateBin2DTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function resolveExtent(values, requested, axis) {
+  const minimum = Math.min(...values);
+  const maximum = Math.max(...values);
+  const extent = requested === "auto" ? [minimum, maximum] : requested;
+  if (extent[0] > minimum || extent[1] < maximum) {
+    throw new RangeError(
+      `2D bin ${axis} extent must contain every eligible value.`
+    );
+  }
+  if (extent[0] === extent[1]) {
+    throw new RangeError(`2D bin ${axis} extent must have positive span.`);
+  }
+  return [...extent];
+}
+
+function createEdges(extent, count) {
+  const [minimum, maximum] = extent;
+  const step = (maximum - minimum) / count;
+  return Array.from({ length: count + 1 }, (_, index) =>
+    index === count ? maximum : minimum + step * index
+  );
+}
+
+function findBinIndex(value, edges) {
+  if (value === edges.at(-1)) return edges.length - 2;
+  let low = 0;
+  let high = edges.length - 1;
+  while (low + 1 < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (value < edges[middle]) high = middle;
+    else low = middle;
+  }
+  return low;
+}
+
+export function deriveBin2DRows(rows, transform) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("2D bin source rows must be an array.");
+  }
+  validateBin2DTransform(transform);
+  const eligible = rows.flatMap((row, index) =>
+    isPlainObject(row) &&
+    Number.isFinite(row[transform.x]) &&
+    Number.isFinite(row[transform.y])
+      ? [{ index, row }]
+      : []
+  );
+  if (eligible.length === 0) {
+    throw new Error(
+      "2D bin requires at least one row with finite x and y values."
+    );
+  }
+  const extent = {
+    x: resolveExtent(
+      eligible.map(item => item.row[transform.x]),
+      transform.extent.x,
+      "x"
+    ),
+    y: resolveExtent(
+      eligible.map(item => item.row[transform.y]),
+      transform.extent.y,
+      "y"
+    )
+  };
+  const edges = {
+    x: createEdges(extent.x, transform.bins.x),
+    y: createEdges(extent.y, transform.bins.y)
+  };
+  const buckets = Array.from(
+    { length: transform.bins.x * transform.bins.y },
+    () => []
+  );
+  for (const item of eligible) {
+    const xIndex = findBinIndex(item.row[transform.x], edges.x);
+    const yIndex = findBinIndex(item.row[transform.y], edges.y);
+    buckets[yIndex * transform.bins.x + xIndex].push(item.index);
+  }
+  const values = [];
+  for (let yIndex = 0; yIndex < transform.bins.y; yIndex += 1) {
+    for (let xIndex = 0; xIndex < transform.bins.x; xIndex += 1) {
+      const memberIndexes = buckets[yIndex * transform.bins.x + xIndex];
+      if (!transform.includeEmpty && memberIndexes.length === 0) continue;
+      values.push({
+        [transform.as.x0]: edges.x[xIndex],
+        [transform.as.x1]: edges.x[xIndex + 1],
+        [transform.as.y0]: edges.y[yIndex],
+        [transform.as.y1]: edges.y[yIndex + 1],
+        [transform.as.count]: memberIndexes.length,
+        ...(transform.members
+          ? { [transform.as.members]: [...memberIndexes] }
+          : {})
+      });
+    }
+  }
+  return cloneAndFreeze({
+    values,
+    resolved: {
+      extent,
+      edges,
+      eligibleCount: eligible.length,
+      occupiedCount: buckets.filter(bucket => bucket.length > 0).length
+    }
+  });
+}
+
+export function requestedBin2DTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  return cloneAndFreeze(requested);
+}