ggaction 0.0.2 → 0.0.4

package/src/grammar/interval.js

@@ -1,5 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
+import { studentTCriticalValue } from "./statistics/studentT.js";
 
 const CENTER_VALUES = Object.freeze(["mean", "median"]);
 const EXTENT_VALUES = Object.freeze(["stderr", "stdev", "ci", "iqr"]);
@@ -133,92 +134,6 @@ export function normalizeIntervalParameters({
   });
 }
 
-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 t = shifted + LANCZOS.length - 0.5;
-  return 0.5 * Math.log(2 * Math.PI) +
-    (shifted + 0.5) * Math.log(t) - t + Math.log(sum);
-}
-
-function betaFraction(a, b, x) {
-  const maximumIterations = 200;
-  const epsilon = 3e-14;
-  const floor = 1e-300;
-  const sum = a + b;
-  let c = 1;
-  let d = 1 - sum * x / (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) * x /
-      ((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) * x /
-      ((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 regularizedBeta(x, a, b) {
-  if (x <= 0) return 0;
-  if (x >= 1) return 1;
-  const front = Math.exp(
-    logGamma(a + b) - logGamma(a) - logGamma(b) +
-    a * Math.log(x) + b * Math.log1p(-x)
-  );
-  return x < (a + 1) / (a + b + 2)
-    ? front * betaFraction(a, b, x) / a
-    : 1 - front * betaFraction(b, a, 1 - x) / b;
-}
-
-function studentTCdf(value, degreesOfFreedom) {
-  if (value === 0) return 0.5;
-  const x = degreesOfFreedom /
-    (degreesOfFreedom + value * value);
-  const tail = 0.5 * regularizedBeta(
-    x,
-    degreesOfFreedom / 2,
-    0.5
-  );
-  return value > 0 ? 1 - tail : tail;
-}
-
 export function studentTCritical(degreesOfFreedom, level) {
   if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
     throw new RangeError("Student-t degreesOfFreedom must be a positive integer.");
@@ -226,16 +141,7 @@ export function studentTCritical(degreesOfFreedom, level) {
   if (!Number.isFinite(level) || level <= 0 || level >= 1) {
     throw new RangeError("Student-t level must be between 0 and 1.");
   }
-  const target = 0.5 + level / 2;
-  let low = 0;
-  let high = 1;
-  while (studentTCdf(high, degreesOfFreedom) < target) high *= 2;
-  for (let iteration = 0; iteration < 100; iteration += 1) {
-    const midpoint = (low + high) / 2;
-    if (studentTCdf(midpoint, degreesOfFreedom) < target) low = midpoint;
-    else high = midpoint;
-  }
-  return (low + high) / 2;
+  return studentTCriticalValue(level, degreesOfFreedom);
 }
 
 function isMissing(value) {

package/src/grammar/lineSeries.js

@@ -3,7 +3,7 @@ import {
   readNominalField,
   readQuantitativeField,
   readTemporalField
-} from "./scales.js";
+} from "./scales/index.js";
 import {
   aggregateRows,
   isAggregate,
@@ -64,8 +64,13 @@ function readSeriesFields(rows, layer) {
     const encoding = layer.encoding?.[channel];
 
     if (encoding?.field === undefined) continue;
-    if (encoding.fieldType !== "nominal") {
-      throw new Error(`Line ${channel} encoding on mark "${layer.id}" must be nominal.`);
+    const categorical = channel === "color"
+      ? ["nominal", "ordinal"].includes(encoding.fieldType)
+      : encoding.fieldType === "nominal";
+    if (!categorical) {
+      throw new Error(
+        `Line ${channel} encoding on mark "${layer.id}" must be categorical.`
+      );
     }
 
     if (!values.has(encoding.field)) {
@@ -81,7 +86,7 @@ function groupKey(values) {
   return JSON.stringify(values);
 }
 
-export function deriveLineSeries(rows, layer) {
+function deriveCartesianLineSeries(rows, layer) {
   const { x, y, isAggregate, directTemporal } = requireLineEncoding(layer);
   if (isAggregate) {
     validateAggregateFieldValues(rows, y.field, y.fieldType);
@@ -195,3 +200,106 @@ export function deriveLineSeries(rows, layer) {
     series
   });
 }
+
+function requirePolarLineEncoding(layer) {
+  if (layer?.mark?.type !== "line") {
+    throw new Error("Polar line series derivation requires a semantic line mark.");
+  }
+  const theta = layer.encoding?.theta;
+  const radius = layer.encoding?.radius;
+  if (theta === undefined || radius === undefined) {
+    throw new Error(
+      `Polar line mark "${layer.id}" requires theta and radius encodings.`
+    );
+  }
+  if (!["quantitative", "temporal", "ordinal", "nominal"].includes(
+    theta.fieldType
+  )) {
+    throw new Error(
+      `Polar line mark "${layer.id}" has unsupported theta field type.`
+    );
+  }
+  if (radius.fieldType !== "quantitative") {
+    throw new Error(
+      `Polar line mark "${layer.id}" requires a quantitative radius encoding.`
+    );
+  }
+  return { theta, radius };
+}
+
+function readThetaValues(rows, encoding) {
+  if (["nominal", "ordinal"].includes(encoding.fieldType)) {
+    return readNominalField(rows, encoding.field);
+  }
+  return encoding.fieldType === "temporal"
+    ? readTemporalField(rows, encoding.field)
+    : readQuantitativeField(rows, encoding.field);
+}
+
+function thetaOrder(values, fieldType, domain) {
+  if (!["nominal", "ordinal"].includes(fieldType)) return values;
+  const order = domain ?? [...new Set(values)];
+  const indices = new Map(order.map((value, index) => [value, index]));
+  for (const value of values) {
+    if (!indices.has(value)) {
+      throw new Error(`Polar line theta domain does not contain "${value}".`);
+    }
+  }
+  return values.map(value => indices.get(value));
+}
+
+export function derivePolarLineSeries(rows, layer, { thetaDomain } = {}) {
+  const { theta, radius } = requirePolarLineEncoding(layer);
+  const thetaValues = readThetaValues(rows, theta);
+  const radiusValues = readQuantitativeField(rows, radius.field);
+  const sortValues = thetaOrder(thetaValues, theta.fieldType, thetaDomain);
+  const seriesFields = readSeriesFields(rows, layer);
+  const groups = new Map();
+
+  for (let index = 0; index < rows.length; index += 1) {
+    const dimensions = seriesFields.fields.map(
+      field => seriesFields.values.get(field)[index]
+    );
+    const key = groupKey(dimensions);
+    const series = groups.get(key) ?? {
+      key: Object.fromEntries(
+        seriesFields.fields.map((field, item) => [field, dimensions[item]])
+      ),
+      values: []
+    };
+    series.values.push({
+      theta: thetaValues[index],
+      radius: radiusValues[index],
+      order: sortValues[index],
+      sourceIndex: index
+    });
+    groups.set(key, series);
+  }
+
+  const series = [...groups.values()].flatMap(item => {
+    const values = item.values.sort(
+      (left, right) => left.order - right.order ||
+        left.sourceIndex - right.sourceIndex
+    );
+    return values.length < 2 ? [] : [{ key: item.key, values }];
+  });
+  if (series.length === 0) {
+    throw new Error(
+      `Polar line series on mark "${layer.id}" requires at least two points.`
+    );
+  }
+  return cloneAndFreeze({
+    thetaFieldType: theta.fieldType,
+    thetaValues: series.flatMap(item => item.values.map(value => value.theta)),
+    radiusValues: series.flatMap(item => item.values.map(value => value.radius)),
+    series
+  });
+}
+
+export function deriveLineSeries(rows, layer, options) {
+  const polar = layer?.encoding?.theta !== undefined ||
+    layer?.encoding?.radius !== undefined;
+  return polar
+    ? derivePolarLineSeries(rows, layer, options)
+    : deriveCartesianLineSeries(rows, layer);
+}

package/src/grammar/palettes.js

@@ -190,16 +190,14 @@ export function resolvePalette(value, domainCount) {
 }
 
 export function resolveContinuousPalette(value, count = 31) {
-  if (!Number.isInteger(count) || count < 2) {
-    throw new RangeError("Continuous palette count must be an integer of at least 2.");
-  }
   const palette = normalizePalette(value);
-  if (palette.count !== undefined) {
-    throw new Error("Continuous palette does not accept count.");
+  const resolvedCount = palette.count ?? count;
+  if (!Number.isInteger(resolvedCount) || resolvedCount < 2) {
+    throw new RangeError("Continuous palette count must be an integer of at least 2.");
   }
   const discrete = DISCRETE[palette.name];
-  if (discrete !== undefined) return discrete;
-  return resolvePalette({ ...palette, count }, count);
+  if (discrete !== undefined && palette.count === undefined) return discrete;
+  return resolvePalette({ ...palette, count: resolvedCount }, resolvedCount);
 }
 
 export function paletteFamily(name) {

package/src/grammar/polar.js

@@ -0,0 +1,102 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validatePair } from "./scales/validation.js";
+
+function validateBounds(bounds) {
+  if (
+    !isPlainObject(bounds) ||
+    ![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite) ||
+    bounds.width < 0 ||
+    bounds.height < 0
+  ) {
+    throw new TypeError(
+      "Polar geometry requires finite, non-negative graphical bounds."
+    );
+  }
+  return bounds;
+}
+
+export function resolvePolarFrame(bounds) {
+  validateBounds(bounds);
+  return cloneAndFreeze({
+    centerX: bounds.x + bounds.width / 2,
+    centerY: bounds.y + bounds.height / 2,
+    availableRadius: Math.min(bounds.width, bounds.height) / 2
+  });
+}
+
+export function validateThetaRange(range) {
+  if (range === "auto") return range;
+  const validated = validatePair(range, "Theta scale range");
+  if (Math.abs(validated[1] - validated[0]) > 360) {
+    throw new RangeError("Theta scale range span must not exceed 360 degrees.");
+  }
+  return validated;
+}
+
+export function validateRadialRange(range, availableRadius) {
+  if (range === "auto") return range;
+  const validated = validatePair(range, "Radius scale range");
+  if (validated.some(value => value < 0)) {
+    throw new RangeError("Radius scale range values must be non-negative.");
+  }
+  if (
+    availableRadius !== undefined &&
+    validated.some(value => value > availableRadius)
+  ) {
+    throw new RangeError(
+      `Radius scale range must fit within the available radius ${availableRadius}.`
+    );
+  }
+  return validated;
+}
+
+export function resolvePolarScaleRange(range, channel, bounds) {
+  if (channel === "theta") {
+    return range === "auto"
+      ? cloneAndFreeze([0, 360])
+      : validateThetaRange(range);
+  }
+  if (channel !== "radius") {
+    throw new Error(`Unknown Polar position channel "${channel}".`);
+  }
+  const frame = resolvePolarFrame(bounds);
+  return range === "auto"
+    ? cloneAndFreeze([0, frame.availableRadius])
+    : validateRadialRange(range, frame.availableRadius);
+}
+
+export function polarDirection(theta) {
+  if (!Number.isFinite(theta)) {
+    throw new TypeError("Polar theta must be a finite number of degrees.");
+  }
+  const angle = theta * Math.PI / 180;
+  return cloneAndFreeze({
+    x: Math.sin(angle),
+    y: -Math.cos(angle)
+  });
+}
+
+export function polarToCartesian({ theta, radius, frame }) {
+  const direction = polarDirection(theta);
+  if (!Number.isFinite(radius) || radius < 0) {
+    throw new TypeError("Polar radius must be a non-negative finite number.");
+  }
+  const resolvedFrame = frame?.availableRadius === undefined
+    ? resolvePolarFrame(frame)
+    : frame;
+  if (
+    ![resolvedFrame.centerX, resolvedFrame.centerY,
+      resolvedFrame.availableRadius].every(Number.isFinite)
+  ) {
+    throw new TypeError("Polar frame must contain finite geometry.");
+  }
+  if (radius > resolvedFrame.availableRadius) {
+    throw new RangeError(
+      `Polar radius ${radius} exceeds the available radius ${resolvedFrame.availableRadius}.`
+    );
+  }
+  return cloneAndFreeze({
+    x: resolvedFrame.centerX + radius * direction.x,
+    y: resolvedFrame.centerY + radius * direction.y
+  });
+}

package/src/grammar/polarGuides.js

@@ -0,0 +1,243 @@
+import { freezeOwned } from "../core/immutable.js";
+import { polarDirection } from "./polar.js";
+import { buildPolarCircleCommands } from "./polarPaths.js";
+
+export { buildPolarCircleCommands } from "./polarPaths.js";
+
+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 guide frame requires finite centerX, centerY, and non-negative availableRadius."
+    );
+  }
+  return frame;
+}
+
+function validateFiniteValues(values, label) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError(`${label} must be an array of finite numbers.`);
+  }
+  return values;
+}
+
+function validateNonNegative(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+function own(value) {
+  return freezeOwned(value);
+}
+
+function pointAt(frame, theta, radius) {
+  validateNonNegative(radius, "Polar guide radius");
+  const direction = polarDirection(theta);
+  return {
+    x: frame.centerX + direction.x * radius,
+    y: frame.centerY + direction.y * radius
+  };
+}
+
+export function resolveThetaSpokes({ frame, angles }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Polar spoke angles");
+  const end = angles.map(theta => pointAt(frame, theta, frame.availableRadius));
+  return own({
+    x1: angles.map(() => frame.centerX),
+    y1: angles.map(() => frame.centerY),
+    x2: end.map(point => point.x),
+    y2: end.map(point => point.y)
+  });
+}
+
+export function resolveRadialCircles({ frame, radii }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Polar grid radii");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Polar grid radii must be inside the Polar frame.");
+  }
+  const visibleRadii = radii.filter(radius => radius > 0);
+  return own({
+    radii: visibleRadii,
+    commands: visibleRadii.map(radius => buildPolarCircleCommands(frame, radius))
+  });
+}
+
+export function resolveThetaAxisTicks({ frame, angles, length }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Theta-axis angles");
+  validateNonNegative(length, "Theta-axis tick length");
+  const start = angles.map(theta => pointAt(frame, theta, frame.availableRadius));
+  const end = angles.map(theta => pointAt(
+    frame,
+    theta,
+    frame.availableRadius + length
+  ));
+  return own({
+    x1: start.map(point => point.x),
+    y1: start.map(point => point.y),
+    x2: end.map(point => point.x),
+    y2: end.map(point => point.y)
+  });
+}
+
+function perimeterAlignment(theta) {
+  const radians = theta * Math.PI / 180;
+  const horizontal = Math.sin(radians);
+  const vertical = Math.cos(radians);
+  return {
+    textAlign: horizontal > 0.25
+      ? "left"
+      : horizontal < -0.25
+        ? "right"
+        : "center",
+    textBaseline: vertical > 0.25
+      ? "bottom"
+      : vertical < -0.25
+        ? "top"
+        : "middle"
+  };
+}
+
+export function resolveThetaAxisLabels({ frame, angles, offset }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Theta-axis label angles");
+  validateNonNegative(offset, "Theta-axis label offset");
+  const points = angles.map(theta => pointAt(
+    frame,
+    theta,
+    frame.availableRadius + offset
+  ));
+  const alignment = angles.map(perimeterAlignment);
+  return own({
+    x: points.map(point => point.x),
+    y: points.map(point => point.y),
+    textAlign: alignment.map(value => value.textAlign),
+    textBaseline: alignment.map(value => value.textBaseline)
+  });
+}
+
+function radialVectors(angle) {
+  let direction;
+  try {
+    direction = polarDirection(angle);
+  } catch {
+    throw new TypeError("Radial-axis angle must be finite degrees.");
+  }
+  return {
+    direction,
+    normal: { x: -direction.y, y: direction.x }
+  };
+}
+
+export function resolveRadialAxisLine({ frame, angle, startRadius = 0 }) {
+  validateFrame(frame);
+  validateNonNegative(startRadius, "Radial-axis start radius");
+  if (startRadius > frame.availableRadius) {
+    throw new RangeError("Radial-axis start radius must be inside the Polar frame.");
+  }
+  const { direction } = radialVectors(angle);
+  return own({
+    x1: frame.centerX + direction.x * startRadius,
+    y1: frame.centerY + direction.y * startRadius,
+    x2: frame.centerX + direction.x * frame.availableRadius,
+    y2: frame.centerY + direction.y * frame.availableRadius
+  });
+}
+
+export function resolveRadialAxisTicks({ frame, angle, radii, length }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Radial-axis tick radii");
+  validateNonNegative(length, "Radial-axis tick length");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Radial-axis tick radii must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  const half = length / 2;
+  const centers = radii.map(radius => ({
+    x: frame.centerX + direction.x * radius,
+    y: frame.centerY + direction.y * radius
+  }));
+  return own({
+    x1: centers.map(point => point.x - normal.x * half),
+    y1: centers.map(point => point.y - normal.y * half),
+    x2: centers.map(point => point.x + normal.x * half),
+    y2: centers.map(point => point.y + normal.y * half)
+  });
+}
+
+export function resolveRadialAxisLabels({ frame, angle, radii, offset }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Radial-axis label radii");
+  validateNonNegative(offset, "Radial-axis label offset");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Radial-axis label radii must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  return own({
+    x: radii.map(radius =>
+      frame.centerX + direction.x * radius - normal.x * offset
+    ),
+    y: radii.map(radius =>
+      frame.centerY + direction.y * radius - normal.y * offset
+    ),
+    textAlign: radii.map(() => "center"),
+    textBaseline: radii.map(() => "bottom")
+  });
+}
+
+export function resolveRadialAxisTitle({
+  frame,
+  angle,
+  radius = frame.availableRadius / 2,
+  offset,
+  position = "inside"
+}) {
+  validateFrame(frame);
+  validateNonNegative(offset, "Radial-axis title offset");
+  if (!["inside", "outside"].includes(position)) {
+    throw new Error(`Unknown radial-axis title position "${position}".`);
+  }
+  if (position === "outside") {
+    const { direction } = radialVectors(angle);
+    return own({
+      x: frame.centerX + direction.x * (frame.availableRadius + offset),
+      y: frame.centerY + direction.y * (frame.availableRadius + offset),
+      textAlign: direction.x > 0.25
+        ? "left"
+        : direction.x < -0.25 ? "right" : "center",
+      textBaseline: direction.y > 0.25
+        ? "top"
+        : direction.y < -0.25 ? "bottom" : "middle"
+    });
+  }
+  validateNonNegative(radius, "Radial-axis title radius");
+  if (radius > frame.availableRadius) {
+    throw new RangeError("Radial-axis title radius must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  return own({
+    x: frame.centerX + direction.x * radius + normal.x * offset,
+    y: frame.centerY + direction.y * radius + normal.y * offset,
+    textAlign: "center",
+    textBaseline: "top"
+  });
+}
+
+export function resolveThetaAxisTitle({ frame, offset }) {
+  validateFrame(frame);
+  validateNonNegative(offset, "Theta-axis title offset");
+  return own({
+    x: frame.centerX,
+    y: frame.centerY + frame.availableRadius + offset,
+    textAlign: "center",
+    textBaseline: "middle"
+  });
+}

package/src/grammar/polarLineCommands.js

@@ -0,0 +1,43 @@
+import { buildLinearPathCommands } from "./pathCommands.js";
+import { polarToCartesian } from "./polar.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "./scales/index.js";
+
+function mappedTheta(values, fieldType, scale) {
+  return ["nominal", "ordinal"].includes(fieldType)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+}
+
+export function buildPolarLinePathCommands({
+  series,
+  thetaFieldType,
+  thetaScale,
+  radiusScale,
+  frame,
+  closed = false
+}) {
+  if (!Array.isArray(series) || series.length < 2) {
+    throw new TypeError("Polar line commands require at least two series values.");
+  }
+  if (typeof closed !== "boolean") {
+    throw new TypeError("Polar line closed must be a boolean.");
+  }
+  const theta = mappedTheta(
+    series.map(value => value.theta),
+    thetaFieldType,
+    thetaScale
+  );
+  const radius = mapContinuousScaleValues(
+    series.map(value => value.radius),
+    radiusScale
+  );
+  const points = series.map((_, index) => polarToCartesian({
+    theta: theta[index],
+    radius: radius[index],
+    frame
+  }));
+  return buildLinearPathCommands(points, { close: closed });
+}