ggaction 0.0.15 → 0.0.17

package/src/grammar/regression/models.js

@@ -58,14 +58,14 @@ function linearPrediction(model, xValue) {
 }
 
 function fitLinearGroup(rows, {
-  x, y, group, confidenceMethod, level
+  x, y, group, confidenceMethod, level, interval
 }) {
   const count = rows.length;
   const groupLabel = group === undefined ? "all" : String(group);
   const label = `Regression group "${groupLabel}"`;
-  if (count < 3) {
+  if (count < (interval === false ? 2 : 3)) {
     throw new Error(
-      `${label} requires at least three rows.`
+      `${label} requires at least ${interval === false ? "two" : "three"} rows.`
     );
   }
   const xValues = rows.map(row => row[x]);
@@ -148,6 +148,7 @@ function fitLinearGroup(rows, {
     normalizedSxx
   });
   if (!normalizedXByDifference) model.normalizedXByDifference = false;
+  if (interval === false) return model;
   const residualSumSquares = stableFiniteSquareSum(
     rows.map(row => row[y] - linearPrediction(model, row[x])),
     `${label} residual sum of squares`
@@ -238,19 +239,19 @@ function polynomialResponse(design, values, size, scale = 1) {
 }
 
 function fitPolynomialGroup(rows, {
-  x, y, group, confidenceMethod, level, degree
+  x, y, group, confidenceMethod, level, degree, interval
 }) {
   const count = rows.length;
   const parameterCount = degree + 1;
   const groupLabel = group === undefined ? "all" : String(group);
   const label = `Polynomial regression group "${groupLabel}"`;
   if (
-    count < degree + 2 ||
+    count < (interval === false ? parameterCount : degree + 2) ||
     new Set(rows.map(row => row[x])).size < parameterCount
   ) {
     throw new Error(
       `${label} requires at least ` +
-      `${degree + 2} rows and ${parameterCount} distinct x values.`
+      `${interval === false ? parameterCount : degree + 2} rows and ${parameterCount} distinct x values.`
     );
   }
   const xValues = rows.map(row => row[x]);
@@ -289,7 +290,7 @@ function fitPolynomialGroup(rows, {
         `${label} coefficient ${index}`
       ))
     : scaledCoefficients;
-  const inverse = invertSymmetricMatrix(normal);
+  const inverse = interval === false ? undefined : invertSymmetricMatrix(normal);
   const fitted = design.map(basis => stableResponse
     ? restoreFiniteScale(
         dot(basis, scaledCoefficients),
@@ -298,12 +299,12 @@ function fitPolynomialGroup(rows, {
       )
     : dot(basis, normalizedCoefficients)
   );
-  const residualSumSquares = stableFiniteSquareSum(
+  const residualSumSquares = interval === false ? undefined : stableFiniteSquareSum(
     fitted.map((value, index) => rows[index][y] - value),
     `${label} residual sum of squares`
   );
   const degreesOfFreedom = count - parameterCount;
-  const residualVariance = residualSumSquares / degreesOfFreedom;
+  const residualVariance = interval === false ? undefined : residualSumSquares / degreesOfFreedom;
   const model = {
     count,
     degreesOfFreedom,
@@ -316,13 +317,15 @@ function fitPolynomialGroup(rows, {
     normalizedCoefficients,
     center,
     scale,
-    inverse,
-    residualSumSquares,
-    residualStandardError: Math.sqrt(residualVariance),
-    critical: confidenceCriticalValue({
-      method: confidenceMethod,
-      level,
-      degreesOfFreedom
+    ...(inverse === undefined ? {} : { inverse }),
+    ...(interval === false ? {} : {
+      residualSumSquares,
+      residualStandardError: Math.sqrt(residualVariance),
+      critical: confidenceCriticalValue({
+        method: confidenceMethod,
+        level,
+        degreesOfFreedom
+      })
     })
   };
   if (!normalizedXByDifference) model.normalizedXByDifference = false;
@@ -345,7 +348,9 @@ function evaluatePolynomial(model, xValue) {
           model.responseScale,
           "Polynomial regression prediction"
         ),
-    leverage: dot(basis, model.inverse.map(row => dot(row, basis)))
+    ...(model.inverse === undefined ? {} : {
+      leverage: dot(basis, model.inverse.map(row => dot(row, basis)))
+    })
   };
 }
 
@@ -420,7 +425,29 @@ function fitLoessGroup(rows, { x, y, group, span }) {
       neighborIndices: weighted.map(item => item.index)
     };
   });
-  return { count: rows.length, span, neighborCount, fits };
+  return { count: rows.length, span, neighborCount, fits, rows, x, y, xScale, yScale };
+}
+
+function predictLoessAt(model, xValue) {
+  const found = model.fits.find(fit => fit.x === xValue);
+  if (found !== undefined) return found.prediction;
+  const neighbors = model.rows.map((row, index) => ({
+    row,
+    index,
+    distance: Math.abs(row[model.x] / model.xScale - xValue / model.xScale)
+  })).sort((left, right) => left.distance - right.distance || left.index - right.index)
+    .slice(0, model.neighborCount);
+  const radius = neighbors.at(-1).distance;
+  const weighted = neighbors.map(neighbor => ({
+    ...neighbor,
+    weight: radius === 0 ? 1 : (1 - (neighbor.distance / radius) ** 3) ** 3
+  }));
+  const ordinary = weightedPrediction(weighted, model.x, model.y, xValue);
+  return Number.isFinite(ordinary) ? ordinary : restoreFiniteScale(
+    weightedPrediction(weighted, model.x, model.y, xValue, model.xScale, model.yScale),
+    model.yScale,
+    "LOESS regression prediction"
+  );
 }
 
 export function fitRegressionGroup(rows, { x, y, group, parameters }) {
@@ -430,7 +457,8 @@ export function fitRegressionGroup(rows, { x, y, group, parameters }) {
       y,
       group,
       confidenceMethod: parameters.confidenceMethod,
-      level: parameters.level
+      level: parameters.level,
+      interval: parameters.interval
     });
   }
   if (parameters.method === "polynomial") {
@@ -440,7 +468,8 @@ export function fitRegressionGroup(rows, { x, y, group, parameters }) {
       group,
       confidenceMethod: parameters.confidenceMethod,
       level: parameters.level,
-      degree: parameters.degree
+      degree: parameters.degree,
+      interval: parameters.interval
     });
   }
   return fitLoessGroup(rows, { x, y, group, span: parameters.span });
@@ -454,8 +483,8 @@ export function predictRegressionAt(model, xValue, parameters) {
     ? linearPrediction(model, xValue)
     : parameters.method === "polynomial"
       ? polynomial.prediction
-      : model.fits.find(fit => fit.x === xValue).prediction;
-  if (parameters.method === "loess") return { prediction };
+      : predictLoessAt(model, xValue);
+  if (parameters.method === "loess" || parameters.interval === false) return { prediction };
   const leverage = parameters.method === "linear"
     ? model.normalizedSxx !== undefined
       ? 1 / model.count + (

package/src/grammar/regression/parameters.js

@@ -1,10 +1,39 @@
-import { cloneAndFreeze } from "../../core/immutable.js";
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 import { validateGeneratedItemLimit } from "../../core/validation.js";
 import { normalizeConfidenceInterval } from
   "../statistics/confidenceInterval.js";
 
 const MAX_POLYNOMIAL_DEGREE = 32;
 
+export function normalizeRegressionPredict(predict) {
+  if (predict === undefined) return undefined;
+  if (predict === false) throw new TypeError("Regression predict false is only valid in edits.");
+  if (!isPlainObject(predict)) {
+    throw new TypeError("Regression predict must be a plain object.");
+  }
+  const unknown = Object.keys(predict).find(key => !["values", "domain", "steps"].includes(key));
+  if (unknown !== undefined) throw new Error(`Unknown regression predict property "${unknown}".`);
+  const usesValues = Object.hasOwn(predict, "values");
+  const usesDomain = Object.hasOwn(predict, "domain") || Object.hasOwn(predict, "steps");
+  if (usesValues === usesDomain) throw new Error("Regression predict requires values or domain with steps.");
+  if (usesValues) {
+    const values = predict.values;
+    if (!Array.isArray(values) || values.length === 0 || values.some((value, index) =>
+      !Number.isFinite(value) || (index > 0 && !(value > values[index - 1]))
+    )) throw new TypeError("Regression predict values must be finite, unique, and strictly ascending.");
+    return cloneAndFreeze({ values: [...values] });
+  }
+  if (!Array.isArray(predict.domain) || predict.domain.length !== 2 ||
+      !predict.domain.every(Number.isFinite) || !(predict.domain[0] < predict.domain[1])) {
+    throw new TypeError("Regression predict domain must be two increasing finite numbers.");
+  }
+  if (!Number.isInteger(predict.steps) || predict.steps < 2) {
+    throw new RangeError("Regression predict steps must be an integer of at least two.");
+  }
+  validateGeneratedItemLimit(predict.steps, "Regression predict steps");
+  return cloneAndFreeze({ domain: [...predict.domain], steps: predict.steps });
+}
+
 export function requireRegressionField(field, label) {
   if (typeof field !== "string" || field.length === 0) {
     throw new TypeError(`${label} must be a non-empty string.`);
@@ -45,6 +74,21 @@ export function normalizeRegressionParameters({
   if (span !== undefined) {
     throw new Error("Regression span requires the loess method.");
   }
+  if (interval === false) {
+    if (confidenceMethod !== undefined || level !== undefined || confidence !== undefined) {
+      throw new Error("Regression interval false cannot include confidence options.");
+    }
+    if (method === "polynomial") {
+      const resolvedDegree = degree ?? 2;
+      if (!Number.isInteger(resolvedDegree) || resolvedDegree < 1) {
+        throw new RangeError("Regression polynomial degree must be a positive integer.");
+      }
+      validateGeneratedItemLimit(resolvedDegree, "Regression polynomial degree", MAX_POLYNOMIAL_DEGREE);
+      return cloneAndFreeze({ method, degree: resolvedDegree, interval: false });
+    }
+    if (degree !== undefined) throw new Error("Regression degree requires the polynomial method.");
+    return cloneAndFreeze({ method, interval: false });
+  }
   if (level !== undefined && confidence !== undefined && level !== confidence) {
     throw new Error(
       "Regression level and confidence alias must match when both are provided."
@@ -96,7 +140,7 @@ export function validateRegressionTransform(transform) {
   const supported = [
     "type", "method", "x", "y", "groupBy", "confidenceMethod", "level",
     "confidence", "interval",
-    "degree", "span"
+    "degree", "span", "predict", "missing"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
@@ -127,9 +171,14 @@ export function validateRegressionTransform(transform) {
     confidence: transform.confidence,
     interval: transform.interval
   });
+  normalizeRegressionPredict(transform.predict);
+  if (transform.missing !== undefined && !["error", "drop"].includes(transform.missing)) {
+    throw new Error('Regression missing must be "error" or "drop".');
+  }
   if (normalized.method === "loess") return transform;
   if (
     transform.confidence === undefined &&
+    transform.interval !== false &&
     (transform.confidenceMethod === undefined || transform.level === undefined)
   ) {
     throw new Error("Regression confidence provenance requires method and level.");
@@ -142,6 +191,7 @@ export function validateRegressionTransform(transform) {
 
 export function normalizeRegressionTransform(args = {}) {
   const parameters = normalizeRegressionParameters(args);
+  const predict = normalizeRegressionPredict(args.predict);
   const transform = {
     type: "regression",
     method: parameters.method,
@@ -153,11 +203,13 @@ export function normalizeRegressionTransform(args = {}) {
       : {}),
     ...(parameters.method === "loess"
       ? { span: parameters.span }
-      : {
+      : parameters.interval === false ? { interval: false } : {
           confidenceMethod: parameters.confidenceMethod,
           level: parameters.level,
           interval: parameters.interval
-        })
+        }),
+    ...(predict === undefined ? {} : { predict }),
+    ...(args.missing === undefined ? {} : { missing: args.missing })
   };
   validateRegressionTransform(transform);
   return cloneAndFreeze(transform);

package/src/grammar/scales/definition.js

@@ -108,6 +108,13 @@ export function normalizeScaleDefinition({
     domain: validateDomain(type, rawDomain),
     range: validateRange(type, rawRange)
   };
+  const emptyDomain = retainedValue(previous, patch, defaults, "emptyDomain", typeChanged);
+  if (emptyDomain !== undefined) {
+    if (!["preserve", "require-explicit"].includes(emptyDomain)) {
+      throw new Error('Scale emptyDomain must be "preserve" or "require-explicit".');
+    }
+    definition.emptyDomain = emptyDomain;
+  }
 
   for (const property of BOOLEAN_PROPERTIES) {
     let value = retainedValue(previous, patch, defaults, property, typeChanged);

package/src/grammar/scales/types.js

@@ -26,6 +26,14 @@ export const COMPLETE_SCALE_TYPES = Object.freeze([
   ...new Set(Object.values(SCALE_TYPES_BY_ROLE).flat())
 ]);
 
+// Dimensionless scale spacing is shared by generic and focused editors.
+export const SCALE_OPTION_UNITS = Object.freeze({
+  padding: "band-fraction",
+  paddingInner: "band-fraction",
+  paddingOuter: "band-fraction",
+  align: "ratio"
+});
+
 const SCALE_PROPERTY_TYPES = Object.freeze({
   midpoint: Object.freeze(["sequential"]),
   nice: Object.freeze(["linear", "log", "pow", "sqrt", "symlog", "time"]),

package/src/grammar/schemas/graphicBounds.js

@@ -376,7 +376,7 @@ function hasActiveStroke(properties) {
     (properties.strokeWidth ?? 0) > 0;
 }
 
-function primitiveBounds(type, properties = {}) {
+function primitiveBounds(type, properties = {}, profile) {
   const strokeExtent = hasActiveStroke(properties)
     ? properties.strokeWidth / 2
     : 0;
@@ -420,7 +420,7 @@ function primitiveBounds(type, properties = {}) {
       !Number.isFinite(properties.fontSize) ||
       typeof properties.text !== "string"
     ) return undefined;
-    return resolveTextBounds(properties);
+    return resolveTextBounds(properties, profile);
   }
   if (type === "path") {
     const commands = properties.commands;
@@ -469,15 +469,15 @@ function ancestorOffset(graphicSpec, target) {
   }
 }
 
-function objectBounds(graphicSpec, id, object, ancestors, x, y) {
+function objectBounds(graphicSpec, id, object, ancestors, x, y, profile) {
   if (ancestors.has(id)) {
     throw new Error(`Graphic attachment cycle includes "${id}".`);
   }
   ancestors.add(id);
   let result = object.items === undefined
-    ? translateBounds(primitiveBounds(object.type, object.properties), x, y)
+    ? translateBounds(primitiveBounds(object.type, object.properties, profile), x, y)
     : unionBounds(object.items.map(item => translateBounds(
-        primitiveBounds(item.type ?? object.type, item.properties),
+        primitiveBounds(item.type ?? object.type, item.properties, profile),
         x,
         y
       )));
@@ -489,7 +489,7 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y) {
       throw new Error(`Unknown attached graphic "${childId}".`);
     }
     const bounds = objectBounds(
-      graphicSpec, childId, child.object, ancestors, childX, childY
+      graphicSpec, childId, child.object, ancestors, childX, childY, profile
     );
     if (bounds !== undefined) {
       result = includeExtent(
@@ -501,23 +501,23 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y) {
   return result;
 }
 
-export function resolveConcreteGraphicBounds(graphicSpec, target) {
+export function resolveConcreteGraphicBounds(graphicSpec, target, profile) {
   const found = requireGraphic(graphicSpec, target);
   const [x, y] = ancestorOffset(graphicSpec, target);
   return requireFiniteBounds(found.kind === "item"
     ? translateBounds(
-      primitiveBounds(found.object.type ?? found.owner.type, found.object.properties),
+      primitiveBounds(found.object.type ?? found.owner.type, found.object.properties, profile),
       x,
       y
     )
-    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y));
+    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y, profile));
 }
 
-export function unionConcreteGraphicBounds(graphicSpec, targets) {
+export function unionConcreteGraphicBounds(graphicSpec, targets, profile) {
   if (!Array.isArray(targets)) {
     throw new TypeError("Graphic bounds targets must be an array.");
   }
   return unionBounds(targets.map(target =>
-    resolveConcreteGraphicBounds(graphicSpec, target)
+    resolveConcreteGraphicBounds(graphicSpec, target, profile)
   ));
 }

package/src/grammar/schemas/semanticPath.js

@@ -49,7 +49,7 @@ const ENCODING_PATHS = Object.freeze([
 const ENTITY_PATHS = Object.freeze({
   dataset: {
     collection: "datasets",
-    properties: new Set(["source", "transform", "values"])
+    properties: new Set(["source", "transform", "schema", "values"])
   },
   layer: {
     collection: "layers",
@@ -64,6 +64,7 @@ const ENTITY_PATHS = Object.freeze({
       "transform",
       "mark.type",
       "mark.missing",
+      "derivedBindings.regression",
       "layout.mode",
       ...ENCODING_PATHS
     ])
@@ -71,7 +72,7 @@ const ENTITY_PATHS = Object.freeze({
   scale: {
     collection: "scales",
     properties: new Set([
-      "type", "domain", "range", "nice", "zero", "clamp", "reverse",
+      "type", "domain", "range", "emptyDomain", "nice", "zero", "clamp", "reverse",
       "unknown", "base", "exponent", "constant", "interpolate", "radialMapping", "midpoint",
       "paddingInner", "paddingOuter", "padding", "align"
     ])

package/src/grammar/sort.js

@@ -0,0 +1,88 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { normalizeTemporalValue } from "./scales/fields.js";
+
+const ORDERS = new Set(["ascending", "descending"]);
+const NULLS = new Set(["first", "last"]);
+const TEMPORAL_UNITS = new Set(["year", "timestamp"]);
+
+export function normalizeSortTransform({ sortBy }) {
+  if (!Array.isArray(sortBy) || sortBy.length === 0 ||
+      Array.from({ length: sortBy.length }, (_, index) => index).some(index => !Object.hasOwn(sortBy, index))) {
+    throw new TypeError("Sorted data sortBy must be a non-empty dense array.");
+  }
+  const keys = sortBy.map((key, index) => {
+    if (!isPlainObject(key)) throw new TypeError(`Sort key ${index} must be a plain object.`);
+    const unknown = Object.keys(key).find(name => !["field", "order", "nulls", "temporalUnit"].includes(name));
+    if (unknown !== undefined) throw new Error(`Unknown sort key property "${unknown}".`);
+    if (typeof key.field !== "string" || key.field.length === 0) {
+      throw new TypeError(`Sort key ${index} field must be a non-empty string.`);
+    }
+    const order = key.order ?? "ascending";
+    const nulls = key.nulls ?? "last";
+    if (!ORDERS.has(order)) throw new Error(`Unsupported sort order "${order}".`);
+    if (!NULLS.has(nulls)) throw new Error(`Unsupported sort null placement "${nulls}".`);
+    if (key.temporalUnit !== undefined && !TEMPORAL_UNITS.has(key.temporalUnit)) {
+      throw new Error(`Unsupported sort temporalUnit "${key.temporalUnit}".`);
+    }
+    return { field: key.field, order, nulls, ...(key.temporalUnit === undefined ? {} : { temporalUnit: key.temporalUnit }) };
+  });
+  if (new Set(keys.map(key => key.field)).size !== keys.length) {
+    throw new Error("Sorted data sortBy fields must be unique.");
+  }
+  return cloneAndFreeze({ type: "sort", sortBy: keys });
+}
+
+export function validateSortTransform(transform) {
+  if (!isPlainObject(transform)) throw new TypeError("Sort transform must be a plain object.");
+  const unknown = Object.keys(transform).find(key => !["type", "sortBy"].includes(key));
+  if (unknown !== undefined) throw new Error(`Unknown sort transform property "${unknown}".`);
+  if (transform.type !== "sort") throw new Error('Sort transform type must be "sort".');
+  normalizeSortTransform(transform);
+}
+
+function compareValues(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function normalizedKey(value, key, rowIndex) {
+  if (value === null || value === undefined) return { missing: true };
+  if (key.temporalUnit !== undefined) {
+    return { missing: false, value: normalizeTemporalValue(value, key.field, rowIndex, key.temporalUnit) };
+  }
+  if (!["number", "string", "boolean"].includes(typeof value) ||
+      (typeof value === "number" && !Number.isFinite(value))) {
+    throw new TypeError(`Sort field "${key.field}" requires finite number, string, boolean, or missing values at row ${rowIndex}.`);
+  }
+  return { missing: false, value, type: typeof value };
+}
+
+export function deriveSortedRows(values, transform) {
+  if (!Array.isArray(values)) throw new TypeError("Sort source values must be an array.");
+  validateSortTransform(transform);
+  const decorated = values.map((row, index) => ({
+    row,
+    index,
+    keys: transform.sortBy.map(key => normalizedKey(row[key.field], key, index))
+  }));
+  for (let keyIndex = 0; keyIndex < transform.sortBy.length; keyIndex += 1) {
+    const key = transform.sortBy[keyIndex];
+    const types = new Set(decorated.map(entry => entry.keys[keyIndex]).filter(value => !value.missing).map(value => value.type ?? "number"));
+    if (types.size > 1) throw new TypeError(`Sort field "${key.field}" contains mixed non-missing types.`);
+  }
+  decorated.sort((left, right) => {
+    for (let index = 0; index < transform.sortBy.length; index += 1) {
+      const key = transform.sortBy[index];
+      const a = left.keys[index];
+      const b = right.keys[index];
+      if (a.missing || b.missing) {
+        if (a.missing !== b.missing) return a.missing === (key.nulls === "first") ? -1 : 1;
+        continue;
+      }
+      const compared = compareValues(a.value, b.value);
+      if (compared !== 0) return key.order === "ascending" ? compared : -compared;
+    }
+    return left.index - right.index;
+  });
+  return decorated.map(entry => entry.row);
+}