ggaction 0.0.12 → 0.0.13

package/src/grammar/ecdf.js

@@ -0,0 +1,198 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { stableDecimal } from "./numeric.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "field", "groupBy", "weight", "missing", "as", "resolved"
+]);
+const OUTPUT_KEYS = Object.freeze(["value", "cumulative", "probability"]);
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+
+function normalizeGroupBy(groupBy) {
+  const fields = groupBy === undefined
+    ? []
+    : Array.isArray(groupBy) ? [...groupBy] : [groupBy];
+  fields.forEach(field => nonEmptyString(field, "ECDF groupBy field"));
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("ECDF groupBy fields must be distinct.");
+  }
+  return fields;
+}
+
+function validateOutputs(as, occupied) {
+  if (!isPlainObject(as)) throw new TypeError("ECDF as must be a plain object.");
+  const keys = Object.keys(as);
+  if (keys.length !== OUTPUT_KEYS.length ||
+      !OUTPUT_KEYS.every(key => Object.hasOwn(as, key))) {
+    throw new Error("ECDF as requires exactly value, cumulative, and probability.");
+  }
+  const values = OUTPUT_KEYS.map(key => as[key]);
+  values.forEach((field, index) => nonEmptyString(field, `ECDF as.${OUTPUT_KEYS[index]}`));
+  if (new Set(values).size !== values.length) {
+    throw new Error("ECDF output fields must be distinct.");
+  }
+  if (values.some(field => occupied.has(field))) {
+    throw new Error("ECDF output fields must not collide with input or grouping fields.");
+  }
+}
+
+function validateResolved(resolved, groupBy) {
+  if (resolved === undefined) return;
+  if (!isPlainObject(resolved) || !Array.isArray(resolved.groups)) {
+    throw new TypeError("ECDF resolved provenance must contain a groups array.");
+  }
+  for (const group of resolved.groups) {
+    if (!isPlainObject(group) || !isPlainObject(group.keys) ||
+        !Number.isFinite(group.denominator) || group.denominator <= 0 ||
+        !Number.isInteger(group.validCount) || group.validCount <= 0 ||
+        Object.keys(group.keys).length !== groupBy.length ||
+        !groupBy.every(field => Object.hasOwn(group.keys, field))) {
+      throw new TypeError("ECDF resolved group provenance is invalid.");
+    }
+  }
+}
+
+export function validateECDFTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("ECDF transform must be a plain object.");
+  }
+  const unknown = Object.keys(transform).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ECDF transform property "${unknown}".`);
+  }
+  if (transform.type !== "ecdf") {
+    throw new Error(`Unsupported ECDF transform "${transform.type}".`);
+  }
+  nonEmptyString(transform.field, "ECDF field");
+  const groupBy = normalizeGroupBy(transform.groupBy);
+  if (groupBy.includes(transform.field)) {
+    throw new Error("ECDF field must not also be a grouping field.");
+  }
+  if (transform.weight !== undefined) {
+    nonEmptyString(transform.weight, "ECDF weight field");
+    if (transform.weight === transform.field || groupBy.includes(transform.weight)) {
+      throw new Error("ECDF weight field must be distinct from value and grouping fields.");
+    }
+  }
+  if (!["drop", "error"].includes(transform.missing)) {
+    throw new Error('ECDF missing must be "drop" or "error".');
+  }
+  validateOutputs(
+    transform.as,
+    new Set([transform.field, transform.weight, ...groupBy].filter(Boolean))
+  );
+  validateResolved(transform.resolved, groupBy);
+}
+
+export function normalizeECDFTransform({ field, groupBy, weight, missing = "drop", as }) {
+  const transform = {
+    type: "ecdf",
+    field,
+    groupBy: normalizeGroupBy(groupBy),
+    ...(weight === undefined ? {} : { weight }),
+    missing,
+    as
+  };
+  validateECDFTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function groupValue(value) {
+  return typeof value === "string" || typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+function rejectOrDrop(transform, index, reason) {
+  if (transform.missing === "error") {
+    throw new TypeError(`ECDF row ${index} ${reason}.`);
+  }
+  return false;
+}
+
+export function deriveECDF(rows, transform) {
+  if (!Array.isArray(rows)) throw new TypeError("ECDF rows must be an array.");
+  validateECDFTransform(transform);
+  const groups = new Map();
+
+  rows.forEach((row, index) => {
+    if (!isPlainObject(row)) {
+      rejectOrDrop(transform, index, "must be a plain object");
+      return;
+    }
+    const value = row[transform.field];
+    if (!Number.isFinite(value)) {
+      rejectOrDrop(transform, index, `has an invalid value in "${transform.field}"`);
+      return;
+    }
+    const keys = transform.groupBy.map(field => row[field]);
+    if (!keys.every(groupValue)) {
+      rejectOrDrop(transform, index, "has an invalid grouping value");
+      return;
+    }
+    const weight = transform.weight === undefined ? 1 : row[transform.weight];
+    if (!Number.isFinite(weight)) {
+      rejectOrDrop(transform, index, `has an invalid weight in "${transform.weight}"`);
+      return;
+    }
+    if (weight < 0) {
+      throw new RangeError(`ECDF row ${index} has a negative weight.`);
+    }
+    const key = JSON.stringify(keys);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        keys: Object.fromEntries(transform.groupBy.map((field, offset) => [field, keys[offset]])),
+        values: new Map(),
+        denominator: 0,
+        validCount: 0
+      });
+    }
+    const group = groups.get(key);
+    if (weight === 0) return;
+    group.values.set(value, (group.values.get(value) ?? 0) + weight);
+    group.denominator += weight;
+    group.validCount += 1;
+  });
+
+  if (groups.size === 0) {
+    throw new RangeError("ECDF denominator must be greater than zero.");
+  }
+
+  const values = [];
+  const provenance = [];
+  for (const group of groups.values()) {
+    if (!(group.denominator > 0) || !Number.isFinite(group.denominator)) {
+      throw new RangeError("ECDF denominator must be finite and greater than zero.");
+    }
+    const support = [...group.values.keys()].sort((left, right) => left - right);
+    values.push({
+      ...group.keys,
+      [transform.as.value]: support[0],
+      [transform.as.cumulative]: 0,
+      [transform.as.probability]: 0
+    });
+    let cumulative = 0;
+    for (const value of support) {
+      cumulative += group.values.get(value);
+      values.push({
+        ...group.keys,
+        [transform.as.value]: value,
+        [transform.as.cumulative]: stableDecimal(cumulative),
+        [transform.as.probability]: stableDecimal(cumulative / group.denominator)
+      });
+    }
+    provenance.push({
+      keys: group.keys,
+      denominator: stableDecimal(group.denominator),
+      validCount: group.validCount
+    });
+  }
+  return cloneAndFreeze({ values, resolved: { groups: provenance } });
+}
+
+export function resolveECDFTransform(result, transform) {
+  return cloneAndFreeze([{ ...transform, resolved: result.resolved }]);
+}

package/src/grammar/facets/index.js

@@ -18,9 +18,9 @@ const SUPPORTED_BAR_GRAINS = new Set([
 ]);
 const MAX_FACET_CHILDREN = 100;
 
-function requireFacetField(field) {
+function requireFacetField(field, label = "facet") {
   if (typeof field !== "string" || field.length === 0) {
-    throw new TypeError("facet requires a non-empty field.");
+    throw new TypeError(`${label} requires a non-empty field.`);
   }
   return field;
 }
@@ -74,25 +74,52 @@ function uniqueInOrder(values) {
   return [...new Set(values)];
 }
 
-function resolveValues(observed, requested) {
+function resolveValues(observed, requested, label = "facet values") {
   if (requested === undefined) return observed;
   if (!Array.isArray(requested) || requested.length === 0) {
-    throw new TypeError("facet values must be a non-empty array when provided.");
+    throw new TypeError(`${label} must be a non-empty array when provided.`);
   }
   const normalized = readNominalField(
     requested.map(value => ({ value })),
     "value"
   );
   if (new Set(normalized).size !== normalized.length) {
-    throw new Error("facet values must be unique.");
+    throw new Error(`${label} must be unique.`);
   }
   const missing = normalized.find(value => !observed.includes(value));
   if (missing !== undefined) {
-    throw new Error(`facet value ${JSON.stringify(missing)} is not present in the source field.`);
+    throw new Error(
+      `${label} value ${JSON.stringify(missing)} is not present in the source field.`
+    );
   }
   return normalized;
 }
 
+function requireGridRole(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`facetGrid ${label} must be a plain object.`);
+  }
+  const unknown = Object.keys(value).find(key => !["field", "values"].includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown facetGrid ${label} option "${unknown}".`);
+  }
+  return {
+    field: requireFacetField(value.field, `facetGrid ${label}`),
+    ...(value.values === undefined ? {} : { values: value.values })
+  };
+}
+
+function pairKey(row, column) {
+  return JSON.stringify([
+    [typeof row, row],
+    [typeof column, column]
+  ]);
+}
+
+function displayValue(value) {
+  return value === "" ? "(empty)" : String(value);
+}
+
 export function resolveFacetDefinition(semanticSpec, options = {}) {
   if (!isPlainObject(semanticSpec)) {
     throw new TypeError("resolveFacetDefinition requires a semantic spec.");
@@ -136,3 +163,87 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
     }))
   });
 }
+
+export function resolveFacetGridDefinition(semanticSpec, options = {}) {
+  if (!isPlainObject(semanticSpec)) {
+    throw new TypeError("resolveFacetGridDefinition requires a semantic spec.");
+  }
+  if (!isPlainObject(options)) {
+    throw new TypeError("facetGrid options must be a plain object.");
+  }
+  const rows = requireGridRole(options.rows, "rows");
+  const columns = requireGridRole(options.columns, "columns");
+  if (rows.field === columns.field) {
+    throw new Error("facetGrid rows.field and columns.field must be different.");
+  }
+  const combinations = options.combinations ?? "observed";
+  if (!["observed", "full"].includes(combinations)) {
+    throw new Error('facetGrid combinations must be "observed" or "full".');
+  }
+  const id = validateUserId(options.id ?? "facetGrid", "Facet grid id");
+  requireSupportedLayers(semanticSpec);
+  const dependencies = planFacetDependencies(semanticSpec, {
+    field: rows.field,
+    ...(options.data === undefined ? {} : { data: options.data })
+  });
+  const data = dependencies.anchor;
+  const dataset = requirePartitionDataset(semanticSpec, data);
+  const observedRows = readNominalField(dataset.values, rows.field);
+  const observedColumns = readNominalField(dataset.values, columns.field);
+  const rowValues = resolveValues(
+    uniqueInOrder(observedRows), rows.values, "facetGrid rows.values"
+  );
+  const columnValues = resolveValues(
+    uniqueInOrder(observedColumns), columns.values, "facetGrid columns.values"
+  );
+  const observedPairs = new Set(dataset.values.map((_, index) =>
+    pairKey(observedRows[index], observedColumns[index])
+  ));
+  const candidates = rowValues.flatMap((rowValue, row) =>
+    columnValues.map((columnValue, column) => ({
+      row,
+      column,
+      rowValue,
+      columnValue,
+      empty: !observedPairs.has(pairKey(rowValue, columnValue))
+    }))
+  );
+  const selected = combinations === "full"
+    ? candidates
+    : candidates.filter(cell => !cell.empty);
+  if (selected.length === 0) {
+    throw new Error("facetGrid has no observed row and column combinations.");
+  }
+  validateGeneratedItemLimit(
+    selected.length,
+    "Facet grid child count",
+    MAX_FACET_CHILDREN
+  );
+  validateWorkLimit(
+    dataset.values.length * selected.length,
+    "Facet grid partition work"
+  );
+  return cloneAndFreeze({
+    id,
+    data,
+    dependencies,
+    grid: {
+      rows: { field: rows.field, values: rowValues },
+      columns: { field: columns.field, values: columnValues },
+      combinations
+    },
+    cells: selected.map(cell => {
+      const cellId = `${id}-row-${cell.row + 1}-column-${cell.column + 1}`;
+      return {
+        ...cell,
+        id: cellId,
+        data: `${cellId}-data`,
+        value: `${displayValue(cell.rowValue)} · ${displayValue(cell.columnValue)}`,
+        filters: [
+          { field: rows.field, value: cell.rowValue },
+          { field: columns.field, value: cell.columnValue }
+        ]
+      };
+    })
+  });
+}

package/src/grammar/fold.js

@@ -0,0 +1,123 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const TRANSFORM_KEYS = Object.freeze(["type", "fields", "as"]);
+const AS_KEYS = Object.freeze(["key", "value"]);
+const MAX_FIELDS = 64;
+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 normalizeAs(value) {
+  const requested = value ?? {};
+  if (!isPlainObject(requested)) return requested;
+  return {
+    ...requested,
+    key: requested.key ?? "key",
+    value: requested.value ?? "value"
+  };
+}
+
+export function normalizeFoldTransform({ fields, as } = {}) {
+  const transform = {
+    type: "fold",
+    fields: Array.isArray(fields) ? [...fields] : fields,
+    as: normalizeAs(as)
+  };
+  validateFoldTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateFoldTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Fold transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "fold transform");
+  if (transform.type !== "fold") {
+    throw new Error(`Unsupported fold transform "${transform.type}".`);
+  }
+  if (!Array.isArray(transform.fields) || transform.fields.length === 0) {
+    throw new TypeError("Fold fields must be a non-empty array.");
+  }
+  if (transform.fields.length > MAX_FIELDS) {
+    throw new RangeError(`Fold fields cannot contain more than ${MAX_FIELDS} entries.`);
+  }
+  transform.fields.forEach((field, index) => {
+    requireField(field, `Fold fields[${index}]`);
+  });
+  if (new Set(transform.fields).size !== transform.fields.length) {
+    throw new Error("Fold fields must be unique.");
+  }
+  if (!isPlainObject(transform.as)) {
+    throw new TypeError("Fold as must be a plain object.");
+  }
+  rejectUnknownKeys(transform.as, AS_KEYS, "fold as");
+  const key = requireField(transform.as.key, "Fold as.key");
+  const value = requireField(transform.as.value, "Fold as.value");
+  if (key === value) {
+    throw new Error("Fold output fields must be unique.");
+  }
+  return transform;
+}
+
+function valueType(value, field, row) {
+  if (value === null || value === undefined) {
+    throw new TypeError(`Fold field "${field}" is missing at row ${row}.`);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Fold field "${field}" must contain finite numbers.`);
+    }
+    return "number";
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    return typeof value;
+  }
+  throw new TypeError(
+    `Fold field "${field}" must contain finite numbers, strings, or booleans.`
+  );
+}
+
+export function deriveFoldRows(rows, transform) {
+  validateFoldTransform(transform);
+  if (rows.length * transform.fields.length > MAX_OUTPUT_ROWS) {
+    throw new RangeError(`Fold output cannot exceed ${MAX_OUTPUT_ROWS} rows.`);
+  }
+  const sourceFields = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const output of [transform.as.key, transform.as.value]) {
+    if (sourceFields.has(output)) {
+      throw new Error(`Fold output field "${output}" already exists.`);
+    }
+  }
+  let expectedType;
+  const output = [];
+  rows.forEach((row, rowIndex) => {
+    for (const field of transform.fields) {
+      if (!Object.hasOwn(row, field)) {
+        throw new Error(`Fold source does not contain field "${field}" at row ${rowIndex}.`);
+      }
+      const type = valueType(row[field], field, rowIndex);
+      if (expectedType === undefined) expectedType = type;
+      else if (type !== expectedType) {
+        throw new TypeError("Fold fields must contain one common primitive type.");
+      }
+      output.push({
+        ...row,
+        [transform.as.key]: field,
+        [transform.as.value]: row[field]
+      });
+    }
+  });
+  return output;
+}

package/src/grammar/horizon.js

@@ -8,14 +8,15 @@ import { interpolateNumber, inverseLerp } from "./numeric.js";
 import { requireFiniteResult } from "./numeric.js";
 import {
   isNominalValue,
-  normalizeTemporalValue
+  normalizeTemporalValue,
+  resolveTemporalUnit
 } from "./scales/index.js";
 
 export const HORIZON_RESOLUTIONS = Object.freeze(["shared", "independent"]);
 export const HORIZON_MISSING_POLICIES = Object.freeze(["break", "error"]);
 export const HORIZON_OVERFLOW_POLICIES = Object.freeze(["clip", "error"]);
 
-const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType"]);
+const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType", "temporalUnit"]);
 const OUTPUT_PROPERTIES = Object.freeze([
   "x", "lower", "upper", "group", "color", "sign", "band", "segment"
 ]);
@@ -41,7 +42,8 @@ function validateEncoding(value, role) {
       `Horizon ${role} fieldType must be quantitative${supportsTemporal ? " or temporal" : ""}.`
     );
   }
-  return { field, fieldType };
+  const temporalUnit = resolveTemporalUnit(value, fieldType);
+  return { field, fieldType, ...(temporalUnit === undefined ? {} : { temporalUnit }) };
 }
 
 function validateOutputFields(value) {
@@ -183,7 +185,7 @@ export function validateHorizonTransform(transform) {
 
 function orderedX(value, encoding, rowIndex) {
   if (encoding.fieldType === "temporal") {
-    return normalizeTemporalValue(value, encoding.field, rowIndex);
+    return normalizeTemporalValue(value, encoding.field, rowIndex, encoding.temporalUnit);
   }
   if (!Number.isFinite(value)) {
     throw new TypeError(

package/src/grammar/interval.js

@@ -1,7 +1,10 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
 import { requireFiniteResult, stableDecimal } from "./numeric.js";
-import { studentTCriticalValue } from "./statistics/studentT.js";
+import {
+  confidenceCriticalValue,
+  normalizeConfidenceInterval
+} from "./statistics/confidenceInterval.js";
 
 const CENTER_VALUES = ["mean", "median"];
 const EXTENT_VALUES = ["stderr", "stdev", "ci", "iqr"];
@@ -11,6 +14,7 @@ const TRANSFORM_KEYS = [
   "groupBy",
   "center",
   "extent",
+  "method",
   "level",
   "as"
 ];
@@ -84,13 +88,12 @@ export function validateIntervalTransform(transform) {
     throw new Error("Median intervals require iqr, and iqr requires median.");
   }
   if (transform.extent === "ci") {
-    if (
-      !Number.isFinite(transform.level) ||
-      transform.level <= 0 ||
-      transform.level >= 1
-    ) {
-      throw new RangeError("Interval CI level must be between 0 and 1.");
-    }
+    normalizeConfidenceInterval(transform, {
+      defaultMethod: "student-t",
+      label: "Interval CI"
+    });
+  } else if (transform.method !== undefined) {
+    throw new Error("Interval method is supported only for ci extent.");
   } else if (transform.level !== undefined) {
     throw new Error("Interval level is supported only for ci extent.");
   }
@@ -111,16 +114,27 @@ function normalizeGrouping(groupBy) {
 export function normalizeIntervalParameters({
   center = "mean",
   extent = "ci",
+  method,
   level
 } = {}) {
-  const resolvedLevel = extent === "ci" ? level ?? 0.95 : level;
+  const confidence = extent === "ci"
+    ? normalizeConfidenceInterval({ method, level }, {
+        defaultMethod: "student-t",
+        label: "Interval CI"
+      })
+    : undefined;
   const candidate = {
     type: "interval",
     field: "__interval_input",
     groupBy: [],
     center,
     extent,
-    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel }),
+    ...(confidence === undefined
+      ? {
+          ...(method === undefined ? {} : { method }),
+          ...(level === undefined ? {} : { level })
+        }
+      : confidence),
     as: {
       center: "__interval_center",
       lower: "__interval_lower",
@@ -131,18 +145,16 @@ export function normalizeIntervalParameters({
   return cloneAndFreeze({
     center,
     extent,
-    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel })
+    ...(confidence === undefined ? {} : confidence)
   });
 }
 
 export function studentTCritical(degreesOfFreedom, level) {
-  if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
-    throw new RangeError("Student-t degreesOfFreedom must be a positive integer.");
-  }
-  if (!Number.isFinite(level) || level <= 0 || level >= 1) {
-    throw new RangeError("Student-t level must be between 0 and 1.");
-  }
-  return studentTCriticalValue(level, degreesOfFreedom);
+  return confidenceCriticalValue({
+    method: "student-t",
+    level,
+    degreesOfFreedom
+  });
 }
 
 function isMissing(value) {
@@ -170,7 +182,11 @@ function deriveGroup(values, transform) {
     ? aggregateScalarValues(values, "stdev")
     : transform.extent === "stderr"
       ? aggregateScalarValues(values, "stderr")
-      : studentTCritical(values.length - 1, transform.level) *
+      : confidenceCriticalValue({
+          method: transform.method,
+          level: transform.level,
+          degreesOfFreedom: values.length - 1
+        }) *
         aggregateScalarValues(values, "stderr");
   return {
     center,
@@ -232,12 +248,13 @@ export function normalizeIntervalTransform({
   groupBy,
   center,
   extent,
+  method,
   level,
   as
 }) {
   nonEmptyString(field, "Interval field");
   const grouping = normalizeGrouping(groupBy);
-  const parameters = normalizeIntervalParameters({ center, extent, level });
+  const parameters = normalizeIntervalParameters({ center, extent, method, level });
   const transform = {
     type: "interval",
     field,