ggaction 0.0.1

package/src/grammar/curveCommands.js

@@ -0,0 +1,356 @@
+import { freezeOwned, isPlainObject } from "../core/immutable.js";
+import { buildLinearPathCommands } from "./pathCommands.js";
+
+export const CURVE_INTERPOLATIONS = Object.freeze([
+  "linear",
+  "step",
+  "step-before",
+  "step-after",
+  "basis",
+  "cardinal",
+  "monotone",
+  "natural"
+]);
+
+const SMOOTH_CURVES = new Set([
+  "basis",
+  "cardinal",
+  "monotone",
+  "natural"
+]);
+
+function ownCommands(commands) {
+  return freezeOwned(commands.map(command => freezeOwned(command)));
+}
+
+function validatePoints(points) {
+  if (
+    !Array.isArray(points) ||
+    points.length < 2 ||
+    !points.every(point =>
+      isPlainObject(point) &&
+      Object.keys(point).length === 2 &&
+      Number.isFinite(point.x) &&
+      Number.isFinite(point.y)
+    )
+  ) {
+    throw new TypeError(
+      "Curve points must contain at least two finite { x, y } objects."
+    );
+  }
+  return points;
+}
+
+export function validateCurveInterpolation(curve) {
+  if (!CURVE_INTERPOLATIONS.includes(curve)) {
+    throw new Error(`Unsupported curve interpolation "${curve}".`);
+  }
+  return curve;
+}
+
+function buildStepCommands(points, mode) {
+  const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
+  for (let index = 1; index < points.length; index += 1) {
+    const previous = points[index - 1];
+    const current = points[index];
+    if (mode === "step") {
+      const midpoint = (previous.x + current.x) / 2;
+      commands.push(
+        { op: "L", x: midpoint, y: previous.y },
+        { op: "L", x: midpoint, y: current.y },
+        { op: "L", x: current.x, y: current.y }
+      );
+    } else if (mode === "step-before") {
+      commands.push(
+        { op: "L", x: previous.x, y: current.y },
+        { op: "L", x: current.x, y: current.y }
+      );
+    } else {
+      commands.push(
+        { op: "L", x: current.x, y: previous.y },
+        { op: "L", x: current.x, y: current.y }
+      );
+    }
+  }
+  return ownCommands(commands);
+}
+
+function cubicLine(from, to) {
+  return {
+    op: "C",
+    x1: from.x + (to.x - from.x) / 3,
+    y1: from.y + (to.y - from.y) / 3,
+    x2: from.x + (to.x - from.x) * 2 / 3,
+    y2: from.y + (to.y - from.y) * 2 / 3,
+    x: to.x,
+    y: to.y
+  };
+}
+
+function buildBasisCommands(points) {
+  const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
+  let previous = points[0];
+  let current = points[1];
+  let endpoint = {
+    x: (5 * previous.x + current.x) / 6,
+    y: (5 * previous.y + current.y) / 6
+  };
+  commands.push(cubicLine(previous, endpoint));
+
+  for (let index = 2; index < points.length; index += 1) {
+    const next = points[index];
+    endpoint = {
+      x: (previous.x + 4 * current.x + next.x) / 6,
+      y: (previous.y + 4 * current.y + next.y) / 6
+    };
+    commands.push({
+      op: "C",
+      x1: (2 * previous.x + current.x) / 3,
+      y1: (2 * previous.y + current.y) / 3,
+      x2: (previous.x + 2 * current.x) / 3,
+      y2: (previous.y + 2 * current.y) / 3,
+      x: endpoint.x,
+      y: endpoint.y
+    });
+    previous = current;
+    current = next;
+  }
+
+  endpoint = {
+    x: (previous.x + 5 * current.x) / 6,
+    y: (previous.y + 5 * current.y) / 6
+  };
+  commands.push({
+    op: "C",
+    x1: (2 * previous.x + current.x) / 3,
+    y1: (2 * previous.y + current.y) / 3,
+    x2: (previous.x + 2 * current.x) / 3,
+    y2: (previous.y + 2 * current.y) / 3,
+    x: endpoint.x,
+    y: endpoint.y
+  });
+  commands.push(cubicLine(endpoint, current));
+  return ownCommands(commands);
+}
+
+function buildCardinalCommands(points) {
+  const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const before = points[index - 1] ?? points[index];
+    const current = points[index];
+    const next = points[index + 1];
+    const after = points[index + 2] ?? next;
+    commands.push({
+      op: "C",
+      x1: current.x + (next.x - before.x) / 6,
+      y1: current.y + (next.y - before.y) / 6,
+      x2: next.x - (after.x - current.x) / 6,
+      y2: next.y - (after.y - current.y) / 6,
+      x: next.x,
+      y: next.y
+    });
+  }
+  return ownCommands(commands);
+}
+
+function monotoneTangents(points) {
+  const intervals = points.slice(1).map((point, index) => {
+    const previous = points[index];
+    const width = point.x - previous.x;
+    if (!(width > 0)) {
+      throw new Error("Monotone curve requires strictly increasing x values.");
+    }
+    return { width, slope: (point.y - previous.y) / width };
+  });
+  const tangents = [intervals[0].slope];
+
+  for (let index = 1; index < points.length - 1; index += 1) {
+    const previous = intervals[index - 1];
+    const next = intervals[index];
+    if (
+      previous.slope === 0 ||
+      next.slope === 0 ||
+      Math.sign(previous.slope) !== Math.sign(next.slope)
+    ) {
+      tangents.push(0);
+      continue;
+    }
+    const previousWeight = 2 * next.width + previous.width;
+    const nextWeight = next.width + 2 * previous.width;
+    tangents.push(
+      (previousWeight + nextWeight) /
+      (previousWeight / previous.slope + nextWeight / next.slope)
+    );
+  }
+  tangents.push(intervals.at(-1).slope);
+  return tangents;
+}
+
+function buildMonotoneCommands(points) {
+  const tangents = monotoneTangents(points);
+  const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
+  for (let index = 1; index < points.length; index += 1) {
+    const previous = points[index - 1];
+    const current = points[index];
+    const third = (current.x - previous.x) / 3;
+    commands.push({
+      op: "C",
+      x1: previous.x + third,
+      y1: previous.y + tangents[index - 1] * third,
+      x2: current.x - third,
+      y2: current.y - tangents[index] * third,
+      x: current.x,
+      y: current.y
+    });
+  }
+  return ownCommands(commands);
+}
+
+function solveFirstControlPoints(values) {
+  const segmentCount = values.length - 1;
+  const diagonal = Array(segmentCount).fill(4);
+  const right = Array(segmentCount);
+  diagonal[0] = 2;
+  diagonal[segmentCount - 1] = 7;
+  right[0] = values[0] + 2 * values[1];
+  for (let index = 1; index < segmentCount - 1; index += 1) {
+    right[index] = 4 * values[index] + 2 * values[index + 1];
+  }
+  right[segmentCount - 1] =
+    8 * values[segmentCount - 1] + values[segmentCount];
+
+  for (let index = 1; index < segmentCount; index += 1) {
+    const lower = index === segmentCount - 1 ? 2 : 1;
+    const factor = lower / diagonal[index - 1];
+    diagonal[index] -= factor;
+    right[index] -= factor * right[index - 1];
+  }
+
+  const controls = Array(segmentCount);
+  controls[segmentCount - 1] =
+    right[segmentCount - 1] / diagonal[segmentCount - 1];
+  for (let index = segmentCount - 2; index >= 0; index -= 1) {
+    controls[index] = (right[index] - controls[index + 1]) / diagonal[index];
+  }
+  return controls;
+}
+
+function buildNaturalCommands(points) {
+  const x = points.map(point => point.x);
+  const y = points.map(point => point.y);
+  const firstX = solveFirstControlPoints(x);
+  const firstY = solveFirstControlPoints(y);
+  const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
+  const last = points.length - 2;
+
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const secondX = index === last
+      ? (x[index + 1] + firstX[index]) / 2
+      : 2 * x[index + 1] - firstX[index + 1];
+    const secondY = index === last
+      ? (y[index + 1] + firstY[index]) / 2
+      : 2 * y[index + 1] - firstY[index + 1];
+    commands.push({
+      op: "C",
+      x1: firstX[index],
+      y1: firstY[index],
+      x2: secondX,
+      y2: secondY,
+      x: x[index + 1],
+      y: y[index + 1]
+    });
+  }
+  return ownCommands(commands);
+}
+
+export function buildCurvePathCommands(points, curve = "linear") {
+  const validatedPoints = validatePoints(points);
+  const validatedCurve = validateCurveInterpolation(curve);
+  if (validatedCurve === "linear" ||
+      (SMOOTH_CURVES.has(validatedCurve) && points.length < 3)) {
+    return buildLinearPathCommands(validatedPoints);
+  }
+  if (validatedCurve.startsWith("step")) {
+    return buildStepCommands(validatedPoints, validatedCurve);
+  }
+  if (validatedCurve === "basis") return buildBasisCommands(validatedPoints);
+  if (validatedCurve === "cardinal") {
+    return buildCardinalCommands(validatedPoints);
+  }
+  if (validatedCurve === "monotone") {
+    return buildMonotoneCommands(validatedPoints);
+  }
+  return buildNaturalCommands(validatedPoints);
+}
+
+function reverseOpenPathCommands(commands) {
+  const endpoints = commands.map(command => ({ x: command.x, y: command.y }));
+  const reversed = [
+    { op: "M", x: endpoints.at(-1).x, y: endpoints.at(-1).y }
+  ];
+  for (let index = commands.length - 1; index > 0; index -= 1) {
+    const command = commands[index];
+    const endpoint = endpoints[index - 1];
+    if (command.op === "C") {
+      reversed.push({
+        op: "C",
+        x1: command.x2,
+        y1: command.y2,
+        x2: command.x1,
+        y2: command.y1,
+        x: endpoint.x,
+        y: endpoint.y
+      });
+    } else {
+      reversed.push({ op: "L", x: endpoint.x, y: endpoint.y });
+    }
+  }
+  return reversed;
+}
+
+function transposeCommands(commands) {
+  return commands.map(command => command.op === "C"
+    ? {
+        op: "C",
+        x1: command.y1,
+        y1: command.x1,
+        x2: command.y2,
+        y2: command.x2,
+        x: command.y,
+        y: command.x
+      }
+    : command.op === "Z"
+      ? command
+      : { op: command.op, x: command.y, y: command.x });
+}
+
+function buildOrientedCurvePathCommands(points, curve, independentAxis) {
+  if (independentAxis === "x") return buildCurvePathCommands(points, curve);
+  if (independentAxis !== "y") {
+    throw new Error(`Unsupported curve independent axis "${independentAxis}".`);
+  }
+  const transposed = points.map(point => ({ x: point.y, y: point.x }));
+  return ownCommands(transposeCommands(buildCurvePathCommands(transposed, curve)));
+}
+
+export function buildAreaCurvePathCommands(
+  lowerPoints,
+  upperPoints,
+  curve = "linear",
+  { independentAxis = "x" } = {}
+) {
+  const lower = buildOrientedCurvePathCommands(
+    lowerPoints,
+    curve,
+    independentAxis
+  );
+  const upper = reverseOpenPathCommands(
+    buildOrientedCurvePathCommands(upperPoints, curve, independentAxis)
+  );
+  return ownCommands([
+    ...lower,
+    { op: "L", x: upper[0].x, y: upper[0].y },
+    ...upper.slice(1),
+    { op: "Z" }
+  ]);
+}

package/src/grammar/density.js

@@ -0,0 +1,296 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import { isNominalValue } from "./scales.js";
+
+const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
+
+export const DENSITY_KERNELS = Object.freeze([
+  "gaussian",
+  "epanechnikov",
+  "uniform",
+  "triangular"
+]);
+export const DENSITY_NORMALIZATIONS = Object.freeze(["unit", "count"]);
+
+export function validateDensityKernel(value) {
+  if (!DENSITY_KERNELS.includes(value)) {
+    throw new Error(`Unsupported density kernel "${value}".`);
+  }
+  return value;
+}
+
+export function validateDensityNormalization(value) {
+  if (!DENSITY_NORMALIZATIONS.includes(value)) {
+    throw new Error(`Unsupported density normalization "${value}".`);
+  }
+  return value;
+}
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function validateDensityTransform(transform) {
+  const supported = [
+    "type", "field", "groupBy", "bandwidth", "extent", "steps", "as",
+    "resolve", "kernel", "normalization"
+  ];
+  const unknown = Object.keys(transform).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown density transform property "${unknown}".`);
+  }
+  if (transform.type !== "density") {
+    throw new Error(`Unsupported density transform "${transform.type}".`);
+  }
+  requireField(transform.field, "Density field");
+  if (transform.groupBy !== undefined) {
+    requireField(transform.groupBy, "Density groupBy");
+  }
+  validateDensityKernel(transform.kernel ?? "gaussian");
+  validateDensityNormalization(transform.normalization ?? "unit");
+  if (
+    transform.bandwidth !== "auto" &&
+    (!Number.isFinite(transform.bandwidth) || transform.bandwidth <= 0)
+  ) {
+    throw new RangeError(
+      "Density bandwidth must be a positive finite number or auto."
+    );
+  }
+  if (
+    transform.extent !== "auto" &&
+    (!Array.isArray(transform.extent) ||
+      transform.extent.length !== 2 ||
+      !transform.extent.every(Number.isFinite) ||
+      transform.extent[0] >= transform.extent[1])
+  ) {
+    throw new RangeError(
+      "Density extent must be an ascending pair of finite numbers or auto."
+    );
+  }
+  if (!Number.isInteger(transform.steps) || transform.steps < 2) {
+    throw new RangeError("Density steps must be an integer of at least 2.");
+  }
+  if (
+    !Array.isArray(transform.as) ||
+    transform.as.length !== 2 ||
+    !transform.as.every(value => typeof value === "string" && value.length > 0) ||
+    transform.as[0] === transform.as[1]
+  ) {
+    throw new TypeError("Density as must contain two distinct non-empty fields.");
+  }
+  const collisions = new Set([
+    transform.field,
+    transform.groupBy
+  ].filter(Boolean));
+  if (transform.as.some(value => collisions.has(value))) {
+    throw new Error(
+      "Density output fields must not collide with source or group fields."
+    );
+  }
+  if (transform.resolve !== "shared") {
+    throw new Error(`Unsupported density resolve "${transform.resolve}".`);
+  }
+  return transform;
+}
+
+function quantile(sortedValues, probability) {
+  const index = (sortedValues.length - 1) * probability;
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sortedValues[lower];
+  const ratio = index - lower;
+  return sortedValues[lower] * (1 - ratio) + sortedValues[upper] * ratio;
+}
+
+function sampleDeviation(values) {
+  if (values.length < 2) return 0;
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const sumSquares = values.reduce(
+    (sum, value) => sum + (value - mean) ** 2,
+    0
+  );
+  return Math.sqrt(sumSquares / (values.length - 1));
+}
+
+export function estimateDensityBandwidth(values) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError("Density bandwidth values must be finite numbers.");
+  }
+  if (values.length < 2) {
+    throw new Error("Density auto bandwidth requires at least two values.");
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const deviation = sampleDeviation(sorted);
+  const interquartileRange = quantile(sorted, 0.75) - quantile(sorted, 0.25);
+  const robustDeviation = interquartileRange / 1.34;
+  const spread = robustDeviation > 0
+    ? Math.min(deviation, robustDeviation)
+    : deviation;
+  const bandwidth = 1.06 * spread * sorted.length ** -0.2;
+  if (!Number.isFinite(bandwidth) || bandwidth <= 0) {
+    throw new Error("Density auto bandwidth requires varying finite values.");
+  }
+  return bandwidth;
+}
+
+function resolveBandwidth(value, sourceValues) {
+  if (value === undefined || value === "auto") {
+    return estimateDensityBandwidth(sourceValues);
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      "Density bandwidth must be a positive finite number or auto."
+    );
+  }
+  return value;
+}
+
+function resolveExtent(value, sourceValues) {
+  if (value === undefined || value === "auto") {
+    const extent = [Math.min(...sourceValues), Math.max(...sourceValues)];
+    if (extent[0] === extent[1]) {
+      throw new Error("Density observed extent requires varying finite values.");
+    }
+    return extent;
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    !value.every(Number.isFinite) ||
+    value[0] >= value[1]
+  ) {
+    throw new RangeError(
+      "Density extent must be an ascending pair of finite numbers or auto."
+    );
+  }
+  return [...value];
+}
+
+function resolveOutputFields(as, field, groupBy) {
+  const resolved = as ?? [`${field}_value`, `${field}_density`];
+  if (
+    !Array.isArray(resolved) ||
+    resolved.length !== 2 ||
+    !resolved.every(value => typeof value === "string" && value.length > 0) ||
+    resolved[0] === resolved[1]
+  ) {
+    throw new TypeError("Density as must contain two distinct non-empty fields.");
+  }
+  const collisions = new Set([field, groupBy].filter(Boolean));
+  if (resolved.some(value => collisions.has(value))) {
+    throw new Error("Density output fields must not collide with source or group fields.");
+  }
+  return [...resolved];
+}
+
+const KERNEL_FUNCTIONS = Object.freeze({
+  gaussian(value) {
+    return Math.exp(-0.5 * value ** 2) / SQRT_TWO_PI;
+  },
+  epanechnikov(value) {
+    return Math.abs(value) <= 1 ? 0.75 * (1 - value ** 2) : 0;
+  },
+  uniform(value) {
+    return Math.abs(value) <= 1 ? 0.5 : 0;
+  },
+  triangular(value) {
+    return Math.abs(value) <= 1 ? 1 - Math.abs(value) : 0;
+  }
+});
+
+function estimateAt(sample, values, bandwidth, kernel, normalization) {
+  const sum = values.reduce(
+    (total, value) => total + KERNEL_FUNCTIONS[kernel](
+      (sample - value) / bandwidth
+    ),
+    0
+  );
+  const denominator = normalization === "unit"
+    ? values.length * bandwidth
+    : bandwidth;
+  return sum / denominator;
+}
+
+export function deriveKernelDensity(values, {
+  field,
+  groupBy,
+  bandwidth = "auto",
+  extent = "auto",
+  steps = 100,
+  kernel = "gaussian",
+  normalization = "unit",
+  as
+} = {}) {
+  if (!Array.isArray(values)) {
+    throw new TypeError("Density values must be an array.");
+  }
+  const sourceField = requireField(field, "Density field");
+  const groupField = groupBy === undefined
+    ? undefined
+    : requireField(groupBy, "Density groupBy");
+  if (!Number.isInteger(steps) || steps < 2) {
+    throw new RangeError("Density steps must be an integer of at least 2.");
+  }
+  const outputFields = resolveOutputFields(as, sourceField, groupField);
+  const resolvedKernel = validateDensityKernel(kernel);
+  const resolvedNormalization = validateDensityNormalization(normalization);
+  const validRows = values.filter(row =>
+    row !== null &&
+    typeof row === "object" &&
+    Number.isFinite(row[sourceField]) &&
+    (groupField === undefined || isNominalValue(row[groupField]))
+  );
+  if (validRows.length === 0) {
+    throw new Error("Density requires at least one valid field/group row.");
+  }
+  const sourceValues = validRows.map(row => row[sourceField]);
+  const resolvedBandwidth = resolveBandwidth(bandwidth, sourceValues);
+  const resolvedExtent = resolveExtent(extent, sourceValues);
+  const groups = groupField === undefined
+    ? [undefined]
+    : [...new Set(validRows.map(row => row[groupField]))];
+  const sampleStep = (resolvedExtent[1] - resolvedExtent[0]) / (steps - 1);
+  const samples = Array.from(
+    { length: steps },
+    (_, index) => index === steps - 1
+      ? resolvedExtent[1]
+      : resolvedExtent[0] + sampleStep * index
+  );
+  const rows = [];
+  for (const group of groups) {
+    const groupValues = validRows
+      .filter(row => groupField === undefined || row[groupField] === group)
+      .map(row => row[sourceField]);
+    for (const sample of samples) {
+      rows.push({
+        ...(groupField === undefined ? {} : { [groupField]: group }),
+        [outputFields[0]]: sample,
+        [outputFields[1]]: estimateAt(
+          sample,
+          groupValues,
+          resolvedBandwidth,
+          resolvedKernel,
+          resolvedNormalization
+        )
+      });
+    }
+  }
+  return cloneAndFreeze({
+    fields: {
+      source: sourceField,
+      ...(groupField === undefined ? {} : { group: groupField }),
+      value: outputFields[0],
+      density: outputFields[1]
+    },
+    groups,
+    bandwidth: resolvedBandwidth,
+    kernel: resolvedKernel,
+    normalization: resolvedNormalization,
+    extent: resolvedExtent,
+    steps,
+    samples,
+    values: rows
+  });
+}