ggaction 0.0.1

package/src/actions/regression/components.js

@@ -0,0 +1,216 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { resolveEligibleLayer } from "../../selectors/layers.js";
+import {
+  REGRESSION_LOWER_FIELD,
+  REGRESSION_UPPER_FIELD
+} from "../../grammar/regression.js";
+import { validateAreaCreateOutline } from "../marks/area.js";
+
+const BAND_OPTIONS = Object.freeze([
+  "id", "data", "x", "lower", "upper", "groupBy", "coordinate", "xScale", "yScale",
+  "color", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "id", "data", "x", "y", "groupBy", "coordinate", "xScale", "yScale", "colorScale",
+  "strokeWidth", "curve"
+]);
+const EDIT_BAND_OPTIONS = Object.freeze([
+  "target", "color", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const EDIT_LINE_OPTIONS = Object.freeze(["target", "strokeWidth", "curve"]);
+
+function isRegressionLayer(program, layer, type) {
+  const dataset = findDataset(program, layer.data);
+  return layer.mark?.type === type &&
+    dataset?.transform?.length === 1 &&
+    dataset.transform[0].type === "regression";
+}
+
+function resolveRegressionComponent(program, args, type, label) {
+  const target = Object.hasOwn(args, "target")
+    ? validateUserId(args.target, `${label} id`)
+    : undefined;
+  return resolveEligibleLayer(program, {
+    target,
+    predicate: layer => isRegressionLayer(program, layer, type),
+    label
+  });
+}
+
+function requireRegressionBandDataset(program, args) {
+  const dataset = findDataset(program, args.data);
+  const transform = dataset?.transform?.length === 1
+    ? dataset.transform[0]
+    : undefined;
+  if (transform?.type !== "regression" || transform.method === "loess") {
+    throw new Error(
+      "createRegressionBand requires a regression dataset with interval bounds."
+    );
+  }
+  if (
+    args.x !== transform.x ||
+    args.lower !== REGRESSION_LOWER_FIELD ||
+    args.upper !== REGRESSION_UPPER_FIELD ||
+    args.groupBy !== transform.groupBy
+  ) {
+    throw new Error(
+      "createRegressionBand fields and grouping must match regression provenance."
+    );
+  }
+  return { dataset, transform };
+}
+
+export const createRegressionBand = action(
+  {
+    op: "createRegressionBand",
+    description: "Create and encode a grouped regression confidence band."
+  },
+  function (args = {}) {
+    validateKeys(args, BAND_OPTIONS, "createRegressionBand");
+    const id = validateUserId(args.id, "Regression band id");
+    const { transform } = requireRegressionBandDataset(this, args);
+    validateAreaCreateOutline(args, "createRegressionBand");
+    let next = this
+      .createErrorBand({
+        id,
+        data: args.data,
+        x: {
+          field: args.x,
+          fieldType: "quantitative",
+          scale: { id: args.xScale }
+        },
+        y: {
+          center: transform.y,
+          lower: args.lower,
+          upper: args.upper,
+          scale: { id: args.yScale }
+        },
+        ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+        coordinate: args.coordinate,
+        fill: args.color ?? DEFAULT_COLORS.regressionBand,
+        opacity: args.opacity ?? 0.18,
+        ...(args.curve === undefined ? {} : { curve: args.curve })
+      })
+      .editSemantic({
+        property: `layer[${id}].encoding.y.title`,
+        remove: true
+      });
+    if (args.stroke !== undefined || args.strokeWidth !== undefined) {
+      next = next.editAreaMark({
+        target: id,
+        ...(args.stroke === undefined ? {} : { stroke: args.stroke }),
+        ...(args.strokeWidth === undefined
+          ? {}
+          : { strokeWidth: args.strokeWidth })
+      });
+    }
+    return next;
+  }
+);
+
+export const editRegressionBand = action(
+  {
+    op: "editRegressionBand",
+    description: "Edit regression-band fill, opacity, and outline."
+  },
+  function (args = {}) {
+    validateKeys(args, EDIT_BAND_OPTIONS, "editRegressionBand");
+    const changes = ["color", "opacity", "stroke", "strokeWidth", "curve"];
+    if (!changes.some(key => Object.hasOwn(args, key))) {
+      throw new Error(
+        "editRegressionBand requires color, opacity, stroke, strokeWidth, or curve."
+      );
+    }
+    const layer = resolveRegressionComponent(
+      this,
+      args,
+      "area",
+      "regression band"
+    );
+    return this.editAreaMark({
+      target: layer.id,
+      ...(Object.hasOwn(args, "color") ? { fill: args.color } : {}),
+      ...(Object.hasOwn(args, "opacity") ? { opacity: args.opacity } : {}),
+      ...(Object.hasOwn(args, "stroke") ? { stroke: args.stroke } : {}),
+      ...(Object.hasOwn(args, "strokeWidth")
+        ? { strokeWidth: args.strokeWidth }
+        : {}),
+      ...(Object.hasOwn(args, "curve") ? { curve: args.curve } : {})
+    });
+  }
+);
+
+export const editRegressionLine = action(
+  {
+    op: "editRegressionLine",
+    description: "Edit regression-line width or curve."
+  },
+  function (args = {}) {
+    validateKeys(args, EDIT_LINE_OPTIONS, "editRegressionLine");
+    if (
+      !Object.hasOwn(args, "strokeWidth") &&
+      !Object.hasOwn(args, "curve")
+    ) {
+      throw new Error("editRegressionLine requires strokeWidth or curve.");
+    }
+    const layer = resolveRegressionComponent(
+      this,
+      args,
+      "line",
+      "regression line"
+    );
+    return this.editLineMark({
+      target: layer.id,
+      ...(Object.hasOwn(args, "strokeWidth")
+        ? { strokeWidth: args.strokeWidth }
+        : {}),
+      ...(Object.hasOwn(args, "curve") ? { curve: args.curve } : {})
+    });
+  }
+);
+
+export const createRegressionLine = action(
+  {
+    op: "createRegressionLine",
+    description: "Create and encode grouped regression line paths."
+  },
+  function (args = {}) {
+    validateKeys(args, LINE_OPTIONS, "createRegressionLine");
+    const id = validateUserId(args.id, "Regression line id");
+    let next = this
+      .createLineMark({
+        id,
+        data: args.data,
+        strokeWidth: args.strokeWidth ?? 3,
+        ...(args.curve === undefined ? {} : { curve: args.curve })
+      })
+      .encodeX({
+        target: id,
+        field: args.x,
+        fieldType: "quantitative",
+        coordinate: args.coordinate,
+        scale: { id: args.xScale }
+      })
+      .encodeY({
+        target: id,
+        field: args.y,
+        fieldType: "quantitative",
+        coordinate: args.coordinate,
+        scale: { id: args.yScale }
+      });
+    if (args.groupBy !== undefined) {
+      next = next
+        .encodeColor({
+          target: id,
+          field: args.groupBy,
+          scale: { id: args.colorScale }
+        })
+        .encodeGroup({ target: id, field: args.groupBy });
+    }
+    return next.rematerializeLineMark({ id });
+  }
+);

package/src/actions/regression/create.js

@@ -0,0 +1,102 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { normalizeRegressionParameters } from "../../grammar/regression.js";
+import {
+  findRegressionPoint,
+  inferRegressionGroup,
+  requireRegressionField,
+  requireRegressionObject
+} from "./resolve.js";
+
+const REGRESSION_OPTIONS = Object.freeze([
+  "target", "x", "y", "groupBy", "method", "degree", "span",
+  "confidence", "interval", "band", "line"
+]);
+
+export const createRegression = action(
+  {
+    op: "createRegression",
+    description: "Fit and layer regression lines with optional interval bands."
+  },
+  function (args = {}) {
+    validateKeys(args, REGRESSION_OPTIONS, "createRegression");
+    const point = findRegressionPoint(this, args.target);
+    const x = args.x === undefined
+      ? point.encoding.x.field
+      : requireRegressionField(args.x, "Regression x");
+    const y = args.y === undefined
+      ? point.encoding.y.field
+      : requireRegressionField(args.y, "Regression y");
+    const groupBy = inferRegressionGroup(point, args);
+    const coordinate = point.coordinate;
+    const xScale = point.encoding.x.scale;
+    const yScale = point.encoding.y.scale;
+    if (coordinate === undefined || xScale === undefined || yScale === undefined) {
+      throw new Error(
+        "createRegression target requires stored coordinate and scales."
+      );
+    }
+    const parameters = normalizeRegressionParameters(args);
+    let band = false;
+    if (parameters.method === "loess") {
+      if (args.band !== undefined && args.band !== false) {
+        throw new Error("LOESS regression does not support a band object.");
+      }
+    } else if (args.band !== false) {
+      band = requireRegressionObject(args.band ?? {}, "Regression band");
+    }
+    const line = requireRegressionObject(args.line ?? {}, "Regression line");
+    if (band !== false) {
+      validateKeys(
+        band,
+        ["color", "opacity", "stroke", "strokeWidth", "curve"],
+        "regression band"
+      );
+    }
+    validateKeys(line, ["strokeWidth", "curve"], "regression line");
+    const colorEncoding = point.encoding?.color;
+    const namespace = point.id;
+    const dataId = `${namespace}RegressionData`;
+    const bandId = `${namespace}RegressionBands`;
+    const lineId = `${namespace}RegressionLines`;
+    const colorScale =
+      groupBy !== undefined && colorEncoding?.field === groupBy
+        ? colorEncoding.scale
+        : `${namespace}RegressionColor`;
+
+    let next = this
+      .createRegressionData({
+        id: dataId,
+        source: point.data,
+        x,
+        y,
+        ...(groupBy === undefined ? {} : { groupBy }),
+        ...parameters
+      });
+    if (band !== false) {
+      next = next.createRegressionBand({
+        id: bandId,
+        data: dataId,
+        x,
+        lower: "__regression_ci_lower",
+        upper: "__regression_ci_upper",
+        ...(groupBy === undefined ? {} : { groupBy }),
+        coordinate,
+        xScale,
+        yScale,
+        ...band
+      });
+    }
+    return next.createRegressionLine({
+      id: lineId,
+      data: dataId,
+      x,
+      y,
+      ...(groupBy === undefined ? {} : { groupBy, colorScale }),
+      coordinate,
+      xScale,
+      yScale,
+      ...line
+    });
+  }
+);

package/src/actions/regression/index.js

@@ -0,0 +1,23 @@
+import {
+  createRegressionBand,
+  createRegressionLine,
+  editRegressionBand,
+  editRegressionLine
+} from "./components.js";
+import { createRegression } from "./create.js";
+
+export {
+  createRegressionBand,
+  createRegressionLine,
+  editRegressionBand,
+  editRegressionLine
+} from "./components.js";
+export { createRegression } from "./create.js";
+
+export function registerRegressionActions(ProgramClass) {
+  ProgramClass.prototype.createRegressionBand = createRegressionBand;
+  ProgramClass.prototype.createRegressionLine = createRegressionLine;
+  ProgramClass.prototype.editRegressionBand = editRegressionBand;
+  ProgramClass.prototype.editRegressionLine = editRegressionLine;
+  ProgramClass.prototype.createRegression = createRegression;
+}

package/src/actions/regression/resolve.js

@@ -0,0 +1,57 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { findLayer } from "../../selectors/layers.js";
+
+export function requireRegressionObject(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  return value;
+}
+
+export function requireRegressionField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function findRegressionPoint(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(layer =>
+    layer.mark?.type === "point" &&
+    layer.encoding?.x?.fieldType === "quantitative" &&
+    layer.encoding?.y?.fieldType === "quantitative"
+  );
+  if (requested !== undefined) {
+    const selected = findLayer(program, requested);
+    if (selected === undefined || !eligible.includes(selected)) {
+      throw new Error(`Unknown regression point target "${requested}".`);
+    }
+    return selected;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current !== undefined && eligible.includes(current)) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) {
+    throw new Error(
+      "createRegression requires an eligible quantitative point mark."
+    );
+  }
+  throw new Error("createRegression target is ambiguous; provide target.");
+}
+
+export function inferRegressionGroup(layer, args) {
+  if (Object.hasOwn(args, "groupBy")) {
+    return args.groupBy === undefined
+      ? undefined
+      : requireRegressionField(args.groupBy, "Regression groupBy");
+  }
+  const candidates = [...new Set(
+    [layer.encoding?.color, layer.encoding?.shape]
+      .filter(encoding => encoding?.fieldType === "nominal")
+      .map(encoding => encoding.field)
+  )];
+  if (candidates.length > 1) {
+    throw new Error("createRegression groupBy is ambiguous; provide groupBy.");
+  }
+  return candidates[0];
+}

package/src/actions/scales/consumers.js

@@ -0,0 +1,283 @@
+import { deriveBarAggregates } from "../../grammar/bars/aggregate.js";
+import {
+  BAR_GRAINS,
+  resolveBarChannels,
+  resolveBarColorLayout,
+  resolveBarGrain
+} from "../../grammar/bars/policy.js";
+import {
+  countHistogramBins,
+  findHistogramBinIndex,
+  resolveHistogramBins
+} from "../../grammar/histogram.js";
+import { deriveDensityAreaSeries } from "../../grammar/areaSeries.js";
+import { deriveLineSeries } from "../../grammar/lineSeries.js";
+import { resolveSeriesLayoutDomainValues } from "../../grammar/seriesLayout.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField,
+  resolveOrdinalDomain
+} from "../../grammar/scales.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { requireSemanticScale } from "../../selectors/scales.js";
+import { isAggregate } from "../../grammar/aggregate.js";
+import { normalizeRuleDatum } from "../../grammar/rules.js";
+
+export function findScale(program, id) {
+  return requireSemanticScale(program, id);
+}
+
+export function findScaleConsumers(program, id) {
+  const consumers = [];
+  for (const layer of program.semanticSpec.layers) {
+    for (const channel of [
+      "x", "y", "x2", "y2", "xOffset", "color", "strokeDash", "size", "shape",
+      "opacity"
+    ]) {
+      const encoding = layer.encoding?.[channel];
+      if (encoding?.scale === id) consumers.push({ layer, channel, encoding });
+    }
+  }
+  return consumers;
+}
+
+export function resolveConsumerValues(program, consumer) {
+  const dataset = findDataset(program, consumer.layer.data);
+  if (dataset === undefined) {
+    throw new Error(
+      `Mark "${consumer.layer.id}" references unknown dataset "${consumer.layer.data}".`
+    );
+  }
+
+  if (Object.hasOwn(consumer.encoding, "datum")) {
+    return [normalizeRuleDatum(
+      consumer.encoding.datum,
+      consumer.encoding.fieldType,
+      consumer.channel
+    )];
+  }
+
+  if (
+    consumer.channel === "strokeDash" &&
+    !["line", "rule"].includes(consumer.layer.mark?.type)
+  ) {
+    throw new Error("strokeDash scale materialization requires a line mark or rule mark.");
+  }
+  const scale = findScale(program, consumer.encoding.scale);
+  const allowUnknown = Object.hasOwn(scale, "unknown");
+
+  if (
+    ["color", "strokeDash", "xOffset", "shape"].includes(consumer.channel) &&
+    consumer.encoding.fieldType === "nominal"
+  ) {
+    return allowUnknown
+      ? readScaleField(
+          dataset.values,
+          consumer.encoding.field,
+          consumer.encoding.fieldType,
+          { allowUnknown: true }
+        )
+      : readNominalField(dataset.values, consumer.encoding.field);
+  }
+
+  if (
+    consumer.layer.mark?.type === "line" &&
+    isAggregate(consumer.layer.encoding?.y?.aggregate)
+  ) {
+    const derived = deriveLineSeries(dataset.values, consumer.layer);
+    return consumer.channel === "x" ? derived.xValues : derived.yValues;
+  }
+
+  if (
+    resolveBarGrain(consumer.layer) === BAR_GRAINS.aggregate
+  ) {
+    const derived = deriveBarAggregates(dataset.values, consumer.layer);
+    if (consumer.channel === "color") {
+      return derived.values.map(value => value.color);
+    }
+    return consumer.channel === "x" ? derived.xValues : derived.yValues;
+  }
+
+  if (consumer.encoding.fieldType === "temporal") {
+    return allowUnknown
+      ? readScaleField(dataset.values, consumer.encoding.field, "temporal", {
+          allowUnknown: true
+        })
+      : readTemporalField(dataset.values, consumer.encoding.field);
+  }
+  if (["nominal", "ordinal"].includes(consumer.encoding.fieldType)) {
+    if (!["ordinal", "band", "point"].includes(scale.type)) {
+      throw new Error(
+        `Scale materialization requires a quantitative encoding on mark "${consumer.layer.id}".`
+      );
+    }
+    return allowUnknown
+      ? readScaleField(
+          dataset.values,
+          consumer.encoding.field,
+          consumer.encoding.fieldType,
+          { allowUnknown: true }
+        )
+      : readNominalField(dataset.values, consumer.encoding.field);
+  }
+  if (consumer.encoding.fieldType !== "quantitative") {
+    throw new Error(
+      `Scale materialization requires a quantitative encoding on mark "${consumer.layer.id}".`
+    );
+  }
+  return allowUnknown
+    ? readScaleField(dataset.values, consumer.encoding.field, "quantitative", {
+        allowUnknown: true
+      })
+    : readQuantitativeField(dataset.values, consumer.encoding.field);
+}
+
+export function resolveHistogramCountValues(program, consumer) {
+  const xEncoding = consumer.layer.encoding?.x;
+  const xScale = xEncoding?.scale === undefined
+    ? undefined
+    : findScale(program, xEncoding.scale);
+  const dataset = findDataset(program, consumer.layer.data);
+
+  if (xEncoding?.bin === undefined || xScale === undefined) {
+    throw new Error(
+      `Histogram mark "${consumer.layer.id}" requires a binned x scale.`
+    );
+  }
+  if (dataset === undefined) {
+    throw new Error(
+      `Histogram mark "${consumer.layer.id}" requires an existing dataset.`
+    );
+  }
+
+  const xValues = readQuantitativeField(dataset.values, xEncoding.field);
+  const bins = resolveHistogramBins({
+    values: xValues,
+    bin: xEncoding.bin,
+    domain: xScale.domain,
+    nice: xScale.nice ?? true,
+    zero: xScale.zero ?? false
+  });
+  return countHistogramBins(xValues, bins.boundaries);
+}
+
+function resolveHistogramPartitions(program, consumer) {
+  const layer = consumer.layer;
+  const dataset = findDataset(program, layer.data);
+  const xEncoding = layer.encoding.x;
+  const xScale = findScale(program, xEncoding.scale);
+  const xValues = readQuantitativeField(dataset.values, xEncoding.field);
+  const bins = resolveHistogramBins({
+    values: xValues,
+    bin: xEncoding.bin,
+    domain: xScale.domain,
+    nice: xScale.nice ?? true,
+    zero: xScale.zero ?? false
+  });
+  const colorEncoding = layer.encoding?.color;
+  if (colorEncoding?.scale === undefined) {
+    return countHistogramBins(xValues, bins.boundaries).map(value => [value]);
+  }
+
+  const colorScale = findScale(program, colorEncoding.scale);
+  const colorValues = readNominalField(dataset.values, colorEncoding.field);
+  const colorDomain = resolveOrdinalDomain(colorScale.domain, colorValues);
+  const colorIndex = new Map(colorDomain.map((value, index) => [value, index]));
+  const partitions = bins.boundaries.slice(0, -1).map(() =>
+    colorDomain.map(() => 0)
+  );
+  for (let index = 0; index < xValues.length; index += 1) {
+    const bin = findHistogramBinIndex(xValues[index], bins.boundaries);
+    const color = colorIndex.get(colorValues[index]);
+    if (bin !== -1 && color !== undefined) partitions[bin][color] += 1;
+  }
+  return partitions;
+}
+
+function resolveAggregatePartitions(program, consumer) {
+  const layer = consumer.layer;
+  const dataset = findDataset(program, layer.data);
+  const derived = deriveBarAggregates(dataset.values, layer);
+  const channels = resolveBarChannels(layer);
+  const categoryEncoding = layer.encoding[channels.category];
+  const categoryScale = findScale(program, categoryEncoding.scale);
+  const categoryValues = channels.category === "x"
+    ? derived.xValues
+    : derived.yValues;
+  const categoryDomain = resolveOrdinalDomain(categoryScale.domain, categoryValues);
+  const colorEncoding = layer.encoding?.color;
+  if (colorEncoding?.scale === undefined) {
+    const byCategory = new Map(derived.values.map(value => [
+      value[channels.category],
+      value[channels.measure]
+    ]));
+    return categoryDomain.map(value => [byCategory.get(value) ?? 0]);
+  }
+
+  const colorScale = findScale(program, colorEncoding.scale);
+  const colorValues = readNominalField(dataset.values, colorEncoding.field);
+  const colorDomain = resolveOrdinalDomain(colorScale.domain, colorValues);
+  const cells = new Map(derived.values.map(value => [
+    JSON.stringify([value[channels.category], value.color]),
+    value[channels.measure]
+  ]));
+  return categoryDomain.map(category => colorDomain.map(color =>
+    cells.get(JSON.stringify([category, color])) ?? 0
+  ));
+}
+
+function resolveAreaPartitions(program, consumer) {
+  const layer = consumer.layer;
+  const dataset = findDataset(program, layer.data);
+  const transform = dataset?.transform?.length === 1 &&
+    dataset.transform[0].type === "density"
+    ? dataset.transform[0]
+    : undefined;
+  if (transform === undefined) return undefined;
+  const derived = deriveDensityAreaSeries(dataset.values, layer, transform);
+  if (derived.mode !== "y-density") return undefined;
+  const sampleCount = derived.series[0].values.length;
+  if (derived.series.some(series => series.values.length !== sampleCount)) {
+    throw new Error(`Area mark "${layer.id}" requires aligned layout samples.`);
+  }
+  return Array.from({ length: sampleCount }, (_, index) =>
+    derived.series.map(series => series.values[index].y)
+  );
+}
+
+export function resolveSeriesLayoutScaleValues(program, consumer) {
+  if (consumer.layer.mark?.type === "bar") {
+    const grain = resolveBarGrain(consumer.layer);
+    const channels = resolveBarChannels(consumer.layer);
+    if (consumer.channel !== channels?.measure) return undefined;
+    const partitions = grain === BAR_GRAINS.histogram
+      ? resolveHistogramPartitions(program, consumer)
+      : grain === BAR_GRAINS.aggregate
+        ? resolveAggregatePartitions(program, consumer)
+        : undefined;
+    if (partitions === undefined) return undefined;
+    const layout = resolveBarColorLayout(consumer.layer);
+    return {
+      layout,
+      values: resolveSeriesLayoutDomainValues(partitions, layout)
+    };
+  }
+  if (consumer.channel !== "y") return undefined;
+  if (consumer.layer.mark?.type === "area") {
+    const layout = consumer.layer.encoding?.color?.layout;
+    if (layout === undefined || layout === "overlay") return undefined;
+    const partitions = resolveAreaPartitions(program, consumer);
+    if (partitions === undefined) {
+      throw new Error(
+        `Area layout "${layout}" currently requires vertical density series.`
+      );
+    }
+    return {
+      layout,
+      values: resolveSeriesLayoutDomainValues(partitions, layout)
+    };
+  }
+  return undefined;
+}