ggaction 0.0.13 → 0.0.15

package/src/grammar/facets/index.js

@@ -4,18 +4,8 @@ import {
   validateGeneratedItemLimit,
   validateWorkLimit
 } from "../../core/validation.js";
-import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
-import { planFacetDependencies } from "./dependencies.js";
+import { planFacetDependencies, resolveFacetFamily } from "./dependencies.js";
 import { readNominalField } from "../scales/index.js";
-
-const SUPPORTED_MARKS = new Set([
-  "point", "line", "area", "bar", "rule", "tick", "rect"
-]);
-const SUPPORTED_BAR_GRAINS = new Set([
-  BAR_GRAINS.histogram,
-  BAR_GRAINS.aggregate,
-  BAR_GRAINS.ranged
-]);
 const MAX_FACET_CHILDREN = 100;
 
 function requireFacetField(field, label = "facet") {
@@ -25,40 +15,6 @@ function requireFacetField(field, label = "facet") {
   return field;
 }
 
-function requireSupportedLayer(layer) {
-  if (!SUPPORTED_MARKS.has(layer.mark?.type)) {
-    throw new Error(
-      `facet does not support mark "${layer.id}" of type ${layer.mark?.type ?? "incomplete"}.`
-    );
-  }
-  if (
-    layer.mark.type === "bar" &&
-    !SUPPORTED_BAR_GRAINS.has(resolveBarGrain(layer))
-  ) {
-    throw new Error(
-      `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
-    );
-  }
-  if (
-    layer.encoding?.x?.scale === undefined ||
-    layer.encoding?.y?.scale === undefined
-  ) {
-    throw new Error(
-      `Facet layer "${layer.id}" must be a complete materializable Cartesian mark.`
-    );
-  }
-  if (typeof layer.data !== "string" || layer.data.length === 0) {
-    throw new Error(`Facet layer "${layer.id}" requires a dataset.`);
-  }
-}
-
-function requireSupportedLayers(semanticSpec) {
-  if (!Array.isArray(semanticSpec.layers) || semanticSpec.layers.length === 0) {
-    throw new Error("facet requires at least one materializable layer.");
-  }
-  for (const layer of semanticSpec.layers) requireSupportedLayer(layer);
-}
-
 function requirePartitionDataset(semanticSpec, id) {
   const dataset = semanticSpec.datasets?.find(candidate => candidate.id === id);
   if (dataset === undefined) {
@@ -129,9 +85,10 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
   }
   const field = requireFacetField(options.field);
   const id = validateUserId(options.id ?? "facet", "Facet id");
-  requireSupportedLayers(semanticSpec);
+  const family = resolveFacetFamily(semanticSpec);
   const dependencies = planFacetDependencies(semanticSpec, {
     field,
+    family,
     ...(options.data === undefined ? {} : { data: options.data })
   });
   const data = dependencies.anchor;
@@ -152,6 +109,7 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
   );
   return cloneAndFreeze({
     id,
+    family: family.family,
     data,
     field,
     values,
@@ -181,9 +139,10 @@ export function resolveFacetGridDefinition(semanticSpec, options = {}) {
     throw new Error('facetGrid combinations must be "observed" or "full".');
   }
   const id = validateUserId(options.id ?? "facetGrid", "Facet grid id");
-  requireSupportedLayers(semanticSpec);
+  const family = resolveFacetFamily(semanticSpec);
   const dependencies = planFacetDependencies(semanticSpec, {
     field: rows.field,
+    family,
     ...(options.data === undefined ? {} : { data: options.data })
   });
   const data = dependencies.anchor;
@@ -225,6 +184,7 @@ export function resolveFacetGridDefinition(semanticSpec, options = {}) {
   );
   return cloneAndFreeze({
     id,
+    family: family.family,
     data,
     dependencies,
     grid: {

package/src/grammar/facets/scales.js

@@ -3,6 +3,7 @@ import {
   FACET_SCALE_CHANNELS,
   FACET_SCALE_RESOLUTIONS
 } from "../../core/vocabulary.js";
+import { collectFacetScaleBindings } from "./dependencies.js";
 import { resolveHistogramBins } from "../histogram.js";
 import {
   hasOrdinalDomain,
@@ -63,30 +64,25 @@ function normalizeRequestedPolicies(requested) {
 
 function usedScaleChannels(semanticSpec, scales) {
   const used = new Map();
-  for (const layer of semanticSpec.layers) {
-    for (const channel of FACET_SCALE_CHANNELS) {
-      const id = layer.encoding?.[channel]?.scale;
-      if (id === undefined) continue;
-      if (!scales.has(id)) {
-        throw new Error(
-          `Facet layer "${layer.id}" references missing scale "${id}".`
-        );
-      }
-      if (!used.has(id)) used.set(id, new Set());
-      used.get(id).add(channel);
+  const bindings = collectFacetScaleBindings(semanticSpec);
+  for (const binding of bindings) {
+    if (!scales.has(binding.scaleId)) {
+      throw new Error(
+        `Facet layer "${binding.layerId}" references missing scale "${binding.scaleId}".`
+      );
     }
+    if (!used.has(binding.scaleId)) used.set(binding.scaleId, new Set());
+    used.get(binding.scaleId).add(binding.policyKey);
   }
-  return used;
+  return { used, bindings };
 }
 
 export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
   const scales = requireScaleDefinitions(semanticSpec);
   const channels = normalizeRequestedPolicies(requested);
-  const used = usedScaleChannels(semanticSpec, scales);
+  const { used, bindings } = usedScaleChannels(semanticSpec, scales);
   for (const channel of Object.keys(requested)) {
-    const applicable = semanticSpec.layers.some(
-      layer => layer.encoding?.[channel]?.scale !== undefined
-    );
+    const applicable = bindings.some(binding => binding.policyKey === channel);
     if (!applicable) {
       throw new Error(
         `Facet scale channel "${channel}" is not used by an affected layer.`
@@ -107,7 +103,7 @@ export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
       channels: attached
     };
   }
-  return cloneAndFreeze({ channels, scales: scalePolicies });
+  return cloneAndFreeze({ channels, scales: scalePolicies, bindings });
 }
 
 function requireChildDomains(resolvedByChild, scaleId) {
@@ -210,7 +206,8 @@ export function resolveFacetScaleDomains(
   }
   return cloneAndFreeze({
     channels: normalized.channels,
-    scales: resolved
+    scales: resolved,
+    bindings: normalized.bindings
   });
 }
 

package/src/grammar/impute.js

@@ -0,0 +1,340 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { interpolateNumber, inverseLerp } from "./numeric.js";
+import { normalizeTemporalValue } from "./scales/fields.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "fields", "groupBy", "sortBy", "method", "value", "edges", "maxGap"
+]);
+const SORT_KEYS = Object.freeze(["field", "order"]);
+const METHODS = Object.freeze(["constant", "forward", "backward", "linear"]);
+
+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 validateFieldList(value, label) {
+  if (!Array.isArray(value) || value.length === 0 || value.some(field =>
+    typeof field !== "string" || field.length === 0
+  )) {
+    throw new TypeError(`${label} must be a non-empty field array.`);
+  }
+  if (new Set(value).size !== value.length) throw new Error(`${label} fields must be unique.`);
+}
+
+function normalizeFieldList(value, { allowEmpty = false } = {}) {
+  if (value === undefined) return allowEmpty ? [] : value;
+  return Array.isArray(value) ? [...value] : [value];
+}
+
+function normalizeSortBy(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return value;
+  return value.map(sort => isPlainObject(sort)
+    ? { ...sort, order: sort.order ?? "ascending" }
+    : sort
+  );
+}
+
+function validateSortBy(sortBy) {
+  if (!Array.isArray(sortBy)) throw new TypeError("Impute sortBy must be an array.");
+  const fields = [];
+  sortBy.forEach((sort, index) => {
+    if (!isPlainObject(sort)) {
+      throw new TypeError(`Impute sortBy[${index}] must be a plain object.`);
+    }
+    rejectUnknownKeys(sort, SORT_KEYS, `impute sortBy[${index}]`);
+    fields.push(requireField(sort.field, `Impute sortBy[${index}].field`));
+    if (!["ascending", "descending"].includes(sort.order)) {
+      throw new Error(`Unsupported impute sort order "${sort.order}".`);
+    }
+  });
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("Impute sortBy fields must be unique.");
+  }
+}
+
+function scalarType(value, label) {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === "string" || typeof value === "boolean") return typeof value;
+  if (typeof value === "number" && Number.isFinite(value)) return "number";
+  throw new TypeError(`${label} must contain scalar values; NaN and Infinity are invalid.`);
+}
+
+function scalarKey(value, label) {
+  const type = scalarType(value, label);
+  if (type === undefined) return "null";
+  if (type === "number") return `number:${Object.is(value, -0) ? 0 : value}`;
+  if (type === "string") return `string:${value.length}:${value}`;
+  return `${type}:${value}`;
+}
+
+export function validateImputeTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Impute transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "impute transform");
+  if (transform.type !== "impute") {
+    throw new Error(`Unsupported impute transform "${transform.type}".`);
+  }
+  validateFieldList(transform.fields, "Impute fields");
+  if (!Array.isArray(transform.groupBy) || transform.groupBy.some(field =>
+    typeof field !== "string" || field.length === 0
+  )) {
+    throw new TypeError("Impute groupBy must contain field names.");
+  }
+  if (new Set(transform.groupBy).size !== transform.groupBy.length) {
+    throw new Error("Impute groupBy fields must be unique.");
+  }
+  validateSortBy(transform.sortBy);
+  if (!METHODS.includes(transform.method)) {
+    throw new Error(`Unsupported impute method "${transform.method}".`);
+  }
+  const hasValue = Object.hasOwn(transform, "value");
+  if (transform.method === "constant") {
+    if (!hasValue) throw new TypeError("Impute constant requires a value.");
+    if (transform.value === undefined) {
+      throw new TypeError("Impute constant value must be a JSON-safe scalar.");
+    }
+    scalarType(transform.value, "Impute constant value");
+  } else {
+    if (hasValue) throw new Error(`Impute value is not available for ${transform.method}.`);
+    if (transform.sortBy.length === 0) {
+      throw new Error(`Impute ${transform.method} requires non-empty sortBy.`);
+    }
+  }
+  if (transform.method === "linear") {
+    if (transform.sortBy.length !== 1 || transform.sortBy[0].order !== "ascending") {
+      throw new Error("Impute linear requires exactly one ascending sortBy field.");
+    }
+  }
+  if (!['keep', 'error'].includes(transform.edges)) {
+    throw new Error(`Unsupported impute edges policy "${transform.edges}".`);
+  }
+  if (transform.maxGap !== undefined &&
+    (!Number.isSafeInteger(transform.maxGap) || transform.maxGap <= 0)) {
+    throw new RangeError("Impute maxGap must be a positive safe integer.");
+  }
+  return transform;
+}
+
+export function normalizeImputeTransform(args = {}) {
+  const transform = {
+    type: "impute",
+    fields: normalizeFieldList(args.fields),
+    groupBy: normalizeFieldList(args.groupBy, { allowEmpty: true }),
+    sortBy: normalizeSortBy(args.sortBy),
+    method: args.method,
+    edges: args.edges ?? "keep"
+  };
+  if (Object.hasOwn(args, "value")) transform.value = args.value;
+  if (Object.hasOwn(args, "maxGap")) transform.maxGap = args.maxGap;
+  validateImputeTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function compareScalar(left, right, label) {
+  const leftType = scalarType(left, label);
+  const rightType = scalarType(right, label);
+  if (leftType === undefined || rightType === undefined) {
+    if (leftType === rightType) return 0;
+    return leftType === undefined ? 1 : -1;
+  }
+  if (leftType !== rightType) throw new TypeError(`${label} must contain one scalar type.`);
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function compareEntries(left, right, sortBy) {
+  for (const sort of sortBy) {
+    const comparison = compareScalar(
+      left.row[sort.field], right.row[sort.field], `Impute sort field "${sort.field}"`
+    );
+    if (comparison !== 0) return sort.order === "ascending" ? comparison : -comparison;
+  }
+  return left.index - right.index;
+}
+
+function validateRows(rows, transform) {
+  if (!Array.isArray(rows) || !rows.every(isPlainObject)) {
+    throw new TypeError("Impute source rows must be plain objects.");
+  }
+  const required = [...transform.fields, ...transform.groupBy,
+    ...transform.sortBy.map(sort => sort.field)];
+  rows.forEach((row, index) => {
+    for (const field of required) {
+      if (!Object.hasOwn(row, field)) {
+        throw new Error(`Impute source does not contain field "${field}" at row ${index}.`);
+      }
+    }
+    for (const field of transform.fields) {
+      scalarType(row[field], `Impute field "${field}" at row ${index}`);
+    }
+    for (const field of transform.groupBy) {
+      scalarKey(row[field], `Impute group field "${field}" at row ${index}`);
+    }
+    for (const sort of transform.sortBy) {
+      scalarType(row[sort.field], `Impute sort field "${sort.field}" at row ${index}`);
+    }
+  });
+}
+
+function partitions(entries, transform) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = transform.groupBy.length === 0 ? "all" : transform.groupBy.map(field =>
+      scalarKey(entry.row[field], `Impute group field "${field}"`)
+    ).join("\0");
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(entry);
+  }
+  return [...groups.values()];
+}
+
+function validateFieldTypes(entries, transform) {
+  for (const field of transform.fields) {
+    const types = new Set(entries.flatMap(entry => {
+      const type = scalarType(entry.row[field], `Impute field "${field}"`);
+      return type === undefined ? [] : [type];
+    }));
+    const constantType = transform.method === "constant"
+      ? scalarType(transform.value, "Impute constant value")
+      : undefined;
+    if (constantType !== undefined) types.add(constantType);
+    if (types.size > 1) {
+      throw new TypeError(`Impute field "${field}" must contain one scalar type.`);
+    }
+    if (transform.method === "linear" &&
+      (types.size > 0 && !types.has("number"))) {
+      throw new TypeError(`Impute linear field "${field}" must contain finite numbers.`);
+    }
+  }
+}
+
+function validateSortFieldTypes(partition, transform) {
+  for (const sort of transform.sortBy) {
+    const types = new Set(partition.flatMap(entry => {
+      const type = scalarType(
+        entry.row[sort.field],
+        `Impute sort field "${sort.field}"`
+      );
+      return type === undefined ? [] : [type];
+    }));
+    if (types.size > 1) {
+      throw new TypeError(`Impute sort field "${sort.field}" must contain one scalar type.`);
+    }
+  }
+}
+
+function linearPositions(partition, transform) {
+  if (transform.method !== "linear") return undefined;
+  const field = transform.sortBy[0].field;
+  const types = new Set(partition.map((entry, index) =>
+    scalarType(entry.row[field], `Impute linear sort field "${field}" at row ${index}`)
+  ));
+  if (types.size !== 1 || types.has(undefined) ||
+    !["number", "string"].includes([...types][0])) {
+    throw new TypeError("Impute linear sort field must contain one numeric or temporal-string type.");
+  }
+  const type = [...types][0];
+  const positions = partition.map((entry, index) => type === "number"
+    ? entry.row[field]
+    : normalizeTemporalValue(entry.row[field], field, index, "auto")
+  );
+  for (let index = 1; index < positions.length; index += 1) {
+    if (positions[index] === positions[index - 1]) {
+      throw new Error("Impute linear sort positions must be unique.");
+    }
+  }
+  return positions;
+}
+
+function missingRuns(partition, field) {
+  const runs = [];
+  let start;
+  for (let index = 0; index <= partition.length; index += 1) {
+    const missing = index < partition.length &&
+      (partition[index].row[field] === null || partition[index].row[field] === undefined);
+    if (missing && start === undefined) start = index;
+    if (!missing && start !== undefined) {
+      runs.push([start, index - 1]);
+      start = undefined;
+    }
+  }
+  return runs;
+}
+
+function setField(row, field, value) {
+  Object.defineProperty(row, field, {
+    value, enumerable: true, writable: true, configurable: true
+  });
+}
+
+function fillRun(partition, field, run, transform, positions) {
+  const [start, end] = run;
+  const length = end - start + 1;
+  if (transform.maxGap !== undefined && length > transform.maxGap) return;
+  if (transform.method === "constant") {
+    for (let index = start; index <= end; index += 1) {
+      setField(partition[index].row, field, transform.value);
+    }
+    return;
+  }
+  const left = start - 1;
+  const right = end + 1;
+  const hasLeft = left >= 0;
+  const hasRight = right < partition.length;
+  const usable = transform.method === "forward" ? hasLeft
+    : transform.method === "backward" ? hasRight
+      : hasLeft && hasRight;
+  if (!usable) {
+    if (transform.edges === "error") {
+      throw new RangeError(`Impute ${transform.method} cannot fill an edge run in field "${field}".`);
+    }
+    return;
+  }
+  if (transform.method === "forward" || transform.method === "backward") {
+    const anchor = transform.method === "forward" ? left : right;
+    const value = partition[anchor].row[field];
+    for (let index = start; index <= end; index += 1) {
+      setField(partition[index].row, field, value);
+    }
+    return;
+  }
+  const leftValue = partition[left].row[field];
+  const rightValue = partition[right].row[field];
+  for (let index = start; index <= end; index += 1) {
+    const proportion = inverseLerp(positions[index], positions[left], positions[right]);
+    setField(
+      partition[index].row,
+      field,
+      interpolateNumber(leftValue, rightValue, proportion)
+    );
+  }
+}
+
+export function deriveImputedRows(rows, transform) {
+  validateImputeTransform(transform);
+  validateRows(rows, transform);
+  const entries = rows.map((row, index) => ({ index, row: { ...row } }));
+  validateFieldTypes(entries, transform);
+  const groups = partitions(entries, transform);
+  for (const partition of groups) {
+    validateSortFieldTypes(partition, transform);
+    partition.sort((left, right) => compareEntries(left, right, transform.sortBy));
+    const positions = linearPositions(partition, transform);
+    for (const field of transform.fields) {
+      for (const run of missingRuns(partition, field)) {
+        fillRun(partition, field, run, transform, positions);
+      }
+    }
+  }
+  return cloneAndFreeze(entries.sort((a, b) => a.index - b.index).map(entry => entry.row));
+}

package/src/grammar/markLabelSelection.js

@@ -0,0 +1,57 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+import { normalizeMarkSelector } from "./markSelection.js";
+
+function hasOwn(value, key) {
+  return Object.hasOwn(value, key);
+}
+
+function normalizeNamedSelection(id) {
+  return cloneAndFreeze({
+    kind: "named",
+    id: validateUserId(id, "Label selection id")
+  });
+}
+
+function normalizeInlineSelection(selector) {
+  return cloneAndFreeze({
+    kind: "inline",
+    selector: normalizeMarkSelector(selector)
+  });
+}
+
+export function normalizeLabelSelectionCreate(options) {
+  if (!isPlainObject(options)) {
+    throw new TypeError("createMarkLabels options must be a plain object.");
+  }
+  const hasSelect = hasOwn(options, "select");
+  const hasSelection = hasOwn(options, "selection");
+  if (hasSelect && hasSelection) {
+    throw new Error("createMarkLabels accepts select or selection, not both.");
+  }
+  if (hasSelect) return normalizeInlineSelection(options.select);
+  if (hasSelection) return normalizeNamedSelection(options.selection);
+  return cloneAndFreeze({ kind: "all" });
+}
+
+export function normalizeLabelSelectionEdit(options) {
+  if (!isPlainObject(options)) {
+    throw new TypeError("editMarkLabelSelection options must be a plain object.");
+  }
+  const requested = ["select", "selection", "all"].filter(key =>
+    hasOwn(options, key)
+  );
+  if (requested.length !== 1) {
+    throw new Error(
+      "editMarkLabelSelection requires exactly one of select, selection, or all."
+    );
+  }
+  if (requested[0] === "select") return normalizeInlineSelection(options.select);
+  if (requested[0] === "selection") {
+    return normalizeNamedSelection(options.selection);
+  }
+  if (options.all !== true) {
+    throw new TypeError("editMarkLabelSelection all must be true.");
+  }
+  return cloneAndFreeze({ kind: "all" });
+}

package/src/grammar/markLabels.js

@@ -1,6 +1,11 @@
 import { aggregateRows } from "./aggregate.js";
 import { BAR_GRAINS, resolveBarChannels, resolveBarGrain } from "./bars/policy.js";
 import { stableFiniteSum } from "./numeric.js";
+import {
+  readStatisticalWeights,
+  statisticalWeightTotal,
+  summarizeStatisticalWeights
+} from "./weightedStatistics.js";
 
 const CONTENTS = new Set(["category", "value", "share"]);
 const NORMALIZATIONS = new Set(["source", "category"]);
@@ -44,7 +49,19 @@ export function normalizeMarkLabelContent(source, { content, normalizeBy }) {
 
 function itemValue(source, item) {
   if (source.mark.type === "bar") {
-    if (resolveBarGrain(source) === BAR_GRAINS.histogram) return item.members.length;
+    if (resolveBarGrain(source) === BAR_GRAINS.histogram) {
+      const weight = source.encoding.x.weight;
+      if (weight === undefined || item.members.length === 0) return item.members.length;
+      const weighted = readStatisticalWeights(item.members, weight, "Histogram label");
+      return statisticalWeightTotal(
+        summarizeStatisticalWeights(
+          weighted.entries,
+          weighted.definition.kind,
+          "Histogram label"
+        ),
+        "Histogram label value"
+      );
+    }
     const measure = source.encoding[resolveBarChannels(source).measure];
     return measure.aggregate === "count" ? item.members.length
       : aggregateRows(item.members, measure.field, measure.aggregate);