ggaction 0.0.3 → 0.0.5

package/src/grammar/parallelCoordinates.js

@@ -0,0 +1,213 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+import { validateOptionObject } from "../core/validation.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  validateSemanticFieldType
+} from "./scales/index.js";
+
+const DIMENSION_OPTIONS = Object.freeze([
+  "field", "fieldType", "title", "scale"
+]);
+const FIELD_TYPES = new Set(["quantitative", "ordinal"]);
+const MISSING_POLICIES = new Set(["break", "drop-row", "error"]);
+const DIMENSION_SCALE_OPTIONS = Object.freeze([
+  "type", "domain", "range", "nice", "zero", "clamp", "reverse",
+  "base", "exponent", "constant", "paddingInner", "paddingOuter",
+  "padding", "align", "unknown"
+]);
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function validateParallelKeyField(value) {
+  return nonEmptyString(value, "Parallel key field");
+}
+
+function inferFieldType(rows, field) {
+  const values = rows
+    .map(row => row[field])
+    .filter(value => value !== undefined && value !== null);
+  if (values.length === 0) {
+    throw new Error(`Cannot infer Parallel field type for "${field}".`);
+  }
+  if (values.every(Number.isFinite)) return "quantitative";
+  if (values.every(value => typeof value === "string")) return "ordinal";
+  throw new Error(
+    `Parallel dimension "${field}" requires an explicit compatible fieldType.`
+  );
+}
+
+function validateScaleOptions(value, index) {
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(`Parallel dimension ${index} scale must be a plain object.`);
+  }
+  validateOptionObject(
+    value,
+    DIMENSION_SCALE_OPTIONS,
+    `Parallel dimension ${index} scale`
+  );
+  return { ...value };
+}
+
+export function validateParallelMissingPolicy(value) {
+  if (!MISSING_POLICIES.has(value)) {
+    throw new Error(`Unsupported Parallel missing policy "${value}".`);
+  }
+  return value;
+}
+
+export function validateParallelDimensions(dimensions, { normalized = false } = {}) {
+  if (!Array.isArray(dimensions) || dimensions.length < 2) {
+    throw new RangeError("Parallel coordinates require at least two dimensions.");
+  }
+  const fields = new Set();
+  for (const [index, dimension] of dimensions.entries()) {
+    if (!isPlainObject(dimension)) {
+      throw new TypeError(`Parallel dimension ${index} must be an object.`);
+    }
+    const supported = normalized
+      ? ["field", "fieldType", "title", "scale"]
+      : DIMENSION_OPTIONS;
+    validateOptionObject(dimension, supported, `Parallel dimension ${index}`);
+    const field = nonEmptyString(
+      dimension.field,
+      `Parallel dimension ${index} field`
+    );
+    if (fields.has(field)) {
+      throw new Error("Parallel dimensions must use unique fields.");
+    }
+    fields.add(field);
+    validateSemanticFieldType(dimension.fieldType);
+    if (!FIELD_TYPES.has(dimension.fieldType)) {
+      throw new Error(`Unsupported Parallel field type "${dimension.fieldType}".`);
+    }
+    nonEmptyString(dimension.title, `Parallel dimension ${index} title`);
+    validateUserId(dimension.scale, `Parallel dimension ${index} scale id`);
+  }
+  return dimensions;
+}
+
+export function normalizeParallelDimensions(rows, dimensions, target) {
+  if (!Array.isArray(dimensions) || dimensions.length < 2) {
+    throw new RangeError("Parallel coordinates require at least two dimensions.");
+  }
+  const normalized = dimensions.map((input, index) => {
+    const dimension = typeof input === "string" ? { field: input } : input;
+    if (!isPlainObject(dimension)) {
+      throw new TypeError(
+        `Parallel dimension ${index} must be a field string or plain object.`
+      );
+    }
+    validateOptionObject(
+      dimension,
+      DIMENSION_OPTIONS,
+      `Parallel dimension ${index}`
+    );
+    const field = nonEmptyString(
+      dimension.field,
+      `Parallel dimension ${index} field`
+    );
+    const fieldType = dimension.fieldType ?? inferFieldType(rows, field);
+    if (!FIELD_TYPES.has(fieldType)) {
+      throw new Error(`Unsupported Parallel field type "${fieldType}".`);
+    }
+    const scale = validateScaleOptions(dimension.scale, index);
+    return {
+      field,
+      fieldType,
+      title: dimension.title ?? field,
+      scale: `${target}-parallel-${index}`,
+      scaleOptions: scale
+    };
+  });
+  const fields = normalized.map(dimension => dimension.field);
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("Parallel dimensions must use unique fields.");
+  }
+  return cloneAndFreeze(normalized);
+}
+
+function validDimensionValue(value, fieldType) {
+  return fieldType === "quantitative"
+    ? Number.isFinite(value)
+    : typeof value === "string" || Number.isFinite(value);
+}
+
+function commandsFromVertices(vertices) {
+  const commands = [];
+  let fragment = [];
+  const flush = () => {
+    if (fragment.length >= 2) {
+      fragment.forEach((point, index) => commands.push({
+        op: index === 0 ? "M" : "L",
+        x: point.x,
+        y: point.y
+      }));
+    }
+    fragment = [];
+  };
+  for (const vertex of vertices) {
+    if (vertex === undefined) flush();
+    else fragment.push(vertex);
+  }
+  flush();
+  return commands;
+}
+
+export function validateParallelRows(rows, dimensions, { key, missing }) {
+  const seen = new Set();
+  rows.forEach((row, index) => {
+    if (key !== undefined) {
+      const value = row[key];
+      if (value === undefined || value === null || value === "") {
+        throw new Error(`Parallel key is missing at row ${index}.`);
+      }
+      const token = `${typeof value}:${String(value)}`;
+      if (seen.has(token)) throw new Error(`Duplicate Parallel key "${value}".`);
+      seen.add(token);
+    }
+    const incomplete = dimensions.some(dimension =>
+      !validDimensionValue(row[dimension.field], dimension.fieldType)
+    );
+    if (incomplete && missing === "error") {
+      throw new Error(`Parallel row ${index} has a missing dimension.`);
+    }
+  });
+}
+
+export function materializeParallelRows(rows, dimensions, resolvedScales, bounds, {
+  key,
+  missing
+}) {
+  validateParallelRows(rows, dimensions, { key, missing });
+  const step = bounds.width / (dimensions.length - 1);
+  const items = [];
+  rows.forEach((row, sourceRowIndex) => {
+    const vertices = dimensions.map((dimension, index) => {
+      const value = row[dimension.field];
+      if (!validDimensionValue(value, dimension.fieldType)) return undefined;
+      const scale = resolvedScales[dimension.scale];
+      const mapped = dimension.fieldType === "quantitative"
+        ? mapContinuousScaleValues([value], scale)[0]
+        : mapOrdinalPositionValues([value], scale)[0];
+      return Number.isFinite(mapped)
+        ? { x: bounds.x + step * index, y: mapped, value, dimension: dimension.field }
+        : undefined;
+    });
+    const incomplete = vertices.some(vertex => vertex === undefined);
+    if (incomplete && missing === "drop-row") return;
+    items.push({
+      key: key === undefined ? `source:${sourceRowIndex}` : row[key],
+      sourceRowIndex,
+      commands: commandsFromVertices(vertices)
+    });
+  });
+  return cloneAndFreeze(items);
+}

package/src/grammar/pathOrder.js

@@ -0,0 +1,35 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+
+export const PATH_ORDER_DIRECTIONS = Object.freeze([
+  "ascending",
+  "descending"
+]);
+
+export function validatePathOrderDirection(value) {
+  if (!PATH_ORDER_DIRECTIONS.includes(value)) {
+    throw new Error(`Unsupported path order "${value}".`);
+  }
+  return value;
+}
+
+export function stableOrderPathValues(values, orderValues, order = "ascending") {
+  validatePathOrderDirection(order);
+  if (!Array.isArray(values) || !Array.isArray(orderValues)) {
+    throw new TypeError("Path ordering requires value and order arrays.");
+  }
+  if (values.length !== orderValues.length) {
+    throw new Error("Path value and order arrays must have equal length.");
+  }
+  const direction = order === "ascending" ? 1 : -1;
+  const ordered = values.map((value, sourceIndex) => {
+    const orderValue = orderValues[sourceIndex];
+    if (!Number.isFinite(orderValue)) {
+      throw new TypeError("Path order values must be finite numbers.");
+    }
+    return { value, orderValue, sourceIndex };
+  }).sort((left, right) =>
+    direction * (left.orderValue - right.orderValue) ||
+    left.sourceIndex - right.sourceIndex
+  );
+  return cloneAndFreeze(ordered.map(item => item.value));
+}

package/src/grammar/pointShapes.js

@@ -162,3 +162,27 @@ export function createPointShapeGraphic({
     }
   };
 }
+
+export function resolvePointShapeExtent({ shape, area, strokeWidth = 0 }) {
+  const validated = validatePointShape(shape);
+  if (!Number.isFinite(area) || area < 0) {
+    throw new TypeError("Point shape area must be finite and non-negative.");
+  }
+  if (!Number.isFinite(strokeWidth) || strokeWidth < 0) {
+    throw new TypeError("Point shape strokeWidth must be finite and non-negative.");
+  }
+  const strokeExtent = strokeWidth / 2;
+  if (validated === "circle") {
+    const radius = Math.sqrt(area / Math.PI) + strokeExtent;
+    return cloneAndFreeze({ x: radius, y: radius });
+  }
+  if (validated === "square") {
+    const halfSide = Math.sqrt(area) / 2 + strokeExtent;
+    return cloneAndFreeze({ x: halfSide, y: halfSide });
+  }
+  const points = normalizePolygon(shapePolygon(validated), 0, 0, area);
+  return cloneAndFreeze({
+    x: Math.max(0, ...points.map(point => Math.abs(point.x))) + strokeExtent,
+    y: Math.max(0, ...points.map(point => Math.abs(point.y))) + strokeExtent
+  });
+}

package/src/grammar/polarLineCommands.js

@@ -3,7 +3,7 @@ import { polarToCartesian } from "./polar.js";
 import {
   mapContinuousScaleValues,
   mapOrdinalPositionValues
-} from "./scales.js";
+} from "./scales/index.js";
 
 function mappedTheta(values, fieldType, scale) {
   return ["nominal", "ordinal"].includes(fieldType)

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