ggaction 0.0.12 → 0.0.15

package/src/grammar/statistics/confidenceInterval.js

@@ -0,0 +1,101 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import { studentTCriticalValue } from "./studentT.js";
+
+export const CONFIDENCE_INTERVAL_METHODS = Object.freeze([
+  "normal",
+  "student-t"
+]);
+
+function validateMethod(method, label) {
+  if (!CONFIDENCE_INTERVAL_METHODS.includes(method)) {
+    throw new Error(`Unsupported ${label} method "${method}".`);
+  }
+}
+
+function validateLevel(level, label) {
+  if (!Number.isFinite(level) || level <= 0 || level >= 1) {
+    throw new RangeError(`${label} level must be between 0 and 1.`);
+  }
+}
+
+// Peter J. Acklam's inverse-normal approximation. The exact 95% compatibility
+// value is handled by normalCriticalValue before this approximation is used.
+function inverseNormal(probability) {
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2,
+    -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2,
+    -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1
+  ];
+  const c = [
+    -7.784894002430293e-3, -3.223964580411365e-1,
+    -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783
+  ];
+  const d = [
+    7.784695709041462e-3, 3.224671290700398e-1,
+    2.445134137142996, 3.754408661907416
+  ];
+  const low = 0.02425;
+  const high = 1 - low;
+  if (probability < low) {
+    const q = Math.sqrt(-2 * Math.log(probability));
+    return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+  }
+  if (probability > high) {
+    const q = Math.sqrt(-2 * Math.log(1 - probability));
+    return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+  }
+  const q = probability - 0.5;
+  const r = q * q;
+  return (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q /
+    (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+}
+
+export function normalizeConfidenceInterval({
+  method,
+  level
+} = {}, {
+  defaultMethod,
+  defaultLevel = 0.95,
+  label = "Confidence interval"
+} = {}) {
+  validateMethod(defaultMethod, label);
+  const resolvedMethod = method ?? defaultMethod;
+  const resolvedLevel = level ?? defaultLevel;
+  validateMethod(resolvedMethod, label);
+  validateLevel(resolvedLevel, label);
+  return cloneAndFreeze({ method: resolvedMethod, level: resolvedLevel });
+}
+
+export function normalCriticalValue(level) {
+  validateLevel(level, "Normal confidence interval");
+  if (level === 0.95) return 1.96;
+  return inverseNormal((1 + level) / 2);
+}
+
+export function confidenceCriticalValue({
+  method,
+  level,
+  degreesOfFreedom
+}) {
+  const normalized = normalizeConfidenceInterval(
+    { method, level },
+    { defaultMethod: method, label: "Confidence interval" }
+  );
+  if (normalized.method === "normal") {
+    return normalCriticalValue(normalized.level);
+  }
+  if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
+    throw new RangeError(
+      "Student-t confidence interval degreesOfFreedom must be a positive integer."
+    );
+  }
+  return studentTCriticalValue(normalized.level, degreesOfFreedom);
+}

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

@@ -0,0 +1,245 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  aggregateRows,
+  isScalarAggregate,
+  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", "weight"
+]);
+const AGGREGATE_KEYS = Object.freeze(["op", "field", "as"]);
+const NOMINAL_OPERATIONS = new Set(["distinct", "valid", "missing"]);
+const MAX_OUTPUT_ROWS = 10_000;
+
+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}".`);
+  }
+}
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function normalizeGroupBy(value) {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? [...value] : [value];
+}
+
+function normalizeAggregate(value) {
+  if (!isPlainObject(value)) return value;
+  return {
+    ...value,
+    op: validateAggregate(value.op),
+    ...(Object.hasOwn(value, "field") ? { field: value.field } : {}),
+    as: value.as
+  };
+}
+
+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 }),
+    ...(weight === undefined
+      ? {}
+      : { weight: normalizeStatisticalWeight(weight, "Summary weight") })
+  };
+  validateSummaryTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateSummaryTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Summary transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "summary transform");
+  if (transform.type !== "summary") {
+    throw new Error(`Unsupported summary transform "${transform.type}".`);
+  }
+  if (
+    !Array.isArray(transform.groupBy) ||
+    transform.groupBy.some(field => typeof field !== "string" || field.length === 0)
+  ) {
+    throw new TypeError("Summary groupBy must contain field names.");
+  }
+  if (new Set(transform.groupBy).size !== transform.groupBy.length) {
+    throw new Error("Summary groupBy fields must be unique.");
+  }
+  if (!Array.isArray(transform.aggregates) || transform.aggregates.length === 0) {
+    throw new TypeError("Summary aggregates must be a non-empty array.");
+  }
+  if (transform.aggregates.length > 64) {
+    throw new RangeError("Summary aggregates cannot contain more than 64 outputs.");
+  }
+  const outputs = new Set(transform.groupBy);
+  transform.aggregates.forEach((aggregate, index) => {
+    if (!isPlainObject(aggregate)) {
+      throw new TypeError(`Summary aggregate ${index} must be a plain object.`);
+    }
+    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.");
+      }
+    } else {
+      requireField(aggregate.field, `Summary aggregate ${index} field`);
+    }
+    const output = requireField(aggregate.as, `Summary aggregate ${index} as`);
+    if (outputs.has(output)) {
+      throw new Error(`Summary output field "${output}" collides with another output.`);
+    }
+    outputs.add(output);
+  });
+  if (transform.members !== undefined) {
+    const members = requireField(transform.members, "Summary members");
+    if (outputs.has(members)) {
+      throw new Error(`Summary members field "${members}" collides with another output.`);
+    }
+  }
+  if (transform.weight !== undefined) {
+    normalizeStatisticalWeight(transform.weight, "Summary weight");
+  }
+  return transform;
+}
+
+function scalarKey(value, label) {
+  if (value === null) return "null";
+  if (typeof value === "string") return `string:${value.length}:${value}`;
+  if (typeof value === "boolean") return `boolean:${value}`;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `number:${Object.is(value, -0) ? 0 : value}`;
+  }
+  throw new TypeError(
+    `${label} must contain null, strings, booleans, or finite numbers.`
+  );
+}
+
+function requireSourceFields(rows, transform) {
+  if (rows.length === 0) return;
+  const fields = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const field of transform.groupBy) {
+    if (!fields.has(field)) {
+      throw new Error(`Summary source does not contain group field "${field}".`);
+    }
+  }
+  for (const aggregate of transform.aggregates) {
+    if (aggregate.field !== undefined && !fields.has(aggregate.field)) {
+      throw new Error(`Summary source does not contain aggregate field "${aggregate.field}".`);
+    }
+    const orderBy = isPlainObject(aggregate.op) ? aggregate.op.orderBy : undefined;
+    if (orderBy !== undefined && !fields.has(orderBy)) {
+      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) {
+  if (aggregate.op === "count") return;
+  if (isScalarAggregate(aggregate.op) && NOMINAL_OPERATIONS.has(aggregate.op)) {
+    validateAggregateFieldValues(rows, aggregate.field, "nominal");
+    return;
+  }
+  validateAggregateFieldValues(rows, aggregate.field, "quantitative");
+}
+
+export function deriveSummaryRows(rows, transform) {
+  validateSummaryTransform(transform);
+  requireSourceFields(rows, transform);
+  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,
+      ...(weightEntries === undefined ? {} : { entries: weightEntries })
+    });
+  } else {
+    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: [],
+        ...(weightEntries === undefined ? {} : { entries: [] })
+      };
+      group.rows.push(row);
+      if (weightEntries !== undefined) group.entries.push(weightEntries[index]);
+      groups.set(key, group);
+    });
+  }
+  if (groups.size > MAX_OUTPUT_ROWS) {
+    throw new RangeError(`Summary output cannot exceed ${MAX_OUTPUT_ROWS} groups.`);
+  }
+
+  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)
+          })
+    };
+  });
+}

package/src/grammar/text.js

@@ -1,5 +1,15 @@
 import { cloneAndFreeze } from "../core/immutable.js";
 import { validateConcreteGraphicValue } from "./schemas/concreteGraphic.js";
+import {
+  formatValue,
+  isUtcValueFormat,
+  validateValueFormat
+} from "./valueFormat.js";
+import { resolveRotation } from "./rotation.js";
+
+export function isSourceOwnedText(layer) {
+  return layer?.mark?.type === "text" && layer.source !== undefined;
+}
 
 export const DEFAULT_TEXT_MARK = cloneAndFreeze({
   fill: "#334155",
@@ -14,20 +24,13 @@ export const DEFAULT_TEXT_MARK = cloneAndFreeze({
   dy: 0
 });
 
-const FIXED_FORMAT = /^\.(\d{1,2})f$/;
-
 export function validateTextFormat(format) {
-  if (format === undefined || format === "auto") return format ?? "auto";
-  if (typeof format !== "string" || !FIXED_FORMAT.test(format)) {
+  if (format !== undefined && typeof format !== "string") {
     throw new Error(
-      'Text format must be "auto" or a fixed-decimal token such as ".1f".'
+      'Text format must be "auto" or a supported numeric/UTC format string.'
     );
   }
-  const decimals = Number(format.match(FIXED_FORMAT)[1]);
-  if (decimals > 12) {
-    throw new RangeError("Text fixed-decimal format supports at most 12 decimals.");
-  }
-  return format;
+  return validateValueFormat(format, "Text format");
 }
 
 export function formatTextValue(value, format = "auto") {
@@ -37,10 +40,11 @@ export function formatTextValue(value, format = "auto") {
     const text = String(value);
     return text.length === 0 ? undefined : text;
   }
-  if (!Number.isFinite(value)) {
-    throw new TypeError(`Text format "${resolved}" requires a finite number.`);
-  }
-  return value.toFixed(Number(resolved.match(FIXED_FORMAT)[1]));
+  return formatValue(value, {
+    format: resolved,
+    valueType: isUtcValueFormat(resolved) ? "temporal" : "quantitative",
+    label: "Text format"
+  });
 }
 
 export function normalizeTextMarkConfig(options, base = DEFAULT_TEXT_MARK) {
@@ -52,14 +56,16 @@ export function normalizeTextMarkConfig(options, base = DEFAULT_TEXT_MARK) {
     fontFamily: "fontFamily",
     fontWeight: "fontWeight",
     align: "textAlign",
-    baseline: "textBaseline",
-    rotation: "rotation"
+    baseline: "textBaseline"
   };
   for (const [option, property] of Object.entries(mapping)) {
     if (!Object.hasOwn(options, option)) continue;
     validateConcreteGraphicValue("text", property, options[option]);
     config[option] = options[option];
   }
+  if (Object.hasOwn(options, "rotation")) {
+    config.rotation = resolveRotation(options.rotation, "Text rotation");
+  }
   for (const property of ["dx", "dy"]) {
     if (!Object.hasOwn(options, property)) continue;
     if (!Number.isFinite(options[property])) {