ggaction 0.0.13 → 0.0.16

package/src/grammar/density.js

@@ -10,6 +10,15 @@ import {
   requireFiniteResult,
   stableFiniteDeviation
 } from "./numeric.js";
+import {
+  normalizeStatisticalWeight,
+  readStatisticalWeights,
+  summarizeStatisticalWeights,
+  validateWeightedNumericFields,
+  weightedBandwidth,
+  weightedEntriesExtent,
+  weightedKernelEstimate
+} from "./weightedStatistics.js";
 
 const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
 
@@ -37,6 +46,25 @@ export const DENSITY_WIDTH_RESOLUTIONS = Object.freeze([
   "shared", "independent"
 ]);
 
+export function normalizeDensityTransform(args = {}) {
+  const transform = {
+    type: "density",
+    field: args.field,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bandwidth: args.bandwidth ?? "auto",
+    extent: args.extent ?? "auto",
+    steps: args.steps ?? 100,
+    kernel: args.kernel ?? "gaussian",
+    normalization: args.normalization ?? "unit",
+    as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
+    resolve: args.resolve ?? "shared",
+    ...(args.weight === undefined ? {} : { weight: args.weight }),
+    ...(args.placement === undefined ? {} : { placement: args.placement })
+  };
+  validateDensityTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
 export function validateDensitySteps(value, label = "Density steps") {
   if (!Number.isInteger(value) || value < 2) {
     throw new RangeError(`${label} must be an integer of at least 2.`);
@@ -261,10 +289,88 @@ function validateStoredDensityPlacement(value, groupBy) {
   return value;
 }
 
+function validateResolvedBandwidths(value, transform) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError(
+      "Density resolved bandwidths must be a non-empty array."
+    );
+  }
+  const normalized = value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} must be a plain object.`
+      );
+    }
+    const unknown = Object.keys(item).find(
+      key => !["group", "split", "bandwidth"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(
+        `Unknown density resolved bandwidth property "${unknown}".`
+      );
+    }
+    if (!Number.isFinite(item.bandwidth) || item.bandwidth <= 0) {
+      throw new RangeError(
+        `Density resolved bandwidth ${index} must be positive and finite.`
+      );
+    }
+    if (transform.groupBy === undefined) {
+      if (Object.hasOwn(item, "group")) {
+        throw new Error(
+          "Density resolved bandwidth cannot store a group without groupBy."
+        );
+      }
+    } else if (!Object.hasOwn(item, "group") || !isNominalValue(item.group)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} requires a nominal group.`
+      );
+    }
+    if (transform.placement?.split === undefined) {
+      if (Object.hasOwn(item, "split")) {
+        throw new Error(
+          "Density resolved bandwidth cannot store a split without split placement."
+        );
+      }
+    } else if (!Object.hasOwn(item, "split") || !isNominalValue(item.split)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} requires a nominal split.`
+      );
+    }
+    return item;
+  });
+  for (let index = 0; index < normalized.length; index += 1) {
+    const duplicate = normalized.slice(0, index).some(item =>
+      Object.is(item.group, normalized[index].group) &&
+      Object.is(item.split, normalized[index].split)
+    );
+    if (duplicate) {
+      throw new Error(
+        `Density resolved bandwidth ${index} duplicates an earlier profile.`
+      );
+    }
+  }
+  return value;
+}
+
+function hasValidResolvedBandwidthState(resolved, transform) {
+  const hasBandwidth = Object.hasOwn(resolved, "bandwidth");
+  const hasBandwidths = Object.hasOwn(resolved, "bandwidths");
+  if (hasBandwidth === hasBandwidths) return false;
+  if (hasBandwidth) {
+    return Number.isFinite(resolved.bandwidth) && resolved.bandwidth > 0;
+  }
+  try {
+    validateResolvedBandwidths(resolved.bandwidths, transform);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function validateDensityTransform(transform) {
   const supported = [
     "type", "field", "groupBy", "bandwidth", "extent", "steps", "as",
-    "resolve", "kernel", "normalization", "placement", "resolved"
+    "resolve", "kernel", "normalization", "placement", "weight", "resolved"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
@@ -274,6 +380,9 @@ export function validateDensityTransform(transform) {
     throw new Error(`Unsupported density transform "${transform.type}".`);
   }
   requireField(transform.field, "Density field");
+  if (transform.weight !== undefined) {
+    normalizeStatisticalWeight(transform.weight, "Density weight");
+  }
   if (transform.groupBy !== undefined) {
     requireField(transform.groupBy, "Density groupBy");
   }
@@ -301,10 +410,9 @@ export function validateDensityTransform(transform) {
       typeof resolved !== "object" ||
       Array.isArray(resolved) ||
       Object.keys(resolved).some(
-        key => !["bandwidth", "extent", "splitDomain"].includes(key)
+        key => !["bandwidth", "bandwidths", "extent", "splitDomain"].includes(key)
       ) ||
-      !Number.isFinite(resolved.bandwidth) ||
-      resolved.bandwidth <= 0 ||
+      !hasValidResolvedBandwidthState(resolved, transform) ||
       !Array.isArray(resolved.extent) ||
       resolved.extent.length !== 2 ||
       !resolved.extent.every(Number.isFinite) ||
@@ -319,7 +427,7 @@ export function validateDensityTransform(transform) {
       })())
     ) {
       throw new TypeError(
-        "Density resolved provenance requires a positive bandwidth, ascending finite extent, and optional two-value split domain."
+        "Density resolved provenance requires one positive bandwidth or profile bandwidth list, an ascending finite extent, and an optional two-value split domain."
       );
     }
   }
@@ -363,22 +471,26 @@ export function estimateDensityBandwidth(values) {
   return bandwidth;
 }
 
-function resolveBandwidth(value, sourceValues) {
+function resolveBandwidth(value, sourceValues, weightSummary, field) {
   if (value === undefined || value === "auto") {
-    return estimateDensityBandwidth(sourceValues);
+    return weightSummary === undefined
+      ? estimateDensityBandwidth(sourceValues)
+      : weightedBandwidth(weightSummary, field);
   }
   return validateDensityBandwidth(value);
 }
 
-function resolveExtent(value, sourceValues) {
+function resolveExtent(value, sourceValues, weightSummary, field) {
   if (value === undefined || value === "auto") {
-    let lower = Infinity;
-    let upper = -Infinity;
-    for (const sourceValue of sourceValues) {
-      lower = Math.min(lower, sourceValue);
-      upper = Math.max(upper, sourceValue);
-    }
-    const extent = [lower, upper];
+    const extent = weightSummary === undefined
+      ? sourceValues.reduce(
+          ([lower, upper], sourceValue) => [
+            Math.min(lower, sourceValue),
+            Math.max(upper, sourceValue)
+          ],
+          [Infinity, -Infinity]
+        )
+      : weightedEntriesExtent(weightSummary, field);
     if (extent[0] === extent[1]) {
       throw new Error("Density observed extent requires varying finite values.");
     }
@@ -407,6 +519,17 @@ function estimateAt(sample, values, bandwidth, kernel, normalization) {
   return requireFiniteResult(stable, "Density estimate");
 }
 
+function estimateWeightedAt(sample, summary, field, bandwidth, kernel, normalization) {
+  return weightedKernelEstimate(
+    summary,
+    field,
+    sample,
+    bandwidth,
+    KERNEL_FUNCTIONS[kernel],
+    normalization
+  );
+}
+
 export function deriveKernelDensity(values, {
   field,
   groupBy,
@@ -416,7 +539,8 @@ export function deriveKernelDensity(values, {
   kernel = "gaussian",
   normalization = "unit",
   as,
-  placement
+  placement,
+  weight
 } = {}) {
   if (!Array.isArray(values)) {
     throw new TypeError("Density values must be an array.");
@@ -437,29 +561,66 @@ export function deriveKernelDensity(values, {
   )];
   const resolvedKernel = validateDensityKernel(kernel);
   const resolvedNormalization = validateDensityNormalization(normalization);
-  const validRows = values.filter(row =>
-    row !== null &&
-    typeof row === "object" &&
-    Number.isFinite(row[sourceField]) &&
-    (groupField === undefined || isNominalValue(row[groupField])) &&
-    (placement?.split === undefined || isNominalValue(row[placement.split.field]))
-  );
+  const statisticalWeights = weight === undefined
+    ? undefined
+    : readStatisticalWeights(values, weight, "Density");
+  if (statisticalWeights !== undefined) {
+    validateWeightedNumericFields(
+      statisticalWeights.entries,
+      [sourceField],
+      "Density"
+    );
+  }
+  const validEntries = statisticalWeights === undefined
+    ? undefined
+    : statisticalWeights.entries.filter(entry =>
+        (groupField === undefined || isNominalValue(entry.row[groupField])) &&
+        (placement?.split === undefined ||
+          isNominalValue(entry.row[placement.split.field]))
+      );
+  const validRows = statisticalWeights === undefined
+    ? values.filter(row =>
+        row !== null &&
+        typeof row === "object" &&
+        Number.isFinite(row[sourceField]) &&
+        (groupField === undefined || isNominalValue(row[groupField])) &&
+        (placement?.split === undefined || isNominalValue(row[placement.split.field]))
+      )
+    : validEntries.map(entry => entry.row);
   if (validRows.length === 0) {
     throw new Error("Density requires at least one valid field/group row.");
   }
-  validateWorkLimit(validRows.length * steps, "Density computation");
-  const sourceValues = validRows.map(row => row[sourceField]);
-  const resolvedBandwidth = resolveBandwidth(bandwidth, sourceValues);
-  const resolvedExtent = resolveExtent(extent, sourceValues);
+  const globalWeightSummary = statisticalWeights === undefined
+    ? undefined
+    : summarizeStatisticalWeights(
+        validEntries,
+        statisticalWeights.definition.kind,
+        "Density data"
+      );
+  validateWorkLimit(
+    (globalWeightSummary?.positive.length ?? validRows.length) * steps,
+    "Density computation"
+  );
+  const sourceValues = globalWeightSummary === undefined
+    ? validRows.map(row => row[sourceField])
+    : globalWeightSummary.positive.map(entry => entry.row[sourceField]);
+  const resolvedExtent = resolveExtent(
+    extent,
+    sourceValues,
+    globalWeightSummary,
+    sourceField
+  );
   const groupedValues = new Map();
-  for (const row of validRows) {
+  const groupedSource = statisticalWeights === undefined ? validRows : validEntries;
+  for (const source of groupedSource) {
+    const row = statisticalWeights === undefined ? source : source.row;
     const group = groupField === undefined ? undefined : row[groupField];
     const split = placement?.split === undefined
       ? undefined
       : row[placement.split.field];
     const bySplit = groupedValues.get(group) ?? new Map();
     const groupValues = bySplit.get(split) ?? [];
-    groupValues.push(row[sourceField]);
+    groupValues.push(statisticalWeights === undefined ? row[sourceField] : source);
     bySplit.set(split, groupValues);
     groupedValues.set(group, bySplit);
   }
@@ -492,6 +653,16 @@ export function deriveKernelDensity(values, {
     outputGroups * steps,
     "Density generated row count"
   );
+  const profileBandwidths = statisticalWeights !== undefined &&
+    bandwidth === "auto" && outputGroups > 1;
+  const resolvedBandwidth = profileBandwidths
+    ? undefined
+    : resolveBandwidth(
+        bandwidth,
+        sourceValues,
+        globalWeightSummary,
+        sourceField
+      );
   const extentSpan = resolvedExtent[1] - resolvedExtent[0];
   const sampleStep = extentSpan / (steps - 1);
   const samples = Array.from(
@@ -516,10 +687,30 @@ export function deriveKernelDensity(values, {
     );
   }
   const rows = [];
+  const resolvedBandwidths = [];
   for (const group of groups) {
     for (const split of splits) {
       const groupValues = groupedValues.get(group).get(split) ?? [];
       if (groupValues.length === 0) continue;
+      const groupWeightSummary = statisticalWeights === undefined
+        ? undefined
+        : summarizeStatisticalWeights(
+            groupValues,
+            statisticalWeights.definition.kind,
+            "Density group"
+          );
+      const groupBandwidth = resolvedBandwidth ?? weightedBandwidth(
+        groupWeightSummary,
+        sourceField,
+        "Density group auto bandwidth"
+      );
+      if (profileBandwidths) {
+        resolvedBandwidths.push({
+          ...(groupField === undefined ? {} : { group }),
+          ...(placement?.split === undefined ? {} : { split }),
+          bandwidth: groupBandwidth
+        });
+      }
       for (const sample of samples) {
         rows.push({
           ...(groupField === undefined
@@ -531,13 +722,22 @@ export function deriveKernelDensity(values, {
             ? {}
             : { [placement.split.field]: split }),
           [outputFields[0]]: sample,
-          [outputFields[1]]: estimateAt(
-            sample,
-            groupValues,
-            resolvedBandwidth,
-            resolvedKernel,
-            resolvedNormalization
-          )
+          [outputFields[1]]: groupWeightSummary === undefined
+            ? estimateAt(
+                sample,
+                groupValues,
+                groupBandwidth,
+                resolvedKernel,
+                resolvedNormalization
+              )
+            : estimateWeightedAt(
+                sample,
+                groupWeightSummary,
+                sourceField,
+                groupBandwidth,
+                resolvedKernel,
+                resolvedNormalization
+              )
         });
       }
     }
@@ -551,7 +751,9 @@ export function deriveKernelDensity(values, {
     },
     groups,
     ...(splitDomain === undefined ? {} : { splitDomain }),
-    bandwidth: resolvedBandwidth,
+    ...(resolvedBandwidth === undefined
+      ? { bandwidths: resolvedBandwidths }
+      : { bandwidth: resolvedBandwidth }),
     kernel: resolvedKernel,
     normalization: resolvedNormalization,
     extent: resolvedExtent,

package/src/grammar/displayLabels.js

@@ -0,0 +1,57 @@
+import { isPlainObject } from "../core/immutable.js";
+
+const ENTRY_KEYS = Object.freeze(["value", "label"]);
+
+export function sameDisplayLabelValue(left, right) {
+  return left === right;
+}
+
+function isDisplayLabelValue(value) {
+  return value === null || typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+export function normalizeDisplayLabelMap(value, label = "labelMap") {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} must be an array.`);
+  }
+  const normalized = [];
+  for (const [index, entry] of value.entries()) {
+    if (!isPlainObject(entry)) {
+      throw new TypeError(`${label}[${index}] must be a plain object.`);
+    }
+    const keys = Reflect.ownKeys(entry);
+    if (keys.length !== ENTRY_KEYS.length ||
+        ENTRY_KEYS.some(key => !Object.hasOwn(entry, key))) {
+      throw new Error(`${label}[${index}] must contain exactly value and label.`);
+    }
+    if (!isDisplayLabelValue(entry.value)) {
+      throw new TypeError(
+        `${label}[${index}].value must be a string, boolean, null, or finite number.`
+      );
+    }
+    if (typeof entry.label !== "string") {
+      throw new TypeError(`${label}[${index}].label must be a string.`);
+    }
+    if (normalized.some(previous =>
+      sameDisplayLabelValue(previous.value, entry.value))) {
+      throw new Error(`${label} contains a duplicate typed value.`);
+    }
+    normalized.push(Object.freeze({ value: entry.value, label: entry.label }));
+  }
+  return Object.freeze(normalized);
+}
+
+export function resolveDisplayLabel(value, map, fallback) {
+  if (map !== undefined) {
+    for (const entry of map) {
+      if (sameDisplayLabelValue(entry.value, value)) return entry.label;
+    }
+  }
+  const resolved = fallback(value);
+  if (typeof resolved !== "string") {
+    throw new TypeError("Display label fallback must return a string.");
+  }
+  return resolved;
+}

package/src/grammar/facets/dependencies.js

@@ -1,6 +1,137 @@
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { findTransformPolicy } from "../transforms.js";
+import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
+import { resolveRectMode } from "../rects.js";
+import { resolveRuleMode } from "../rules.js";
+
+const CARTESIAN_MARKS = new Set([
+  "point", "line", "area", "bar", "rule", "tick", "rect"
+]);
+const FACET_BAR_GRAINS = new Set([
+  BAR_GRAINS.histogram,
+  BAR_GRAINS.aggregate,
+  BAR_GRAINS.ranged
+]);
+const ORDINARY_SCALE_CHANNELS = Object.freeze([
+  ["x", "x"], ["y", "y"], ["xOffset", "xOffset"], ["yOffset", "yOffset"],
+  ["theta", "theta"], ["r", "radius"], ["color", "color"],
+  ["stroke", "stroke"], ["size", "size"], ["shape", "shape"],
+  ["opacity", "opacity"], ["strokeDash", "strokeDash"]
+]);
+
+function coordinateType(semanticSpec, layer) {
+  if (layer.coordinate === undefined) return undefined;
+  return semanticSpec.coordinates?.find(value => value.id === layer.coordinate)?.type;
+}
+
+function classifyPrimaryLayer(semanticSpec, layer) {
+  const type = layer.mark?.type;
+  const parallel = layer.encoding?.parallel;
+  if (parallel !== undefined || coordinateType(semanticSpec, layer) === "parallel") {
+    const complete = type === "line" && Array.isArray(parallel?.dimensions) &&
+      parallel.dimensions.length >= 2 &&
+      parallel.dimensions.every(dimension =>
+        typeof dimension?.scale === "string" && dimension.scale.length > 0
+      );
+    if (!complete) {
+      throw new Error(
+        `Facet layer "${layer.id}" must be a complete materializable Parallel mark.`
+      );
+    }
+    return "parallel";
+  }
+  const polar = layer.encoding?.theta !== undefined ||
+    layer.encoding?.radius !== undefined || coordinateType(semanticSpec, layer) === "polar";
+  if (polar) {
+    const theta = layer.encoding?.theta?.scale !== undefined;
+    const radius = layer.encoding?.radius?.scale !== undefined;
+    const complete = (type === "point" || type === "line")
+      ? theta && radius
+      : type === "arc" && theta;
+    if (!complete) {
+      throw new Error(
+        `Facet layer "${layer.id}" must be a complete materializable Polar mark.`
+      );
+    }
+    return "polar";
+  }
+  if (!CARTESIAN_MARKS.has(type)) {
+    throw new Error(
+      `facet does not support mark "${layer.id}" of type ${type ?? "incomplete"}.`
+    );
+  }
+  if (type === "bar" && !FACET_BAR_GRAINS.has(resolveBarGrain(layer))) {
+    throw new Error(
+      `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
+    );
+  }
+  const complete = (
+    layer.encoding?.x?.scale !== undefined &&
+    layer.encoding?.y?.scale !== undefined
+  ) || (type === "rule" && resolveRuleMode(layer) !== undefined) ||
+    (type === "rect" && resolveRectMode(layer) !== undefined);
+  if (!complete) {
+    throw new Error(
+      `Facet layer "${layer.id}" must be a complete materializable Cartesian mark.`
+    );
+  }
+  return "cartesian";
+}
+
+export function collectFacetScaleBindings(semanticSpec) {
+  if (!isPlainObject(semanticSpec) || !Array.isArray(semanticSpec.layers)) {
+    throw new TypeError("Facet scale bindings require a semantic spec with layers.");
+  }
+  const bindings = [];
+  for (const layer of semanticSpec.layers) {
+    for (const [policyKey, semanticChannel] of ORDINARY_SCALE_CHANNELS) {
+      const scaleId = layer.encoding?.[semanticChannel]?.scale;
+      if (scaleId === undefined) continue;
+      bindings.push({ layerId: layer.id, scaleId, policyKey, semanticChannel });
+    }
+    for (const [dimensionIndex, dimension] of
+      (layer.encoding?.parallel?.dimensions ?? []).entries()) {
+      if (dimension?.scale === undefined) continue;
+      bindings.push({
+        layerId: layer.id,
+        scaleId: dimension.scale,
+        policyKey: "parallelDimensions",
+        semanticChannel: "parallel",
+        dimensionField: dimension.field,
+        dimensionIndex
+      });
+    }
+  }
+  return cloneAndFreeze(bindings);
+}
+
+export function resolveFacetFamily(semanticSpec) {
+  if (!isPlainObject(semanticSpec) || !Array.isArray(semanticSpec.layers) ||
+      semanticSpec.layers.length === 0) {
+    throw new Error("facet requires at least one materializable layer.");
+  }
+  const primary = semanticSpec.layers.filter(layer =>
+    !(layer.mark?.type === "text" && layer.source !== undefined)
+  );
+  if (primary.length === 0) {
+    throw new Error("facet requires at least one primary materializable layer.");
+  }
+  const families = primary.map(layer => classifyPrimaryLayer(semanticSpec, layer));
+  if (new Set(families).size !== 1) {
+    throw new Error("facet requires every primary layer to use one coordinate family.");
+  }
+  const family = families[0];
+  return cloneAndFreeze({
+    family,
+    primaryLayers: primary.map(layer => layer.id),
+    dependentLayers: semanticSpec.layers
+      .filter(layer => !primary.includes(layer))
+      .map(layer => layer.id),
+    scaleBindings: collectFacetScaleBindings(semanticSpec),
+    coordinates: [...new Set(primary.map(layer => layer.coordinate).filter(Boolean))]
+  });
+}
 
 function requireCollection(value, label) {
   if (!Array.isArray(value) || value.length === 0) {
@@ -172,6 +303,7 @@ export function planFacetDependencies(semanticSpec, options = {}) {
     field,
     anchor,
     replay,
-    layers: layerPaths.map(({ layerId, data }) => ({ id: layerId, data }))
+    layers: layerPaths.map(({ layerId, data }) => ({ id: layerId, data })),
+    ...(options.family === undefined ? {} : options.family)
   });
 }

package/src/grammar/facets/guides.js

@@ -3,8 +3,11 @@ import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 const LEGEND_FAMILIES = Object.freeze({
   series: "categorical",
   color: "categorical",
+  stroke: "categorical",
   gradient: "gradient",
   interval: "discretized",
+  strokeGradient: "gradient",
+  strokeInterval: "discretized",
   size: "size",
   opacity: "opacity"
 });