ggaction 0.0.4 → 0.0.6

package/src/grammar/density.js

@@ -1,4 +1,4 @@
-import { cloneAndFreeze } from "../core/immutable.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/index.js

@@ -4,7 +4,9 @@ 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,

package/src/grammar/gradientProfile.js

@@ -0,0 +1,213 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  deriveKernelDensity,
+  validateDensityKernel,
+  validateDensityNormalization
+} from "./density.js";
+
+export const GRADIENT_PROFILE_FIELDS = Object.freeze({
+  category: "__gradientPlot_category",
+  values: "__gradientPlot_values",
+  intensities: "__gradientPlot_intensities",
+  lower: "__gradientPlot_lower",
+  upper: "__gradientPlot_upper",
+  center: "__gradientPlot_center",
+  count: "__gradientPlot_count"
+});
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "category", "field", "bandwidth", "extent", "steps", "kernel",
+  "normalization", "center", "as", "resolve", "resolved"
+]);
+const OUTPUT_KEYS = Object.freeze(Object.keys(GRADIENT_PROFILE_FIELDS));
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function validatePair(value, label) {
+  if (
+    !Array.isArray(value) || value.length !== 2 ||
+    !value.every(Number.isFinite) || value[0] >= value[1]
+  ) {
+    throw new RangeError(`${label} must be an ascending pair of finite numbers.`);
+  }
+  return value;
+}
+
+function validateOutputs(as, { category, field }) {
+  if (!isPlainObject(as)) {
+    throw new TypeError("Gradient profile 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(`Gradient profile as requires exactly ${OUTPUT_KEYS.join(", ")}.`);
+  }
+  const values = OUTPUT_KEYS.map(key =>
+    requireField(as[key], `Gradient profile as.${key}`)
+  );
+  if (new Set(values).size !== values.length) {
+    throw new Error("Gradient profile output fields must be distinct.");
+  }
+  const inputCollisions = values.filter(value => value === category || value === field);
+  if (
+    inputCollisions.some(value => value !== category) ||
+    as.category !== category ||
+    values.slice(1).includes(category)
+  ) {
+    throw new Error("Gradient profile output fields must not collide with input fields.");
+  }
+}
+
+export function validateGradientProfileTransform(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Gradient profile transform must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown gradient profile transform property "${unknown}".`);
+  }
+  if (value.type !== "gradientProfile") {
+    throw new Error(`Unsupported gradient profile transform "${value.type}".`);
+  }
+  const category = requireField(value.category, "Gradient profile category");
+  const field = requireField(value.field, "Gradient profile field");
+  if (category === field) {
+    throw new Error("Gradient profile category and field must be distinct.");
+  }
+  if (
+    value.bandwidth !== "auto" &&
+    (!Number.isFinite(value.bandwidth) || value.bandwidth <= 0)
+  ) {
+    throw new RangeError(
+      "Gradient profile bandwidth must be a positive finite number or auto."
+    );
+  }
+  if (value.extent !== "auto") {
+    validatePair(value.extent, "Gradient profile extent");
+  }
+  if (!Number.isInteger(value.steps) || value.steps < 2) {
+    throw new RangeError("Gradient profile steps must be an integer of at least 2.");
+  }
+  validateDensityKernel(value.kernel);
+  validateDensityNormalization(value.normalization);
+  if (!["mean", "median"].includes(value.center)) {
+    throw new Error(`Unsupported gradient profile center "${value.center}".`);
+  }
+  if (value.resolve !== "shared") {
+    throw new Error(`Unsupported gradient profile resolve "${value.resolve}".`);
+  }
+  validateOutputs(value.as, { category, field });
+  if (value.resolved !== undefined) {
+    const resolved = value.resolved;
+    if (
+      !isPlainObject(resolved) ||
+      Object.keys(resolved).some(key => ![
+        "bandwidth", "extent", "intensityDomain"
+      ].includes(key)) ||
+      !Number.isFinite(resolved.bandwidth) || resolved.bandwidth <= 0
+    ) {
+      throw new TypeError("Gradient profile resolved provenance is invalid.");
+    }
+    validatePair(resolved.extent, "Gradient profile resolved extent");
+    validatePair(
+      resolved.intensityDomain,
+      "Gradient profile resolved intensityDomain"
+    );
+  }
+  return value;
+}
+
+export function normalizeGradientProfileTransform(options = {}) {
+  const transform = {
+    type: "gradientProfile",
+    category: options.category,
+    field: options.field,
+    bandwidth: options.bandwidth ?? "auto",
+    extent: options.extent ?? "auto",
+    steps: options.steps ?? 64,
+    kernel: options.kernel ?? "gaussian",
+    normalization: options.normalization ?? "unit",
+    center: options.center ?? "median",
+    as: options.as ?? { ...GRADIENT_PROFILE_FIELDS, category: options.category },
+    resolve: "shared"
+  };
+  validateGradientProfileTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function requestedGradientProfileTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  return cloneAndFreeze(requested);
+}
+
+function centerOf(values, type) {
+  if (type === "mean") {
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = (sorted.length - 1) / 2;
+  const lower = Math.floor(middle);
+  const upper = Math.ceil(middle);
+  return (sorted[lower] + sorted[upper]) / 2;
+}
+
+export function deriveGradientProfiles(rows, transform) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Gradient profile rows must be an array.");
+  }
+  validateGradientProfileTransform(transform);
+  const density = deriveKernelDensity(rows, {
+    field: transform.field,
+    groupBy: transform.category,
+    bandwidth: transform.bandwidth,
+    extent: transform.extent,
+    steps: transform.steps,
+    kernel: transform.kernel,
+    normalization: transform.normalization,
+    as: ["__gradientProfile_value", "__gradientProfile_intensity"]
+  });
+  const validRows = rows.filter(row =>
+    row !== null && typeof row === "object" &&
+    row[transform.category] !== undefined && row[transform.category] !== null &&
+    row[transform.category] !== "" && Number.isFinite(row[transform.field])
+  );
+  const maximumIntensity = Math.max(
+    ...density.values.map(row => row.__gradientProfile_intensity)
+  );
+  if (!Number.isFinite(maximumIntensity) || maximumIntensity <= 0) {
+    throw new Error("Gradient profile requires a positive resolved density range.");
+  }
+  const values = density.groups.map(category => {
+    const samples = density.values.filter(
+      row => row[transform.category] === category
+    );
+    const observations = validRows
+      .filter(row => row[transform.category] === category)
+      .map(row => row[transform.field]);
+    return {
+      [transform.as.category]: category,
+      [transform.as.values]: samples.map(row => row.__gradientProfile_value),
+      [transform.as.intensities]: samples.map(
+        row => row.__gradientProfile_intensity
+      ),
+      [transform.as.lower]: density.extent[0],
+      [transform.as.upper]: density.extent[1],
+      [transform.as.center]: centerOf(observations, transform.center),
+      [transform.as.count]: observations.length
+    };
+  });
+  return cloneAndFreeze({
+    values,
+    categories: density.groups,
+    bandwidth: density.bandwidth,
+    extent: density.extent,
+    intensityDomain: [0, maximumIntensity]
+  });
+}