ggaction 0.0.3 → 0.0.5

package/src/grammar/regression/parameters.js

@@ -0,0 +1,106 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+
+export function requireRegressionField(field, label) {
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return field;
+}
+
+export function normalizeRegressionParameters({
+  method = "linear",
+  degree,
+  span,
+  confidence,
+  interval
+} = {}) {
+  if (!["linear", "polynomial", "loess"].includes(method)) {
+    throw new Error(`Unsupported regression method "${method}".`);
+  }
+  if (method === "loess") {
+    if (degree !== undefined) {
+      throw new Error("Regression degree requires the polynomial method.");
+    }
+    if (confidence !== undefined || interval !== undefined) {
+      throw new Error("LOESS regression does not support confidence intervals.");
+    }
+    const resolvedSpan = span ?? 0.75;
+    if (!Number.isFinite(resolvedSpan) || resolvedSpan <= 0 || resolvedSpan > 1) {
+      throw new RangeError(
+        "Regression LOESS span must be greater than zero and at most one."
+      );
+    }
+    return cloneAndFreeze({ method, span: resolvedSpan });
+  }
+  if (span !== undefined) {
+    throw new Error("Regression span requires the loess method.");
+  }
+  const resolvedConfidence = confidence ?? 0.95;
+  if (
+    !Number.isFinite(resolvedConfidence) ||
+    resolvedConfidence <= 0 ||
+    resolvedConfidence >= 1
+  ) {
+    throw new RangeError("Regression confidence must be between 0 and 1.");
+  }
+  const resolvedInterval = interval ?? "mean";
+  if (!["mean", "prediction"].includes(resolvedInterval)) {
+    throw new Error(`Unsupported regression interval "${resolvedInterval}".`);
+  }
+  if (method === "polynomial") {
+    const resolvedDegree = degree ?? 2;
+    if (!Number.isInteger(resolvedDegree) || resolvedDegree < 1) {
+      throw new RangeError(
+        "Regression polynomial degree must be a positive integer."
+      );
+    }
+    return cloneAndFreeze({
+      method,
+      degree: resolvedDegree,
+      confidence: resolvedConfidence,
+      interval: resolvedInterval
+    });
+  }
+  if (degree !== undefined) {
+    throw new Error("Regression degree requires the polynomial method.");
+  }
+  return cloneAndFreeze({
+    method,
+    confidence: resolvedConfidence,
+    interval: resolvedInterval
+  });
+}
+
+export function validateRegressionTransform(transform) {
+  const supported = [
+    "type", "method", "x", "y", "groupBy", "confidence", "interval",
+    "degree", "span"
+  ];
+  const unknown = Object.keys(transform).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown regression transform property "${unknown}".`);
+  }
+  if (transform.type !== "regression") {
+    throw new Error(`Unsupported regression transform "${transform.type}".`);
+  }
+  requireRegressionField(transform.x, "Regression x field");
+  requireRegressionField(transform.y, "Regression y field");
+  if (transform.groupBy !== undefined) {
+    requireRegressionField(transform.groupBy, "Regression groupBy field");
+  }
+  const normalized = normalizeRegressionParameters({
+    method: transform.method,
+    degree: transform.degree,
+    span: transform.span,
+    confidence: transform.confidence,
+    interval: transform.interval
+  });
+  if (normalized.method === "loess") return transform;
+  if (!Number.isFinite(transform.confidence)) {
+    throw new RangeError("Regression confidence must be between 0 and 1.");
+  }
+  if (transform.interval === undefined) {
+    throw new Error(`Unsupported regression interval "${transform.interval}".`);
+  }
+  return transform;
+}

package/src/grammar/rules.js

@@ -6,12 +6,13 @@ import {
   readQuantitativeField,
   readTemporalField,
   validateSemanticFieldType
-} from "./scales.js";
+} from "./scales/index.js";
 
 const ENDPOINT_CHANNELS = Object.freeze(["x", "y", "x2", "y2"]);
 const VALUE_CHANNELS = Object.freeze([
   ...ENDPOINT_CHANNELS,
   "strokeDash",
+  "strokeWidth",
   "opacity"
 ]);
 

package/src/grammar/scales/appearance.js

@@ -20,6 +20,7 @@ export const NAMED_DASH_PATTERNS = cloneAndFreeze({
 export { POINT_SHAPES } from "../pointShapes.js";
 export const DEFAULT_SIZE_RANGE = cloneAndFreeze([24, 196]);
 export const DEFAULT_OPACITY_RANGE = cloneAndFreeze([0.2, 1]);
+export const DEFAULT_STROKE_WIDTH_RANGE = cloneAndFreeze([1, 8]);
 
 export function validateColorRange(range) {
   if (range === "auto") return range;
@@ -123,6 +124,21 @@ export function validateOpacityRange(range) {
   return cloneAndFreeze(range);
 }
 
+export function validateStrokeWidthRange(range) {
+  if (range === "auto") return range;
+  if (
+    !Array.isArray(range) ||
+    range.length !== 2 ||
+    !range.every(value => Number.isFinite(value) && value >= 0) ||
+    range[0] > range[1]
+  ) {
+    throw new TypeError(
+      "StrokeWidth range must be an ascending pair of non-negative finite widths."
+    );
+  }
+  return cloneAndFreeze(range);
+}
+
 export function validateOpacityValue(value, label = "Opacity") {
   return validateUnitInterval(value, label);
 }
@@ -166,6 +182,11 @@ export function resolveOpacityRange(range) {
   return validated === "auto" ? DEFAULT_OPACITY_RANGE : validated;
 }
 
+export function resolveStrokeWidthRange(range) {
+  const validated = validateStrokeWidthRange(range);
+  return validated === "auto" ? DEFAULT_STROKE_WIDTH_RANGE : validated;
+}
+
 export function mapOrdinalValues(values, domain, range, options = {}) {
   const hasUnknown = Object.hasOwn(options, "unknown");
   const indices = new Map(domain.map((value, index) => [value, index]));

package/src/grammar/scales/color.js

@@ -277,8 +277,10 @@ export function validateSequentialColorRange(value) {
     throw new TypeError("Sequential color range requires colors or a palette descriptor.");
   }
   const palette = normalizePalette(value.palette);
-  if (palette.count !== undefined) {
-    throw new Error("Continuous palette does not accept count.");
+  if (palette.count !== undefined && palette.count < 2) {
+    throw new RangeError(
+      "Sequential palette count must be an integer of at least 2."
+    );
   }
   return cloneAndFreeze({ palette });
 }

package/src/grammar/schemas/concreteGraphic.js

@@ -1,5 +1,6 @@
 import { isPlainObject } from "../../core/immutable.js";
 import { validatePathCommands } from "../pathCommands.js";
+import { validateFillPaint } from "../paint.js";
 import { validateGraphicProperty } from "./graphic.js";
 
 const FINITE_PROPERTIES = new Set([
@@ -10,7 +11,7 @@ const NON_NEGATIVE_PROPERTIES = new Set([
   "width", "height", "radius", "strokeWidth", "fontSize", "gap"
 ]);
 const STRING_PROPERTIES = new Set([
-  "background", "fill", "stroke", "fontFamily", "text", "textAlign",
+  "background", "stroke", "fontFamily", "text", "textAlign",
   "textBaseline"
 ]);
 const TEXT_ALIGNS = new Set(["left", "right", "center", "start", "end"]);
@@ -19,6 +20,15 @@ const TEXT_BASELINES = new Set([
 ]);
 
 export function validateConcreteGraphicValue(type, property, value) {
+  if (property === "fill") {
+    if (typeof value === "string") {
+      validateFillPaint(value, `${type}.fill`);
+    } else if (type === "rect" || type === "path") {
+      validateFillPaint(value, `${type}.fill`);
+    } else {
+      throw new TypeError(`${type}.fill must be a non-empty string.`);
+    }
+  }
   if (FINITE_PROPERTIES.has(property) && !Number.isFinite(value)) {
     throw new TypeError(`${type}.${property} must be a finite number.`);
   }

package/src/grammar/schemas/graphicBounds.js

@@ -1,4 +1,4 @@
-import { measureTextWidth } from "../../core/textMetrics.js";
+import { resolveTextBounds } from "../../core/textMetrics.js";
 import { findGraphic, requireGraphic } from "./graphicTree.js";
 
 function unionBounds(bounds) {
@@ -74,6 +74,17 @@ function pathPoints(commands) {
   return points;
 }
 
+export function resolvePathCommandBounds(commands) {
+  const points = pathPoints(commands);
+  if (points.length === 0) return undefined;
+  return {
+    left: Math.min(...points.map(point => point.x)),
+    right: Math.max(...points.map(point => point.x)),
+    top: Math.min(...points.map(point => point.y)),
+    bottom: Math.max(...points.map(point => point.y))
+  };
+}
+
 function primitiveBounds(type, properties = {}) {
   const strokeExtent = (properties.strokeWidth ?? 0) / 2;
   if (type === "circle") {
@@ -115,47 +126,18 @@ function primitiveBounds(type, properties = {}) {
       !Number.isFinite(properties.fontSize) ||
       typeof properties.text !== "string"
     ) return undefined;
-    const width = measureTextWidth(properties.text, properties);
-    const align = properties.textAlign ?? "left";
-    const left = align === "center" ? -width / 2 :
-      ["right", "end"].includes(align) ? -width : 0;
-    const baseline = properties.textBaseline ?? "alphabetic";
-    const [top, bottom] = baseline === "middle"
-      ? [-properties.fontSize / 2, properties.fontSize / 2]
-      : ["top", "hanging"].includes(baseline)
-        ? [0, properties.fontSize]
-        : ["bottom", "ideographic"].includes(baseline)
-          ? [-properties.fontSize, 0]
-          : [-properties.fontSize * 0.8, properties.fontSize * 0.2];
-    const rotation = properties.rotation ?? 0;
-    const cosine = Math.cos(rotation);
-    const sine = Math.sin(rotation);
-    const corners = [
-      [left, top],
-      [left + width, top],
-      [left + width, bottom],
-      [left, bottom]
-    ].map(([x, y]) => ({
-      x: properties.x + x * cosine - y * sine,
-      y: properties.y + x * sine + y * cosine
-    }));
-    return {
-      left: Math.min(...corners.map(point => point.x)),
-      right: Math.max(...corners.map(point => point.x)),
-      top: Math.min(...corners.map(point => point.y)),
-      bottom: Math.max(...corners.map(point => point.y))
-    };
+    return resolveTextBounds(properties);
   }
   if (type === "path") {
     const commands = properties.commands;
     if (!Array.isArray(commands)) return undefined;
-    const points = pathPoints(commands);
-    if (points.length === 0) return undefined;
+    const bounds = resolvePathCommandBounds(commands);
+    if (bounds === undefined) return undefined;
     return {
-      left: Math.min(...points.map(point => point.x)) - strokeExtent,
-      right: Math.max(...points.map(point => point.x)) + strokeExtent,
-      top: Math.min(...points.map(point => point.y)) - strokeExtent,
-      bottom: Math.max(...points.map(point => point.y)) + strokeExtent
+      left: bounds.left - strokeExtent,
+      right: bounds.right + strokeExtent,
+      top: bounds.top - strokeExtent,
+      bottom: bounds.bottom + strokeExtent
     };
   }
   return undefined;

package/src/grammar/schemas/semanticPath.js

@@ -6,7 +6,7 @@ import {
 } from "../../core/vocabulary.js";
 
 const ENCODING_PATHS = Object.freeze([
-  ...ENCODING_CHANNELS.flatMap(channel => [
+  ...ENCODING_CHANNELS.filter(channel => channel !== "pathOrder").flatMap(channel => [
     `encoding.${channel}.field`,
     `encoding.${channel}.datum`,
     `encoding.${channel}.fieldType`,
@@ -20,8 +20,15 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.x.bin.boundaries",
   "encoding.color.layout",
   "encoding.color.aggregate",
+  "encoding.pathOrder.field",
+  "encoding.pathOrder.fieldType",
+  "encoding.pathOrder.order",
   "encoding.theta.aggregate",
+  "encoding.theta.weight",
   "encoding.text.format",
+  "encoding.parallel.dimensions",
+  "encoding.parallel.key",
+  "encoding.parallel.missing",
   ...CARTESIAN_POSITION_CHANNELS.flatMap(channel => [
     `encoding.${channel}.aggregate`,
     `encoding.${channel}.stack`
@@ -36,7 +43,8 @@ const ENTITY_PATHS = Object.freeze({
   layer: {
     collection: "layers",
     removableContainers: new Set(
-      ENCODING_CHANNELS.map(channel => `encoding.${channel}`)
+      [...ENCODING_CHANNELS.map(channel => `encoding.${channel}`),
+        "encoding.parallel"]
     ),
     properties: new Set([
       "data",
@@ -74,10 +82,15 @@ const GUIDE_PATHS = new Set([
   "axis.radius.scale",
   "axis.radius.coordinate",
   "axis.radius.title",
+  "axis.parallel.target",
+  "axis.parallel.coordinate",
+  "axis.parallel.scales",
   "legend.color.scale",
   "legend.color.title",
   "legend.size.scale",
   "legend.size.title",
+  "legend.strokeWidth.scale",
+  "legend.strokeWidth.title",
   "legend.opacity.scale",
   "legend.opacity.title",
   "legend.series.channels",
@@ -98,12 +111,14 @@ const GUIDE_REMOVABLE_CONTAINERS = new Set([
   "axis.y",
   "axis.theta",
   "axis.radius",
+  "axis.parallel",
   "grid.horizontal",
   "grid.vertical",
   "grid.theta",
   "grid.radial",
   "legend.color",
   "legend.size",
+  "legend.strokeWidth",
   "legend.opacity",
   "legend.series"
 ]);

package/src/grammar/statistics/studentT.js

@@ -0,0 +1,98 @@
+const LANCZOS = Object.freeze([
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9.984369578019572e-6,
+  1.5056327351493116e-7
+]);
+
+function logGamma(value) {
+  if (value < 0.5) {
+    return Math.log(Math.PI) - Math.log(Math.sin(Math.PI * value)) -
+      logGamma(1 - value);
+  }
+  const shifted = value - 1;
+  let sum = 0.9999999999998099;
+  for (const [index, coefficient] of LANCZOS.entries()) {
+    sum += coefficient / (shifted + index + 1);
+  }
+  const base = shifted + LANCZOS.length - 0.5;
+  return 0.5 * Math.log(2 * Math.PI) +
+    (shifted + 0.5) * Math.log(base) - base + Math.log(sum);
+}
+
+function betaContinuedFraction(a, b, value) {
+  const maximumIterations = 200;
+  const epsilon = 3e-14;
+  const floor = 1e-300;
+  const sum = a + b;
+  let c = 1;
+  let d = 1 - sum * value / (a + 1);
+  if (Math.abs(d) < floor) d = floor;
+  d = 1 / d;
+  let result = d;
+
+  for (let iteration = 1; iteration <= maximumIterations; iteration += 1) {
+    const even = 2 * iteration;
+    let coefficient = iteration * (b - iteration) * value /
+      ((a + even - 1) * (a + even));
+    d = 1 + coefficient * d;
+    if (Math.abs(d) < floor) d = floor;
+    c = 1 + coefficient / c;
+    if (Math.abs(c) < floor) c = floor;
+    d = 1 / d;
+    result *= d * c;
+
+    coefficient = -(a + iteration) * (sum + iteration) * value /
+      ((a + even) * (a + even + 1));
+    d = 1 + coefficient * d;
+    if (Math.abs(d) < floor) d = floor;
+    c = 1 + coefficient / c;
+    if (Math.abs(c) < floor) c = floor;
+    d = 1 / d;
+    const delta = d * c;
+    result *= delta;
+    if (Math.abs(delta - 1) <= epsilon) return result;
+  }
+  throw new Error("Student-t calculation did not converge.");
+}
+
+function regularizedIncompleteBeta(value, a, b) {
+  if (value === 0 || value === 1) return value;
+  const factor = Math.exp(
+    logGamma(a + b) - logGamma(a) - logGamma(b) +
+    a * Math.log(value) + b * Math.log1p(-value)
+  );
+  if (value < (a + 1) / (a + b + 2)) {
+    return factor * betaContinuedFraction(a, b, value) / a;
+  }
+  return 1 - factor * betaContinuedFraction(b, a, 1 - value) / b;
+}
+
+function studentTCdf(value, degreesOfFreedom) {
+  if (value === 0) return 0.5;
+  const ratio = degreesOfFreedom /
+    (degreesOfFreedom + value * value);
+  const tail = regularizedIncompleteBeta(
+    ratio,
+    degreesOfFreedom / 2,
+    0.5
+  ) / 2;
+  return value > 0 ? 1 - tail : tail;
+}
+
+export function studentTCriticalValue(level, degreesOfFreedom) {
+  const probability = (1 + level) / 2;
+  let low = 0;
+  let high = 1;
+  while (studentTCdf(high, degreesOfFreedom) < probability) high *= 2;
+  for (let iteration = 0; iteration < 100; iteration += 1) {
+    const midpoint = (low + high) / 2;
+    if (studentTCdf(midpoint, degreesOfFreedom) < probability) low = midpoint;
+    else high = midpoint;
+  }
+  return (low + high) / 2;
+}

package/src/grammar/transforms.js

@@ -1,29 +1,118 @@
 import { isPlainObject } from "../core/immutable.js";
 import { validateBoxTransform } from "./boxPlot.js";
+import {
+  requestedBin2DTransform,
+  validateBin2DTransform
+} from "./bin2d.js";
 import { validateDensityTransform } from "./density.js";
 import { validateFilterTransform } from "./filter.js";
+import {
+  requestedGradientProfileTransform,
+  validateGradientProfileTransform
+} from "./gradientProfile.js";
 import { validateIntervalTransform } from "./interval.js";
+import {
+  requestedHorizonTransform,
+  validateHorizonTransform
+} from "./horizon.js";
 import { validateMarkFilterTransform } from "./markFilter.js";
-import { validateRegressionTransform } from "./regression.js";
+import { validateRegressionTransform } from "./regression/index.js";
+import { validateWindowTransform } from "./window.js";
 
-const TRANSFORM_VALIDATORS = Object.freeze({
-  boxOutlier: validateBoxTransform,
-  boxSummary: validateBoxTransform,
-  density: validateDensityTransform,
-  filter: validateFilterTransform,
-  interval: validateIntervalTransform,
-  markFilter: validateMarkFilterTransform,
-  regression: validateRegressionTransform
+function requestedDensityTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  return requested;
+}
+
+function facetHorizonTransform(transform, { scales = {} } = {}) {
+  if (
+    transform.extent !== "auto" ||
+    (scales.y ?? "shared") !== "shared" ||
+    !Array.isArray(transform.resolved?.extents)
+  ) return transform;
+  const extent = Math.max(...transform.resolved.extents.map(item => item.extent));
+  if (!(extent > 0)) return transform;
+  return {
+    ...requestedHorizonTransform(transform),
+    extent
+  };
+}
+
+const TRANSFORM_POLICIES = Object.freeze({
+  bin2d: Object.freeze({
+    validate: validateBin2DTransform,
+    materializeOp: "materializeBin2DData",
+    facetTopology: "statistical",
+    replayTransform: requestedBin2DTransform
+  }),
+  boxOutlier: Object.freeze({
+    validate: validateBoxTransform,
+    materializeOp: "materializeBoxOutlierData",
+    facetTopology: "statistical"
+  }),
+  boxSummary: Object.freeze({
+    validate: validateBoxTransform,
+    materializeOp: "materializeBoxSummaryData",
+    facetTopology: "statistical"
+  }),
+  density: Object.freeze({
+    validate: validateDensityTransform,
+    materializeOp: "materializeDensityData",
+    facetTopology: "statistical",
+    replayTransform: requestedDensityTransform
+  }),
+  filter: Object.freeze({
+    validate: validateFilterTransform,
+    materializeOp: "materializeFilteredData",
+    facetTopology: "rowPreserving"
+  }),
+  gradientProfile: Object.freeze({
+    validate: validateGradientProfileTransform,
+    materializeOp: "materializeGradientProfileData",
+    facetTopology: "statistical",
+    replayTransform: requestedGradientProfileTransform
+  }),
+  horizon: Object.freeze({
+    validate: validateHorizonTransform,
+    materializeOp: "materializeHorizonData",
+    facetTopology: "statistical",
+    replayTransform: requestedHorizonTransform,
+    facetReplayTransform: facetHorizonTransform
+  }),
+  interval: Object.freeze({
+    validate: validateIntervalTransform,
+    materializeOp: "materializeIntervalData",
+    facetTopology: "statistical"
+  }),
+  markFilter: Object.freeze({
+    validate: validateMarkFilterTransform,
+    materializeOp: "materializeMarkFilteredData",
+    provenanceTransparent: true
+  }),
+  regression: Object.freeze({
+    validate: validateRegressionTransform,
+    materializeOp: "materializeRegressionData",
+    facetTopology: "statistical"
+  }),
+  window: Object.freeze({
+    validate: validateWindowTransform,
+    materializeOp: "materializeWindowData",
+    facetTopology: "statistical"
+  })
 });
 
+export function findTransformPolicy(type) {
+  return TRANSFORM_POLICIES[type];
+}
+
 export function findTransformValidator(type) {
-  return TRANSFORM_VALIDATORS[type];
+  return findTransformPolicy(type)?.validate;
 }
 
 export function validateDatasetTransforms(value) {
-  if (!Array.isArray(value) || value.length === 0 || !value.every(isPlainObject)) {
+  if (!Array.isArray(value) || value.length !== 1 || !isPlainObject(value[0])) {
     throw new TypeError(
-      "Dataset transform must be a non-empty array of plain objects."
+      "Dataset transform must contain exactly one plain object."
     );
   }
   for (const transform of value) {