ggaction 0.0.13 → 0.0.15

package/src/grammar/schemas/graphicBounds.js

@@ -3,6 +3,7 @@ import {
   resolveTextBounds
 } from "../../core/textMetrics.js";
 import { interpolateNumber } from "../numeric.js";
+import { resolveStrokeDetails } from "../strokeStyle.js";
 import {
   findGraphic,
   findGraphicParent,
@@ -174,15 +175,101 @@ function endpointDirection(start, command, end, reverse = false) {
   return undefined;
 }
 
-function includeMiter(bounds, point, incoming, outgoing, strokeExtent) {
+function includeCircle(bounds, point, radius) {
+  return includeExtent(
+    bounds,
+    point.x - radius,
+    point.x + radius,
+    point.y - radius,
+    point.y + radius
+  );
+}
+
+function includeEndpointCap(
+  bounds,
+  point,
+  direction,
+  strokeExtent,
+  lineCap,
+  atStart
+) {
+  if (lineCap === "butt" || direction === undefined) return bounds;
+  if (lineCap === "round") {
+    return includeCircle(bounds, point, strokeExtent);
+  }
+  const sign = atStart ? -1 : 1;
+  const center = {
+    x: point.x + direction.x * strokeExtent * sign,
+    y: point.y + direction.y * strokeExtent * sign
+  };
+  const normal = { x: -direction.y, y: direction.x };
+  return includeExtent(
+    bounds,
+    center.x - Math.abs(normal.x) * strokeExtent,
+    center.x + Math.abs(normal.x) * strokeExtent,
+    center.y - Math.abs(normal.y) * strokeExtent,
+    center.y + Math.abs(normal.y) * strokeExtent
+  );
+}
+
+function segmentStrokeBounds(start, end, strokeExtent, lineCap = "butt") {
+  const command = { op: "L", x: end.x, y: end.y };
+  const direction = endpointDirection(start, command, end);
+  let bounds = includeExtent(
+    undefined,
+    start.x,
+    start.x,
+    start.y,
+    start.y
+  );
+  bounds = includeExtent(bounds, end.x, end.x, end.y, end.y);
+  if (direction === undefined) {
+    return lineCap === "butt"
+      ? bounds
+      : includeCircle(bounds, start, strokeExtent);
+  }
+  const normal = { x: -direction.y, y: direction.x };
+  for (const point of [start, end]) {
+    bounds = includeExtent(
+      bounds,
+      point.x - Math.abs(normal.x) * strokeExtent,
+      point.x + Math.abs(normal.x) * strokeExtent,
+      point.y - Math.abs(normal.y) * strokeExtent,
+      point.y + Math.abs(normal.y) * strokeExtent
+    );
+  }
+  bounds = includeEndpointCap(
+    bounds, start, direction, strokeExtent, lineCap, true
+  );
+  bounds = includeEndpointCap(
+    bounds, end, direction, strokeExtent, lineCap, false
+  );
+  return bounds;
+}
+
+function includeJoin(
+  bounds,
+  point,
+  incoming,
+  outgoing,
+  strokeExtent,
+  lineJoin,
+  miterLimit
+) {
   if (incoming === undefined || outgoing === undefined) return;
   const cross = incoming.x * outgoing.y - incoming.y * outgoing.x;
   if (Math.abs(cross) <= EPSILON) return;
+  if (lineJoin === "round") {
+    includeCircle(bounds, point, strokeExtent);
+    return;
+  }
+  if (lineJoin === "bevel") return;
   const normalX = -incoming.y - outgoing.y;
   const normalY = incoming.x + outgoing.x;
   const normalLength = Math.hypot(normalX, normalY);
+  if (!(normalLength > EPSILON)) return;
   const ratio = 2 / normalLength;
-  if (ratio > 10 * (1 + EPSILON)) return;
+  if (ratio > miterLimit * (1 + EPSILON)) return;
   const distance = strokeExtent * ratio * (cross > 0 ? -1 : 1) / normalLength;
   includeExtent(
     bounds,
@@ -193,16 +280,11 @@ function includeMiter(bounds, point, incoming, outgoing, strokeExtent) {
   );
 }
 
-function pathStrokeBounds(commands, bounds, strokeExtent) {
-  const expanded = box(
-    bounds.left, bounds.right, bounds.top, bounds.bottom, strokeExtent
-  );
-  if (!(strokeExtent > 0)) return expanded;
+function pathStrokeBounds(commands, bounds, strokeExtent, details) {
+  if (!(strokeExtent > 0)) return bounds;
   const start = { x: commands[0].x, y: commands[0].y };
   let current = start;
-  let firstDirection;
-  let previousDirection;
-  let segmentCount = 0;
+  const segments = [];
   for (const command of commands.slice(1)) {
     const end = command.op === "Z"
       ? start
@@ -210,31 +292,94 @@ function pathStrokeBounds(commands, bounds, strokeExtent) {
     const outgoing = endpointDirection(current, command, end);
     const incoming = endpointDirection(current, command, end, true);
     if (outgoing !== undefined || incoming !== undefined) {
-      if (segmentCount > 0) {
-        includeMiter(expanded, current, previousDirection, outgoing, strokeExtent);
-      } else {
-        firstDirection = outgoing;
-      }
-      previousDirection = incoming;
-      segmentCount += 1;
+      segments.push({
+        start: current,
+        end,
+        command,
+        outgoing,
+        incoming
+      });
     }
     current = end;
     if (command.op === "Z") break;
   }
-  if (commands.at(-1)?.op === "Z" && segmentCount > 1) {
-    includeMiter(
+  let expanded = bounds;
+  for (const segment of segments) {
+    let segmentBounds;
+    if (segment.command.op === "C") {
+      const centerline = resolvePathCommandBounds([
+        { op: "M", ...segment.start },
+        segment.command
+      ]);
+      segmentBounds = box(
+        centerline.left,
+        centerline.right,
+        centerline.top,
+        centerline.bottom,
+        strokeExtent
+      );
+    } else {
+      segmentBounds = segmentStrokeBounds(
+          segment.start,
+          segment.end,
+          strokeExtent,
+          "butt"
+      );
+    }
+    expanded = unionBounds([expanded, segmentBounds]);
+  }
+  for (let index = 1; index < segments.length; index += 1) {
+    includeJoin(
+      expanded,
+      segments[index].start,
+      segments[index - 1].incoming,
+      segments[index].outgoing,
+      strokeExtent,
+      details.lineJoin,
+      details.miterLimit
+    );
+  }
+  const closed = commands.at(-1)?.op === "Z";
+  if (closed && segments.length > 1) {
+    includeJoin(
       expanded,
       start,
-      previousDirection,
-      firstDirection,
-      strokeExtent
+      segments.at(-1).incoming,
+      segments[0].outgoing,
+      strokeExtent,
+      details.lineJoin,
+      details.miterLimit
+    );
+  } else if (!closed && segments.length > 0) {
+    expanded = includeEndpointCap(
+      expanded,
+      segments[0].start,
+      segments[0].outgoing,
+      strokeExtent,
+      details.lineCap,
+      true
+    );
+    expanded = includeEndpointCap(
+      expanded,
+      segments.at(-1).end,
+      segments.at(-1).incoming,
+      strokeExtent,
+      details.lineCap,
+      false
     );
   }
   return expanded;
 }
 
+function hasActiveStroke(properties) {
+  return typeof properties.stroke === "string" &&
+    (properties.strokeWidth ?? 0) > 0;
+}
+
 function primitiveBounds(type, properties = {}) {
-  const strokeExtent = (properties.strokeWidth ?? 0) / 2;
+  const strokeExtent = hasActiveStroke(properties)
+    ? properties.strokeWidth / 2
+    : 0;
   if (type === "circle") {
     if (![properties.x, properties.y, properties.radius].every(Number.isFinite)) {
       return undefined;
@@ -261,12 +406,11 @@ function primitiveBounds(type, properties = {}) {
   if (type === "line") {
     if (![properties.x1, properties.y1, properties.x2, properties.y2]
       .every(Number.isFinite)) return undefined;
-    return box(
-      Math.min(properties.x1, properties.x2),
-      Math.max(properties.x1, properties.x2),
-      Math.min(properties.y1, properties.y2),
-      Math.max(properties.y1, properties.y2),
-      strokeExtent
+    return segmentStrokeBounds(
+      { x: properties.x1, y: properties.y1 },
+      { x: properties.x2, y: properties.y2 },
+      strokeExtent,
+      resolveStrokeDetails(properties).lineCap
     );
   }
   if (type === "text") {
@@ -283,7 +427,12 @@ function primitiveBounds(type, properties = {}) {
     if (!Array.isArray(commands)) return undefined;
     const bounds = resolvePathCommandBounds(commands);
     if (bounds === undefined) return undefined;
-    return pathStrokeBounds(commands, bounds, strokeExtent);
+    return pathStrokeBounds(
+      commands,
+      bounds,
+      strokeExtent,
+      resolveStrokeDetails(properties)
+    );
   }
   return undefined;
 }

package/src/grammar/schemas/semanticPath.js

@@ -18,6 +18,7 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.x.bin.maxBins",
   "encoding.x.bin.step",
   "encoding.x.bin.boundaries",
+  "encoding.x.weight",
   "encoding.color.layout",
   "encoding.color.aggregate",
   "encoding.group.fields",
@@ -77,7 +78,7 @@ const ENTITY_PATHS = Object.freeze({
   },
   coordinate: {
     collection: "coordinates",
-    properties: new Set(["type"])
+    properties: new Set(["type", "aspect", "polarFrame"])
   }
 });
 
@@ -101,6 +102,9 @@ const GUIDE_PATHS = new Set([
   "legend.color.scale",
   "legend.color.title",
   "legend.color.order",
+  "legend.stroke.scale",
+  "legend.stroke.title",
+  "legend.stroke.order",
   "legend.size.scale",
   "legend.size.title",
   "legend.strokeWidth.scale",
@@ -132,6 +136,7 @@ const GUIDE_REMOVABLE_CONTAINERS = new Set([
   "grid.theta",
   "grid.radial",
   "legend.color",
+  "legend.stroke",
   "legend.size",
   "legend.strokeWidth",
   "legend.opacity",
@@ -151,7 +156,7 @@ export function parseSemanticPath(property, { allowContainer = false } = {}) {
 
   if (allowContainer) {
     const entityMatch = property.match(
-      new RegExp(`^(dataset|layer|scale)\\[(${USER_ID_SOURCE})\\]$`)
+      new RegExp(`^(dataset|layer|scale|coordinate)\\[(${USER_ID_SOURCE})\\]$`)
     );
     if (entityMatch) {
       const [, kind, id] = entityMatch;

package/src/grammar/statisticalReference.js

@@ -0,0 +1,103 @@
+import { aggregateRows } from "./aggregate.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const STATISTIC_KEYS = Object.freeze(["op", "p"]);
+const SIMPLE_STATISTICS = new Set(["mean", "median", "min", "max"]);
+const POPULATIONS = new Set(["boundData", "visibleItems"]);
+const TRANSFORM_KEYS = Object.freeze(["type", "target"]);
+
+function rejectUnknownKeys(value, supported, label) {
+  const unknown = Object.keys(value).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ${label} property "${unknown}".`);
+  }
+}
+
+export function normalizeReferenceStatistic(value, label = "Reference statistic") {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  rejectUnknownKeys(value, STATISTIC_KEYS, label.toLowerCase());
+  if (SIMPLE_STATISTICS.has(value.op)) {
+    if (Object.hasOwn(value, "p")) {
+      throw new Error(`${label} ${value.op} does not accept p.`);
+    }
+    return cloneAndFreeze({ op: value.op });
+  }
+  if (value.op !== "quantile") {
+    throw new Error(`Unsupported ${label.toLowerCase()} "${value.op ?? "unknown"}".`);
+  }
+  if (!Number.isFinite(value.p) || value.p < 0 || value.p > 1) {
+    throw new RangeError(`${label} quantile p must be between 0 and 1.`);
+  }
+  return cloneAndFreeze({ op: "quantile", p: value.p });
+}
+
+export function normalizeReferenceStatistics(value, count, label) {
+  if (!Array.isArray(value) || value.length !== count) {
+    throw new TypeError(`${label} requires exactly ${count} statistic${count === 1 ? "" : "s"}.`);
+  }
+  return Object.freeze(value.map((statistic, index) =>
+    normalizeReferenceStatistic(statistic, `${label} statistic ${index + 1}`)
+  ));
+}
+
+export function normalizeReferencePopulation(value, label = "Reference population") {
+  const population = value ?? "boundData";
+  if (!POPULATIONS.has(population)) {
+    throw new Error(`${label} must be boundData or visibleItems.`);
+  }
+  return population;
+}
+
+export function normalizeReferenceField(value, label = "Reference field") {
+  if (value === undefined) return cloneAndFreeze({ kind: "axis" });
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return cloneAndFreeze({ kind: "explicit", field: value });
+}
+
+export function normalizeStatisticalReferenceTransform({ target } = {}) {
+  const transform = { type: "statisticalReference", target };
+  validateStatisticalReferenceTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateStatisticalReferenceTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Statistical reference transform must be a plain object.");
+  }
+  rejectUnknownKeys(
+    transform,
+    TRANSFORM_KEYS,
+    "statistical reference transform"
+  );
+  if (transform.type !== "statisticalReference") {
+    throw new Error(`Unsupported statistical reference transform "${transform.type}".`);
+  }
+  if (typeof transform.target !== "string" || transform.target.length === 0) {
+    throw new TypeError("Statistical reference transform target must be a non-empty string.");
+  }
+  return transform;
+}
+
+export function deriveStatisticalReferenceValues(values, statistics, label) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${label} population must contain at least one value.`);
+  }
+  values.forEach((value, index) => {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `${label} population value ${index} must be a finite number.`
+      );
+    }
+  });
+  return statistics.map(statistic => aggregateRows(
+    values.map(value => ({ value })),
+    "value",
+    statistic.op === "quantile"
+      ? { op: "quantile", probability: statistic.p }
+      : statistic.op
+  ));
+}

package/src/grammar/strokeStyle.js

@@ -0,0 +1,77 @@
+import { freezeOwned, isPlainObject } from "../core/immutable.js";
+
+export const DEFAULT_LINE_CAP = "butt";
+export const DEFAULT_LINE_JOIN = "miter";
+export const DEFAULT_MITER_LIMIT = 10;
+
+export const LINE_CAPS = Object.freeze(["butt", "round", "square"]);
+export const LINE_JOINS = Object.freeze(["miter", "round", "bevel"]);
+export const STROKE_STYLE_PROPERTIES = Object.freeze([
+  "lineCap",
+  "lineJoin",
+  "miterLimit"
+]);
+
+function validateEnum(value, values, property, label) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${label} ${property} must be a string.`);
+  }
+  if (!values.includes(value)) {
+    throw new Error(
+      `${label} ${property} must be one of ${values.join(", ")}.`
+    );
+  }
+  return value;
+}
+
+export function validateLineCap(value, label = "Stroke style") {
+  return validateEnum(value, LINE_CAPS, "lineCap", label);
+}
+
+export function validateLineJoin(value, label = "Stroke style") {
+  return validateEnum(value, LINE_JOINS, "lineJoin", label);
+}
+
+export function validateMiterLimit(value, label = "Stroke style") {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${label} miterLimit must be a finite number.`);
+  }
+  if (!(value > 0)) {
+    throw new RangeError(`${label} miterLimit must be positive.`);
+  }
+  return value;
+}
+
+export function resolveStrokeDetails(request = {}) {
+  if (!isPlainObject(request)) {
+    throw new TypeError("Stroke style details must be a plain object.");
+  }
+  return freezeOwned({
+    lineCap: request.lineCap === undefined
+      ? DEFAULT_LINE_CAP
+      : validateLineCap(request.lineCap),
+    lineJoin: request.lineJoin === undefined
+      ? DEFAULT_LINE_JOIN
+      : validateLineJoin(request.lineJoin),
+    miterLimit: request.miterLimit === undefined
+      ? DEFAULT_MITER_LIMIT
+      : validateMiterLimit(request.miterLimit)
+  });
+}
+
+export function requestedStrokeDetails(request = {}, label = "Stroke style") {
+  if (!isPlainObject(request)) {
+    throw new TypeError(`${label} details must be a plain object.`);
+  }
+  const result = {};
+  if (Object.hasOwn(request, "lineCap")) {
+    result.lineCap = validateLineCap(request.lineCap, label);
+  }
+  if (Object.hasOwn(request, "lineJoin")) {
+    result.lineJoin = validateLineJoin(request.lineJoin, label);
+  }
+  if (Object.hasOwn(request, "miterLimit")) {
+    result.miterLimit = validateMiterLimit(request.miterLimit, label);
+  }
+  return freezeOwned(result);
+}

package/src/grammar/summary.js

@@ -5,9 +5,18 @@ import {
   validateAggregate,
   validateAggregateFieldValues
 } from "./aggregate.js";
+import {
+  calculateWeightedAggregate,
+  normalizeStatisticalWeight,
+  readStatisticalWeights,
+  summarizeStatisticalWeights,
+  validateWeightedAggregate,
+  validateWeightedNumericFields,
+  weightedRows
+} from "./weightedStatistics.js";
 
 const TRANSFORM_KEYS = Object.freeze([
-  "type", "groupBy", "aggregates", "members"
+  "type", "groupBy", "aggregates", "members", "weight"
 ]);
 const AGGREGATE_KEYS = Object.freeze(["op", "field", "as"]);
 const NOMINAL_OPERATIONS = new Set(["distinct", "valid", "missing"]);
@@ -42,14 +51,17 @@ function normalizeAggregate(value) {
   };
 }
 
-export function normalizeSummaryTransform({ groupBy, aggregates, members } = {}) {
+export function normalizeSummaryTransform({ groupBy, aggregates, members, weight } = {}) {
   const transform = {
     type: "summary",
     groupBy: normalizeGroupBy(groupBy),
     aggregates: Array.isArray(aggregates)
       ? aggregates.map(normalizeAggregate)
       : aggregates,
-    ...(members === undefined ? {} : { members })
+    ...(members === undefined ? {} : { members }),
+    ...(weight === undefined
+      ? {}
+      : { weight: normalizeStatisticalWeight(weight, "Summary weight") })
   };
   validateSummaryTransform(transform);
   return cloneAndFreeze(transform);
@@ -85,6 +97,7 @@ export function validateSummaryTransform(transform) {
     }
     rejectUnknownKeys(aggregate, AGGREGATE_KEYS, `summary aggregate ${index}`);
     const operation = validateAggregate(aggregate.op);
+    if (transform.weight !== undefined) validateWeightedAggregate(operation);
     if (operation === "count") {
       if (Object.hasOwn(aggregate, "field")) {
         throw new Error("Summary count does not accept a field.");
@@ -104,6 +117,9 @@ export function validateSummaryTransform(transform) {
       throw new Error(`Summary members field "${members}" collides with another output.`);
     }
   }
+  if (transform.weight !== undefined) {
+    normalizeStatisticalWeight(transform.weight, "Summary weight");
+  }
   return transform;
 }
 
@@ -136,6 +152,9 @@ function requireSourceFields(rows, transform) {
       throw new Error(`Summary source does not contain order field "${orderBy}".`);
     }
   }
+  if (transform.weight !== undefined && !fields.has(transform.weight.field)) {
+    throw new Error(`Summary source does not contain weight field "${transform.weight.field}".`);
+  }
 }
 
 function validateAggregateValues(rows, aggregate) {
@@ -150,21 +169,42 @@ function validateAggregateValues(rows, aggregate) {
 export function deriveSummaryRows(rows, transform) {
   validateSummaryTransform(transform);
   requireSourceFields(rows, transform);
-  for (const aggregate of transform.aggregates) {
-    validateAggregateValues(rows, aggregate);
+  let weightEntries;
+  if (transform.weight === undefined) {
+    for (const aggregate of transform.aggregates) {
+      validateAggregateValues(rows, aggregate);
+    }
+  } else {
+    weightEntries = readStatisticalWeights(rows, transform.weight, "Summary").entries;
+    validateWeightedNumericFields(
+      weightEntries,
+      [...new Set(transform.aggregates.flatMap(aggregate =>
+        aggregate.field === undefined ? [] : [aggregate.field]
+      ))],
+      "Summary"
+    );
   }
 
   const groups = new Map();
   if (transform.groupBy.length === 0) {
-    groups.set("all", { values: {}, rows });
+    groups.set("all", {
+      values: {},
+      rows,
+      ...(weightEntries === undefined ? {} : { entries: weightEntries })
+    });
   } else {
-    rows.forEach(row => {
+    rows.forEach((row, index) => {
       const values = Object.fromEntries(transform.groupBy.map(field => [field, row[field]]));
       const key = transform.groupBy.map(field =>
         scalarKey(row[field], `Summary group field "${field}"`)
       ).join("|");
-      const group = groups.get(key) ?? { values, rows: [] };
+      const group = groups.get(key) ?? {
+        values,
+        rows: [],
+        ...(weightEntries === undefined ? {} : { entries: [] })
+      };
       group.rows.push(row);
+      if (weightEntries !== undefined) group.entries.push(weightEntries[index]);
       groups.set(key, group);
     });
   }
@@ -172,12 +212,34 @@ export function deriveSummaryRows(rows, transform) {
     throw new RangeError(`Summary output cannot exceed ${MAX_OUTPUT_ROWS} groups.`);
   }
 
-  return [...groups.values()].map(group => ({
-    ...group.values,
-    ...Object.fromEntries(transform.aggregates.map(aggregate => [
-      aggregate.as,
-      aggregateRows(group.rows, aggregate.field ?? "__row", aggregate.op)
-    ])),
-    ...(transform.members === undefined ? {} : { [transform.members]: group.rows })
-  }));
+  return [...groups.values()].map(group => {
+    const weightSummary = transform.weight === undefined
+      ? undefined
+      : summarizeStatisticalWeights(
+          group.entries,
+          transform.weight.kind,
+          "Summary group"
+        );
+    return {
+      ...group.values,
+      ...Object.fromEntries(transform.aggregates.map(aggregate => [
+        aggregate.as,
+        weightSummary === undefined
+          ? aggregateRows(group.rows, aggregate.field ?? "__row", aggregate.op)
+          : calculateWeightedAggregate(
+              weightSummary,
+              aggregate.field,
+              aggregate.op,
+              `Summary aggregate "${aggregate.as}"`
+            )
+      ])),
+      ...(transform.members === undefined
+        ? {}
+        : {
+            [transform.members]: weightSummary === undefined
+              ? group.rows
+              : weightedRows(weightSummary)
+          })
+    };
+  });
 }