ggaction 0.0.3 → 0.0.5

package/src/grammar/categoricalDensity.js

@@ -0,0 +1,192 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  readNominalField,
+  readQuantitativeField
+} from "./scales/index.js";
+import { buildAreaCurvePathCommands } from "./curveCommands.js";
+import { buildLinearPathCommands } from "./pathCommands.js";
+
+function sameKey(left, right) {
+  const leftEntries = Object.entries(left);
+  const rightEntries = Object.entries(right);
+  return leftEntries.length === rightEntries.length && leftEntries.every(
+    ([field, value]) => Object.hasOwn(right, field) && Object.is(right[field], value)
+  );
+}
+
+function seriesSide(placement, splitValue) {
+  if (placement.split === undefined) return placement.side;
+  const domain = placement.split.domain ?? placement.resolvedSplitDomain;
+  const index = domain.findIndex(value => Object.is(value, splitValue));
+  if (index < 0) {
+    throw new Error(`Density split value "${splitValue}" is outside its domain.`);
+  }
+  if (placement.channel === "x") return index === 0 ? "left" : "right";
+  return index === 0 ? "top" : "bottom";
+}
+
+export function deriveCategoricalDensitySeries(rows, layer, transform) {
+  const placement = transform?.placement;
+  if (layer?.mark?.type !== "area" || placement?.type !== "category") {
+    throw new Error("Categorical density series require a category-placed area.");
+  }
+  const categoryEncoding = layer.encoding?.[placement.channel];
+  const valueChannel = placement.channel === "x" ? "y" : "x";
+  const valueEncoding = layer.encoding?.[valueChannel];
+  if (
+    categoryEncoding?.field !== placement.categoryField ||
+    !["nominal", "ordinal"].includes(categoryEncoding.fieldType) ||
+    valueEncoding?.field !== transform.as?.[0] ||
+    valueEncoding.fieldType !== "quantitative"
+  ) {
+    throw new Error(
+      `Categorical density area mark "${layer.id}" requires its category and value encodings.`
+    );
+  }
+  const categories = readNominalField(rows, placement.categoryField);
+  const values = readQuantitativeField(rows, transform.as[0]);
+  const densities = readQuantitativeField(rows, transform.as[1]);
+  const splits = placement.split === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, placement.split.field);
+  const series = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const key = {
+      ...(transform.groupBy === undefined
+        ? {}
+        : { [transform.groupBy]: categories[index] }),
+      ...(placement.split === undefined
+        ? {}
+        : { [placement.split.field]: splits[index] })
+    };
+    let current = series.find(item => sameKey(item.key, key));
+    if (current === undefined) {
+      current = {
+        category: categories[index],
+        split: splits[index],
+        key,
+        values: []
+      };
+      series.push(current);
+    }
+    current.values.push({
+      value: values[index],
+      density: densities[index]
+    });
+  }
+  if (series.length === 0) {
+    throw new Error(`Categorical density area mark "${layer.id}" has no values.`);
+  }
+  const resolvedSplitDomain = placement.split === undefined
+    ? undefined
+    : transform.resolved?.splitDomain ?? placement.split.domain;
+  if (placement.split !== undefined && resolvedSplitDomain === undefined) {
+    throw new Error("Categorical density split requires a resolved two-value domain.");
+  }
+  return cloneAndFreeze({
+    mode: placement.channel === "x" ? "category-x" : "category-y",
+    placement: {
+      ...placement,
+      ...(resolvedSplitDomain === undefined ? {} : { resolvedSplitDomain })
+    },
+    series: series.map(item => ({
+      ...item,
+      side: seriesSide({
+        ...placement,
+        ...(resolvedSplitDomain === undefined ? {} : { resolvedSplitDomain })
+      }, item.split),
+      values: item.values.sort((left, right) => left.value - right.value)
+    }))
+  });
+}
+
+function maximumFor(derived, series) {
+  const candidates = derived.placement.width.resolve === "shared"
+    ? derived.series
+    : derived.series.filter(candidate => Object.is(
+        candidate.category,
+        series.category
+      ));
+  const maximum = Math.max(...candidates.flatMap(candidate =>
+    candidate.values.map(value => value.density)
+  ));
+  if (!Number.isFinite(maximum) || maximum <= 0) {
+    throw new Error("Categorical density width requires a positive maximum.");
+  }
+  return maximum;
+}
+
+function pathBoundaries(series, center, halfWidth, maximum, valueScale, channel) {
+  const valuePositions = mapContinuousScaleValues(
+    series.values.map(value => value.value),
+    valueScale
+  );
+  const widths = series.values.map(value => halfWidth * value.density / maximum);
+  const horizontal = channel === "x";
+  const direction = {
+    left: -1,
+    right: 1,
+    top: -1,
+    bottom: 1
+  }[series.side];
+  const point = (valuePosition, width) => horizontal
+    ? { x: center + width, y: valuePosition }
+    : { x: valuePosition, y: center + width };
+  if (series.side === "both") {
+    return {
+      lower: valuePositions.map((value, index) => point(value, -widths[index])),
+      upper: valuePositions.map((value, index) => point(value, widths[index]))
+    };
+  }
+  const baseline = valuePositions.map(value => point(value, 0));
+  const outer = valuePositions.map((value, index) =>
+    point(value, direction * widths[index])
+  );
+  return {
+    lower: baseline,
+    upper: outer,
+    outline: [baseline[0], ...outer, baseline.at(-1)]
+  };
+}
+
+export function buildCategoricalDensityPaths(
+  derived,
+  { categoryScale, valueScale, curve = "linear" } = {}
+) {
+  if (!Number.isFinite(categoryScale?.bandwidth) || categoryScale.bandwidth <= 0) {
+    throw new Error("Categorical density placement requires a positive band scale.");
+  }
+  const halfWidth = categoryScale.bandwidth * derived.placement.width.band / 2;
+  const centers = mapOrdinalPositionValues(
+    derived.series.map(series => series.category),
+    categoryScale
+  );
+  const commands = derived.series.map((series, index) => {
+    const boundaries = pathBoundaries(
+      series,
+      centers[index],
+      halfWidth,
+      maximumFor(derived, series),
+      valueScale,
+      derived.placement.channel
+    );
+    if (curve !== "linear") {
+      return buildAreaCurvePathCommands(
+        boundaries.lower,
+        boundaries.upper,
+        curve,
+        derived.placement.channel === "x" ? { independentAxis: "y" } : {}
+      );
+    }
+    return buildLinearPathCommands(
+      boundaries.outline ?? [
+        ...boundaries.lower,
+        ...[...boundaries.upper].reverse()
+      ],
+      { close: true }
+    );
+  });
+  return cloneAndFreeze(commands);
+}

package/src/grammar/coordinates.js

@@ -1,6 +1,6 @@
 import { getPositionChannelDefinition } from "../core/vocabulary.js";
 
-const COORDINATE_TYPES = new Set(["cartesian", "polar"]);
+const COORDINATE_TYPES = new Set(["cartesian", "polar", "parallel"]);
 
 export function validateCoordinateType(value) {
   if (!COORDINATE_TYPES.has(value)) {

package/src/grammar/curveCommands.js

@@ -267,7 +267,9 @@ export function buildCurvePathCommands(points, curve = "linear") {
   const validatedPoints = validatePoints(points);
   const validatedCurve = validateCurveInterpolation(curve);
   if (validatedCurve === "linear" ||
-      (SMOOTH_CURVES.has(validatedCurve) && points.length < 3)) {
+      (SMOOTH_CURVES.has(validatedCurve) &&
+        validatedCurve !== "monotone" &&
+        points.length < 3)) {
     return buildLinearPathCommands(validatedPoints);
   }
   if (validatedCurve.startsWith("step")) {

package/src/grammar/density.js

@@ -1,5 +1,5 @@
-import { cloneAndFreeze } from "../core/immutable.js";
-import { isNominalValue } from "./scales.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { isNominalValue } from "./scales/index.js";
 
 const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
 
@@ -10,6 +10,12 @@ export const DENSITY_KERNELS = Object.freeze([
   "triangular"
 ]);
 export const DENSITY_NORMALIZATIONS = Object.freeze(["unit", "count"]);
+export const DENSITY_PLACEMENT_SIDES = Object.freeze([
+  "both", "left", "right", "top", "bottom"
+]);
+export const DENSITY_WIDTH_RESOLUTIONS = Object.freeze([
+  "shared", "independent"
+]);
 
 export function validateDensityKernel(value) {
   if (!DENSITY_KERNELS.includes(value)) {
@@ -32,10 +38,169 @@ function requireField(value, label) {
   return value;
 }
 
+function validateSplitDomain(value) {
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    !value.every(isNominalValue) ||
+    Object.is(value[0], value[1])
+  ) {
+    throw new TypeError(
+      "Density split domain must contain two distinct nominal values."
+    );
+  }
+  return [...value];
+}
+
+function validatePlacementWidth(value = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Density placement width must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(key => !["band", "resolve"].includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown density placement width property "${unknown}".`);
+  }
+  const band = value.band ?? 0.8;
+  if (!Number.isFinite(band) || band <= 0 || band > 1) {
+    throw new RangeError("Density placement width band must be in (0, 1].");
+  }
+  const resolve = value.resolve ?? "shared";
+  if (!DENSITY_WIDTH_RESOLUTIONS.includes(resolve)) {
+    throw new Error(`Unsupported density width resolve "${resolve}".`);
+  }
+  return { band, resolve };
+}
+
+export function normalizeDensityPlacement(value, {
+  densityChannel = "x",
+  groupBy,
+  categoryField
+} = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Density placement must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    key => !["type", "side", "width", "split", "scale"].includes(key)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown density placement property "${unknown}".`);
+  }
+  if (value.type === "baseline") return undefined;
+  if (value.type !== "category") {
+    throw new Error(`Unsupported density placement type "${value.type}".`);
+  }
+  if (!["x", "y"].includes(densityChannel)) {
+    throw new Error(`Unsupported densityChannel "${densityChannel}".`);
+  }
+  const resolvedCategoryField = requireField(
+    categoryField ?? groupBy,
+    "Density placement category field"
+  );
+  const width = validatePlacementWidth(value.width);
+  let split;
+  if (value.split !== undefined) {
+    if (!isPlainObject(value.split)) {
+      throw new TypeError("Density placement split must be a plain object.");
+    }
+    const splitUnknown = Object.keys(value.split).find(
+      key => !["field", "domain"].includes(key)
+    );
+    if (splitUnknown !== undefined) {
+      throw new Error(`Unknown density split property "${splitUnknown}".`);
+    }
+    const field = requireField(value.split.field, "Density split field");
+    if (field === groupBy) {
+      throw new Error("Density split field must differ from groupBy.");
+    }
+    split = {
+      field,
+      ...(value.split.domain === undefined
+        ? {}
+        : { domain: validateSplitDomain(value.split.domain) })
+    };
+  }
+  if (split !== undefined && Object.hasOwn(value, "side")) {
+    throw new Error("Density split placement cannot also specify side.");
+  }
+  const side = split === undefined ? value.side ?? "both" : undefined;
+  if (side !== undefined && !DENSITY_PLACEMENT_SIDES.includes(side)) {
+    throw new Error(`Unsupported density placement side "${side}".`);
+  }
+  const horizontalWidth = densityChannel === "x";
+  if (
+    side !== undefined &&
+    !(
+      horizontalWidth
+        ? ["both", "left", "right"].includes(side)
+        : ["both", "top", "bottom"].includes(side)
+    )
+  ) {
+    throw new Error(
+      `Density ${densityChannel} placement does not support side "${side}".`
+    );
+  }
+  return cloneAndFreeze({
+    type: "category",
+    channel: densityChannel,
+    categoryField: resolvedCategoryField,
+    ...(side === undefined ? {} : { side }),
+    width,
+    ...(split === undefined ? {} : { split })
+  });
+}
+
+function validateStoredDensityPlacement(value, groupBy) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Density placement provenance must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    key => !["type", "channel", "categoryField", "side", "width", "split"].includes(key)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown density placement provenance property "${unknown}".`);
+  }
+  const normalized = normalizeDensityPlacement({
+    type: value.type,
+    ...(value.side === undefined ? {} : { side: value.side }),
+    width: value.width,
+    ...(value.split === undefined ? {} : { split: value.split })
+  }, {
+    densityChannel: value.channel,
+    groupBy,
+    categoryField: value.categoryField
+  });
+  const sameSplit = normalized.split === undefined
+    ? value.split === undefined
+    : value.split !== undefined &&
+      normalized.split.field === value.split.field &&
+      (
+        normalized.split.domain === undefined
+          ? value.split.domain === undefined
+          : value.split.domain !== undefined &&
+            normalized.split.domain.length === value.split.domain.length &&
+            normalized.split.domain.every((item, index) =>
+              Object.is(item, value.split.domain[index])
+            )
+      );
+  if (
+    normalized.type !== value.type ||
+    normalized.channel !== value.channel ||
+    normalized.categoryField !== value.categoryField ||
+    normalized.side !== value.side ||
+    value.width === undefined ||
+    normalized.width.band !== value.width.band ||
+    normalized.width.resolve !== value.width.resolve ||
+    !sameSplit
+  ) {
+    throw new Error("Density placement provenance must be fully normalized.");
+  }
+  return value;
+}
+
 export function validateDensityTransform(transform) {
   const supported = [
     "type", "field", "groupBy", "bandwidth", "extent", "steps", "as",
-    "resolve", "kernel", "normalization", "resolved"
+    "resolve", "kernel", "normalization", "placement", "resolved"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
@@ -48,6 +213,9 @@ export function validateDensityTransform(transform) {
   if (transform.groupBy !== undefined) {
     requireField(transform.groupBy, "Density groupBy");
   }
+  if (transform.placement !== undefined) {
+    validateStoredDensityPlacement(transform.placement, transform.groupBy);
+  }
   validateDensityKernel(transform.kernel ?? "gaussian");
   validateDensityNormalization(transform.normalization ?? "unit");
   if (
@@ -82,7 +250,9 @@ export function validateDensityTransform(transform) {
   }
   const collisions = new Set([
     transform.field,
-    transform.groupBy
+    transform.groupBy,
+    transform.placement?.categoryField,
+    transform.placement?.split?.field
   ].filter(Boolean));
   if (transform.as.some(value => collisions.has(value))) {
     throw new Error(
@@ -98,16 +268,26 @@ export function validateDensityTransform(transform) {
       resolved === null ||
       typeof resolved !== "object" ||
       Array.isArray(resolved) ||
-      Object.keys(resolved).some(key => !["bandwidth", "extent"].includes(key)) ||
+      Object.keys(resolved).some(
+        key => !["bandwidth", "extent", "splitDomain"].includes(key)
+      ) ||
       !Number.isFinite(resolved.bandwidth) ||
       resolved.bandwidth <= 0 ||
       !Array.isArray(resolved.extent) ||
       resolved.extent.length !== 2 ||
       !resolved.extent.every(Number.isFinite) ||
-      resolved.extent[0] >= resolved.extent[1]
+      resolved.extent[0] >= resolved.extent[1] ||
+      (resolved.splitDomain !== undefined && (() => {
+        try {
+          validateSplitDomain(resolved.splitDomain);
+          return transform.placement?.split === undefined;
+        } catch {
+          return true;
+        }
+      })())
     ) {
       throw new TypeError(
-        "Density resolved provenance requires a positive bandwidth and ascending finite extent."
+        "Density resolved provenance requires a positive bandwidth, ascending finite extent, and optional two-value split domain."
       );
     }
   }
@@ -187,7 +367,7 @@ function resolveExtent(value, sourceValues) {
   return [...value];
 }
 
-function resolveOutputFields(as, field, groupBy) {
+function resolveOutputFields(as, field, groupBy, placement) {
   const resolved = as ?? [`${field}_value`, `${field}_density`];
   if (
     !Array.isArray(resolved) ||
@@ -197,7 +377,12 @@ function resolveOutputFields(as, field, groupBy) {
   ) {
     throw new TypeError("Density as must contain two distinct non-empty fields.");
   }
-  const collisions = new Set([field, groupBy].filter(Boolean));
+  const collisions = new Set([
+    field,
+    groupBy,
+    placement?.categoryField,
+    placement?.split?.field
+  ].filter(Boolean));
   if (resolved.some(value => collisions.has(value))) {
     throw new Error("Density output fields must not collide with source or group fields.");
   }
@@ -240,7 +425,8 @@ export function deriveKernelDensity(values, {
   steps = 100,
   kernel = "gaussian",
   normalization = "unit",
-  as
+  as,
+  placement
 } = {}) {
   if (!Array.isArray(values)) {
     throw new TypeError("Density values must be an array.");
@@ -252,14 +438,18 @@ export function deriveKernelDensity(values, {
   if (!Number.isInteger(steps) || steps < 2) {
     throw new RangeError("Density steps must be an integer of at least 2.");
   }
-  const outputFields = resolveOutputFields(as, sourceField, groupField);
+  if (placement !== undefined) {
+    validateStoredDensityPlacement(placement, groupField);
+  }
+  const outputFields = resolveOutputFields(as, sourceField, groupField, placement);
   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]))
+    (groupField === undefined || isNominalValue(row[groupField])) &&
+    (placement?.split === undefined || isNominalValue(row[placement.split.field]))
   );
   if (validRows.length === 0) {
     throw new Error("Density requires at least one valid field/group row.");
@@ -270,30 +460,65 @@ export function deriveKernelDensity(values, {
   const groups = groupField === undefined
     ? [undefined]
     : [...new Set(validRows.map(row => row[groupField]))];
+  const observedSplits = placement?.split === undefined
+    ? []
+    : [...new Set(validRows.map(row => row[placement.split.field]))];
+  let splitDomain;
+  if (placement?.split !== undefined) {
+    splitDomain = placement.split.domain === undefined
+      ? observedSplits
+      : validateSplitDomain(placement.split.domain);
+    if (splitDomain.length !== 2) {
+      throw new Error(
+        "Density split inference requires exactly two observed values."
+      );
+    }
+    if (observedSplits.some(value => !splitDomain.some(item => Object.is(item, value)))) {
+      throw new Error("Density split domain must include every observed split value.");
+    }
+  }
   const sampleStep = (resolvedExtent[1] - resolvedExtent[0]) / (steps - 1);
   const samples = Array.from(
     { length: steps },
     (_, index) => index === steps - 1
       ? resolvedExtent[1]
-      : resolvedExtent[0] + sampleStep * index
+      : placement === undefined
+        ? resolvedExtent[0] + sampleStep * index
+        : resolvedExtent[0] +
+          (resolvedExtent[1] - resolvedExtent[0]) * index / (steps - 1)
   );
   const rows = [];
   for (const group of groups) {
-    const groupValues = validRows
-      .filter(row => groupField === undefined || row[groupField] === group)
-      .map(row => row[sourceField]);
-    for (const sample of samples) {
-      rows.push({
-        ...(groupField === undefined ? {} : { [groupField]: group }),
-        [outputFields[0]]: sample,
-        [outputFields[1]]: estimateAt(
-          sample,
-          groupValues,
-          resolvedBandwidth,
-          resolvedKernel,
-          resolvedNormalization
+    const splits = splitDomain ?? [undefined];
+    for (const split of splits) {
+      const groupValues = validRows
+        .filter(row =>
+          (groupField === undefined || Object.is(row[groupField], group)) &&
+          (placement?.split === undefined ||
+            Object.is(row[placement.split.field], split))
         )
-      });
+        .map(row => row[sourceField]);
+      if (groupValues.length === 0) continue;
+      for (const sample of samples) {
+        rows.push({
+          ...(groupField === undefined
+            ? placement === undefined
+              ? {}
+              : { [placement.categoryField]: "density" }
+            : { [groupField]: group }),
+          ...(placement?.split === undefined
+            ? {}
+            : { [placement.split.field]: split }),
+          [outputFields[0]]: sample,
+          [outputFields[1]]: estimateAt(
+            sample,
+            groupValues,
+            resolvedBandwidth,
+            resolvedKernel,
+            resolvedNormalization
+          )
+        });
+      }
     }
   }
   return cloneAndFreeze({
@@ -304,6 +529,7 @@ export function deriveKernelDensity(values, {
       density: outputFields[1]
     },
     groups,
+    ...(splitDomain === undefined ? {} : { splitDomain }),
     bandwidth: resolvedBandwidth,
     kernel: resolvedKernel,
     normalization: resolvedNormalization,

package/src/grammar/facets/dependencies.js

@@ -1,14 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
-
-const ROW_PRESERVING_TRANSFORMS = new Set(["filter"]);
-const STATISTICAL_TRANSFORMS = new Set([
-  "regression",
-  "density",
-  "interval",
-  "boxSummary",
-  "boxOutlier"
-]);
+import { findTransformPolicy } from "../transforms.js";
 
 function requireCollection(value, label) {
   if (!Array.isArray(value) || value.length === 0) {
@@ -54,8 +46,8 @@ function classifyDataset(dataset) {
     throw new Error(`Transformed dataset "${dataset.id}" requires a source dataset.`);
   }
   const type = transforms[0].type;
-  if (ROW_PRESERVING_TRANSFORMS.has(type)) return "rowPreserving";
-  if (STATISTICAL_TRANSFORMS.has(type)) return "statistical";
+  const topology = findTransformPolicy(type)?.facetTopology;
+  if (topology !== undefined) return topology;
   throw new Error(
     `Facet replay does not support dataset transform "${type ?? "unknown"}" on "${dataset.id}".`
   );

package/src/grammar/{facets.js → facets/index.js}

@@ -1,10 +1,12 @@
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { validateUserId } from "../core/identifiers.js";
-import { BAR_GRAINS, resolveBarGrain } from "./bars/policy.js";
-import { planFacetDependencies } from "./facets/dependencies.js";
-import { readNominalField } from "./scales.js";
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
+import { planFacetDependencies } from "./dependencies.js";
+import { readNominalField } from "../scales/index.js";
 
-const SUPPORTED_MARKS = new Set(["point", "line", "area", "bar", "rule"]);
+const SUPPORTED_MARKS = new Set([
+  "point", "line", "area", "bar", "rule", "rect"
+]);
 const SUPPORTED_BAR_GRAINS = new Set([
   BAR_GRAINS.histogram,
   BAR_GRAINS.aggregate,