ggaction 0.0.2 → 0.0.4

package/src/grammar/polarPaths.js

@@ -0,0 +1,161 @@
+import { freezeOwned } from "../core/immutable.js";
+
+const KAPPA = 0.5522847498307936;
+const MAX_ARC_SEGMENT = 90;
+
+function validateFrame(frame) {
+  if (
+    frame === null ||
+    typeof frame !== "object" ||
+    ![frame.centerX, frame.centerY, frame.availableRadius].every(Number.isFinite) ||
+    frame.availableRadius < 0
+  ) {
+    throw new TypeError(
+      "Polar path frame requires finite centerX, centerY, and non-negative availableRadius."
+    );
+  }
+  return frame;
+}
+
+function validateRadius(value, label, frame) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  if (value > frame.availableRadius) {
+    throw new RangeError(`${label} must fit inside the Polar frame.`);
+  }
+  return value;
+}
+
+function pointAt(frame, theta, radius) {
+  const radians = theta * Math.PI / 180;
+  return {
+    x: frame.centerX + radius * Math.sin(radians),
+    y: frame.centerY - radius * Math.cos(radians)
+  };
+}
+
+function arcCommands(frame, radius, startTheta, endTheta) {
+  const sweep = endTheta - startTheta;
+  const segments = Math.ceil(Math.abs(sweep) / MAX_ARC_SEGMENT);
+  const delta = sweep / segments;
+  const commands = [];
+  for (let index = 0; index < segments; index += 1) {
+    const start = startTheta + delta * index;
+    const end = start + delta;
+    const startRadians = start * Math.PI / 180;
+    const endRadians = end * Math.PI / 180;
+    const deltaRadians = endRadians - startRadians;
+    const control = 4 / 3 * Math.tan(deltaRadians / 4);
+    const from = pointAt(frame, start, radius);
+    const to = pointAt(frame, end, radius);
+    const fromDerivative = {
+      x: radius * Math.cos(startRadians),
+      y: radius * Math.sin(startRadians)
+    };
+    const toDerivative = {
+      x: radius * Math.cos(endRadians),
+      y: radius * Math.sin(endRadians)
+    };
+    commands.push({
+      op: "C",
+      x1: from.x + control * fromDerivative.x,
+      y1: from.y + control * fromDerivative.y,
+      x2: to.x - control * toDerivative.x,
+      y2: to.y - control * toDerivative.y,
+      x: to.x,
+      y: to.y
+    });
+  }
+  return commands;
+}
+
+export function buildPolarCircleCommands(frame, radius) {
+  validateFrame(frame);
+  validateRadius(radius, "Polar circle radius", frame);
+  const control = radius * KAPPA;
+  const { centerX: cx, centerY: cy } = frame;
+  return freezeOwned([
+    { op: "M", x: cx, y: cy - radius },
+    {
+      op: "C",
+      x1: cx + control,
+      y1: cy - radius,
+      x2: cx + radius,
+      y2: cy - control,
+      x: cx + radius,
+      y: cy
+    },
+    {
+      op: "C",
+      x1: cx + radius,
+      y1: cy + control,
+      x2: cx + control,
+      y2: cy + radius,
+      x: cx,
+      y: cy + radius
+    },
+    {
+      op: "C",
+      x1: cx - control,
+      y1: cy + radius,
+      x2: cx - radius,
+      y2: cy + control,
+      x: cx - radius,
+      y: cy
+    },
+    {
+      op: "C",
+      x1: cx - radius,
+      y1: cy - control,
+      x2: cx - control,
+      y2: cy - radius,
+      x: cx,
+      y: cy - radius
+    },
+    { op: "Z" }
+  ]);
+}
+
+export function buildAnnularSectorCommands({
+  frame,
+  startTheta,
+  endTheta,
+  innerRadius = 0,
+  outerRadius,
+  padAngle = 0
+}) {
+  validateFrame(frame);
+  if (![startTheta, endTheta].every(Number.isFinite)) {
+    throw new TypeError("Polar sector angles must be finite numbers.");
+  }
+  validateRadius(innerRadius, "Polar sector innerRadius", frame);
+  validateRadius(outerRadius, "Polar sector outerRadius", frame);
+  if (outerRadius <= innerRadius) {
+    throw new RangeError("Polar sector outerRadius must be greater than innerRadius.");
+  }
+  const sweep = endTheta - startTheta;
+  if (sweep === 0 || Math.abs(sweep) > 360) {
+    throw new RangeError("Polar sector sweep must be non-zero and at most 360 degrees.");
+  }
+  if (!Number.isFinite(padAngle) || padAngle < 0 || padAngle >= Math.abs(sweep)) {
+    throw new RangeError(
+      "Polar sector padAngle must be non-negative and smaller than its sweep."
+    );
+  }
+  const direction = Math.sign(sweep);
+  const start = startTheta + direction * padAngle / 2;
+  const end = endTheta - direction * padAngle / 2;
+  const commands = [
+    { op: "M", ...pointAt(frame, start, outerRadius) },
+    ...arcCommands(frame, outerRadius, start, end)
+  ];
+  if (innerRadius === 0) {
+    commands.push({ op: "L", x: frame.centerX, y: frame.centerY });
+  } else {
+    commands.push({ op: "L", ...pointAt(frame, end, innerRadius) });
+    commands.push(...arcCommands(frame, innerRadius, end, start));
+  }
+  commands.push({ op: "Z" });
+  return freezeOwned(commands);
+}

package/src/grammar/positionCompatibility.js

@@ -1,16 +1,24 @@
 export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
   point: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
-    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
   }),
   line: Object.freeze({
     x: Object.freeze(["quantitative", "temporal"]),
-    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
   }),
   area: Object.freeze({
     x: Object.freeze(["quantitative", "temporal"]),
     y: Object.freeze(["quantitative", "temporal"])
   }),
+  arc: Object.freeze({
+    theta: Object.freeze(["ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
+  }),
   rule: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
@@ -18,6 +26,14 @@ export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
   bar: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+  }),
+  text: Object.freeze({
+    x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+  }),
+  rect: Object.freeze({
+    x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
   })
 });
 

package/src/grammar/rects.js

@@ -0,0 +1,26 @@
+export const RECT_MODES = Object.freeze({
+  discrete: "discrete",
+  ranged: "ranged"
+});
+
+function categorical(encoding) {
+  return ["nominal", "ordinal"].includes(encoding?.fieldType) &&
+    encoding.scale !== undefined;
+}
+
+function ranged(primary, secondary) {
+  return primary?.scale !== undefined &&
+    secondary?.scale === primary.scale &&
+    ["quantitative", "temporal"].includes(primary.fieldType) &&
+    secondary.fieldType === primary.fieldType;
+}
+
+export function resolveRectMode(layer) {
+  if (layer?.mark?.type !== "rect") return undefined;
+  const { x, y, x2, y2 } = layer.encoding ?? {};
+  if (x2 === undefined && y2 === undefined && categorical(x) && categorical(y)) {
+    return RECT_MODES.discrete;
+  }
+  if (ranged(x, x2) && ranged(y, y2)) return RECT_MODES.ranged;
+  return undefined;
+}

package/src/grammar/regression/derive.js

@@ -0,0 +1,97 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import {
+  readNominalField,
+  readQuantitativeField
+} from "../scales/index.js";
+import { fitRegressionGroup, predictRegressionAt } from "./models.js";
+import {
+  normalizeRegressionParameters,
+  requireRegressionField
+} from "./parameters.js";
+
+export const REGRESSION_LOWER_FIELD = "__regression_ci_lower";
+export const REGRESSION_UPPER_FIELD = "__regression_ci_upper";
+
+export function deriveRegression(values, {
+  x,
+  y,
+  groupBy,
+  method,
+  degree,
+  span,
+  confidence,
+  interval
+} = {}) {
+  if (!Array.isArray(values)) {
+    throw new TypeError("Regression values must be an array.");
+  }
+  requireRegressionField(x, "Regression x field");
+  requireRegressionField(y, "Regression y field");
+  if (groupBy !== undefined) {
+    requireRegressionField(groupBy, "Regression groupBy field");
+  }
+  const parameters = normalizeRegressionParameters({
+    method,
+    degree,
+    span,
+    confidence,
+    interval
+  });
+  readQuantitativeField(values, x);
+  readQuantitativeField(values, y);
+  if (groupBy !== undefined) readNominalField(values, groupBy);
+
+  const groups = groupBy === undefined
+    ? [undefined]
+    : [...new Set(values.map(row => row[groupBy]))];
+  const models = [];
+  const rows = [];
+
+  for (const group of groups) {
+    const groupRows = groupBy === undefined
+      ? values
+      : values.filter(row => row[groupBy] === group);
+    const model = fitRegressionGroup(groupRows, {
+      x,
+      y,
+      group,
+      parameters
+    });
+    const xValues = [...new Set(groupRows.map(row => row[x]))]
+      .sort((left, right) => left - right);
+    models.push({ ...(groupBy === undefined ? {} : { group }), ...model, xValues });
+
+    for (const xValue of xValues) {
+      const prediction = predictRegressionAt(model, xValue, parameters);
+      rows.push({
+        ...(groupBy === undefined ? {} : { [groupBy]: group }),
+        [x]: xValue,
+        [y]: prediction.prediction,
+        ...(parameters.method === "loess" ? {} : {
+          [REGRESSION_LOWER_FIELD]: prediction.prediction - prediction.margin,
+          [REGRESSION_UPPER_FIELD]: prediction.prediction + prediction.margin
+        })
+      });
+    }
+  }
+
+  return cloneAndFreeze({
+    fields: {
+      x,
+      y,
+      ...(groupBy === undefined ? {} : { group: groupBy }),
+      ...(parameters.method === "loess" ? {} : {
+        lower: REGRESSION_LOWER_FIELD,
+        upper: REGRESSION_UPPER_FIELD
+      })
+    },
+    parameters,
+    groups,
+    models,
+    values: rows
+  });
+}
+
+export function deriveLinearRegression(values, options = {}) {
+  return deriveRegression(values, { ...options, method: "linear" });
+}

package/src/grammar/regression/index.js

@@ -0,0 +1,22 @@
+import { studentTCriticalValue } from "../statistics/studentT.js";
+
+export {
+  REGRESSION_LOWER_FIELD,
+  REGRESSION_UPPER_FIELD,
+  deriveLinearRegression,
+  deriveRegression
+} from "./derive.js";
+export {
+  normalizeRegressionParameters,
+  validateRegressionTransform
+} from "./parameters.js";
+
+export function studentTCritical(confidence, degreesOfFreedom) {
+  if (!Number.isFinite(confidence) || confidence <= 0 || confidence >= 1) {
+    throw new RangeError("Regression confidence must be between 0 and 1.");
+  }
+  if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom <= 0) {
+    throw new RangeError("Student-t degrees of freedom must be positive.");
+  }
+  return studentTCriticalValue(confidence, degreesOfFreedom);
+}

package/src/grammar/regression/models.js

@@ -0,0 +1,282 @@
+import { studentTCriticalValue } from "../statistics/studentT.js";
+
+function fitLinearGroup(rows, { x, y, group, confidence }) {
+  const count = rows.length;
+  const groupLabel = group === undefined ? "all" : String(group);
+  if (count < 3) {
+    throw new Error(
+      `Regression group "${groupLabel}" requires at least three rows.`
+    );
+  }
+  const meanX = rows.reduce((sum, row) => sum + row[x], 0) / count;
+  const meanY = rows.reduce((sum, row) => sum + row[y], 0) / count;
+  let sxx = 0;
+  let sxy = 0;
+  for (const row of rows) {
+    const xDifference = row[x] - meanX;
+    sxx += xDifference ** 2;
+    sxy += xDifference * (row[y] - meanY);
+  }
+  if (sxx === 0) {
+    throw new Error(
+      `Regression group "${groupLabel}" requires varying x values.`
+    );
+  }
+  const slope = sxy / sxx;
+  const intercept = meanY - slope * meanX;
+  const residualSumSquares = rows.reduce((sum, row) => {
+    const residual = row[y] - (intercept + slope * row[x]);
+    return sum + residual ** 2;
+  }, 0);
+  const degreesOfFreedom = count - 2;
+  return {
+    count,
+    degreesOfFreedom,
+    meanX,
+    meanY,
+    sxx,
+    slope,
+    intercept,
+    residualSumSquares,
+    residualStandardError: Math.sqrt(residualSumSquares / degreesOfFreedom),
+    critical: studentTCriticalValue(confidence, degreesOfFreedom)
+  };
+}
+
+function solveLinearSystem(matrix, vector) {
+  const size = matrix.length;
+  const augmented = matrix.map((row, index) => [...row, vector[index]]);
+  for (let column = 0; column < size; column += 1) {
+    let pivot = column;
+    for (let row = column + 1; row < size; row += 1) {
+      if (Math.abs(augmented[row][column]) > Math.abs(augmented[pivot][column])) {
+        pivot = row;
+      }
+    }
+    if (Math.abs(augmented[pivot][column]) < 1e-12) {
+      throw new Error("Polynomial regression design is singular.");
+    }
+    [augmented[column], augmented[pivot]] = [
+      augmented[pivot], augmented[column]
+    ];
+    const divisor = augmented[column][column];
+    for (let index = column; index <= size; index += 1) {
+      augmented[column][index] /= divisor;
+    }
+    for (let row = 0; row < size; row += 1) {
+      if (row === column) continue;
+      const factor = augmented[row][column];
+      for (let index = column; index <= size; index += 1) {
+        augmented[row][index] -= factor * augmented[column][index];
+      }
+    }
+  }
+  return augmented.map(row => row[size]);
+}
+
+function invertSymmetricMatrix(matrix) {
+  return matrix.map((_, column) => solveLinearSystem(
+    matrix,
+    matrix.map((__, row) => row === column ? 1 : 0)
+  ));
+}
+
+function dot(left, right) {
+  return left.reduce((sum, value, index) => sum + value * right[index], 0);
+}
+
+function binomial(n, k) {
+  let result = 1;
+  for (let index = 1; index <= k; index += 1) {
+    result *= (n - index + 1) / index;
+  }
+  return result;
+}
+
+function rawPolynomialCoefficients(coefficients, center, scale) {
+  return coefficients.map((_, degree) => coefficients.reduce(
+    (sum, coefficient, power) => power < degree
+      ? sum
+      : sum + coefficient * binomial(power, degree) *
+        (-center) ** (power - degree) / scale ** power,
+    0
+  ));
+}
+
+function fitPolynomialGroup(rows, { x, y, group, confidence, degree }) {
+  const count = rows.length;
+  const parameterCount = degree + 1;
+  const groupLabel = group === undefined ? "all" : String(group);
+  if (
+    count < degree + 2 ||
+    new Set(rows.map(row => row[x])).size < parameterCount
+  ) {
+    throw new Error(
+      `Polynomial regression group "${groupLabel}" requires at least ` +
+      `${degree + 2} rows and ${parameterCount} distinct x values.`
+    );
+  }
+  const center = rows.reduce((sum, row) => sum + row[x], 0) / count;
+  const scale = Math.max(...rows.map(row => Math.abs(row[x] - center)));
+  if (!(scale > 0)) {
+    throw new Error(
+      `Regression group "${groupLabel}" requires varying x values.`
+    );
+  }
+  const design = rows.map(row => {
+    const normalized = (row[x] - center) / scale;
+    return Array.from(
+      { length: parameterCount },
+      (_, power) => normalized ** power
+    );
+  });
+  const normal = Array.from({ length: parameterCount }, (_, row) =>
+    Array.from({ length: parameterCount }, (_, column) =>
+      design.reduce(
+        (sum, basis) => sum + basis[row] * basis[column],
+        0
+      )
+    )
+  );
+  const response = Array.from({ length: parameterCount }, (_, column) =>
+    design.reduce(
+      (sum, basis, index) => sum + basis[column] * rows[index][y],
+      0
+    )
+  );
+  const normalizedCoefficients = solveLinearSystem(normal, response);
+  const inverse = invertSymmetricMatrix(normal);
+  const fitted = design.map(basis => dot(basis, normalizedCoefficients));
+  const residualSumSquares = fitted.reduce(
+    (sum, value, index) => sum + (rows[index][y] - value) ** 2,
+    0
+  );
+  const degreesOfFreedom = count - parameterCount;
+  const residualVariance = residualSumSquares / degreesOfFreedom;
+  return {
+    count,
+    degreesOfFreedom,
+    degree,
+    coefficients: rawPolynomialCoefficients(
+      normalizedCoefficients,
+      center,
+      scale
+    ),
+    normalizedCoefficients,
+    center,
+    scale,
+    inverse,
+    residualSumSquares,
+    residualStandardError: Math.sqrt(residualVariance),
+    critical: studentTCriticalValue(confidence, degreesOfFreedom)
+  };
+}
+
+function evaluatePolynomial(model, xValue) {
+  const normalized = (xValue - model.center) / model.scale;
+  const basis = model.normalizedCoefficients.map(
+    (_, power) => normalized ** power
+  );
+  return {
+    prediction: dot(basis, model.normalizedCoefficients),
+    leverage: dot(basis, model.inverse.map(row => dot(row, basis)))
+  };
+}
+
+function fitLoessGroup(rows, { x, y, group, span }) {
+  const groupLabel = group === undefined ? "all" : String(group);
+  if (rows.length < 2 || new Set(rows.map(row => row[x])).size < 2) {
+    throw new Error(
+      `LOESS regression group "${groupLabel}" requires at least two rows ` +
+      "and varying x values."
+    );
+  }
+  const neighborCount = Math.max(2, Math.ceil(span * rows.length));
+  const xValues = [...new Set(rows.map(row => row[x]))]
+    .sort((left, right) => left - right);
+  const fits = xValues.map(xValue => {
+    const neighbors = rows
+      .map((row, index) => ({
+        row,
+        index,
+        distance: Math.abs(row[x] - xValue)
+      }))
+      .sort((left, right) =>
+        left.distance - right.distance || left.index - right.index
+      )
+      .slice(0, neighborCount);
+    const radius = neighbors.at(-1).distance;
+    const weighted = neighbors.map(neighbor => ({
+      ...neighbor,
+      weight: radius === 0
+        ? 1
+        : (1 - (neighbor.distance / radius) ** 3) ** 3
+    }));
+    const totalWeight = weighted.reduce(
+      (sum, item) => sum + item.weight,
+      0
+    );
+    const meanDifference = weighted.reduce(
+      (sum, item) => sum + item.weight * (item.row[x] - xValue),
+      0
+    ) / totalWeight;
+    const meanY = weighted.reduce(
+      (sum, item) => sum + item.weight * item.row[y],
+      0
+    ) / totalWeight;
+    let variance = 0;
+    let covariance = 0;
+    for (const item of weighted) {
+      const difference = item.row[x] - xValue - meanDifference;
+      variance += item.weight * difference ** 2;
+      covariance += item.weight * difference * (item.row[y] - meanY);
+    }
+    const slope = variance === 0 ? 0 : covariance / variance;
+    return {
+      x: xValue,
+      prediction: meanY - slope * meanDifference,
+      neighborIndices: weighted.map(item => item.index)
+    };
+  });
+  return { count: rows.length, span, neighborCount, fits };
+}
+
+export function fitRegressionGroup(rows, { x, y, group, parameters }) {
+  if (parameters.method === "linear") {
+    return fitLinearGroup(rows, {
+      x,
+      y,
+      group,
+      confidence: parameters.confidence
+    });
+  }
+  if (parameters.method === "polynomial") {
+    return fitPolynomialGroup(rows, {
+      x,
+      y,
+      group,
+      confidence: parameters.confidence,
+      degree: parameters.degree
+    });
+  }
+  return fitLoessGroup(rows, { x, y, group, span: parameters.span });
+}
+
+export function predictRegressionAt(model, xValue, parameters) {
+  const polynomial = parameters.method === "polynomial"
+    ? evaluatePolynomial(model, xValue)
+    : undefined;
+  const prediction = parameters.method === "linear"
+    ? model.intercept + model.slope * xValue
+    : parameters.method === "polynomial"
+      ? polynomial.prediction
+      : model.fits.find(fit => fit.x === xValue).prediction;
+  if (parameters.method === "loess") return { prediction };
+  const leverage = parameters.method === "linear"
+    ? 1 / model.count + (xValue - model.meanX) ** 2 / model.sxx
+    : polynomial.leverage;
+  const standardError = model.residualStandardError * Math.sqrt(
+    leverage + (parameters.interval === "prediction" ? 1 : 0)
+  );
+  return { prediction, margin: model.critical * standardError };
+}