ggaction 0.0.2 → 0.0.4

package/src/actions/regression/edit.js

@@ -0,0 +1,247 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { normalizeRegressionParameters } from "../../grammar/regression/index.js";
+import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
+import { hasDataset } from "../../selectors/index.js";
+import { findLayer } from "../../selectors/layers.js";
+
+const OPTIONS = Object.freeze([
+  "target", "method", "degree", "span", "confidence", "interval", "band", "line"
+]);
+const STATISTICAL_OPTIONS = Object.freeze([
+  "method", "degree", "span", "confidence", "interval"
+]);
+const BAND_OPTIONS = Object.freeze([
+  "color", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const LINE_OPTIONS = Object.freeze(["strokeWidth", "curve"]);
+
+function resolveRegressionOwner(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.regression !== undefined
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Regression owner id");
+    const layer = findLayer(program, id);
+    if (layer === undefined || !eligible.includes(layer)) {
+      throw new Error(`Unknown regression owner "${id}".`);
+    }
+    return layer;
+  }
+  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("No regression owner is available.");
+  throw new Error("Regression owner is ambiguous; provide target.");
+}
+
+function requirePatch(value, keys, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  validateKeys(value, keys, label);
+  return value;
+}
+
+function validateBandPatch(value) {
+  if (value === false) return false;
+  const patch = requirePatch(value, BAND_OPTIONS, "editRegression band");
+  if (Object.hasOwn(patch, "color")) {
+    validateNonEmptyString(patch.color, "Regression band color");
+  }
+  if (Object.hasOwn(patch, "opacity")) {
+    validateUnitInterval(patch.opacity, "Regression band opacity");
+  }
+  if (Object.hasOwn(patch, "stroke")) {
+    if (patch.stroke !== false) {
+      validateNonEmptyString(patch.stroke, "Regression band stroke");
+    }
+  }
+  if (Object.hasOwn(patch, "strokeWidth")) {
+    validateNonNegativeFinite(
+      patch.strokeWidth,
+      "Regression band strokeWidth"
+    );
+  }
+  if (patch.stroke === false && Object.hasOwn(patch, "strokeWidth")) {
+    throw new Error(
+      "editRegression band cannot set strokeWidth while removing stroke."
+    );
+  }
+  if (Object.hasOwn(patch, "curve")) {
+    validateCurveInterpolation(patch.curve);
+  }
+  return patch;
+}
+
+function validateLinePatch(value) {
+  const patch = requirePatch(value, LINE_OPTIONS, "editRegression line");
+  if (Object.hasOwn(patch, "strokeWidth")) {
+    validateNonNegativeFinite(
+      patch.strokeWidth,
+      "Regression line strokeWidth"
+    );
+  }
+  if (Object.hasOwn(patch, "curve")) {
+    validateCurveInterpolation(patch.curve);
+  }
+  return patch;
+}
+
+function resolveParameters(previous, args) {
+  const method = args.method ?? previous.method;
+  const raw = { method };
+  for (const key of ["degree", "span", "confidence", "interval"]) {
+    if (Object.hasOwn(args, key)) raw[key] = args[key];
+  }
+  if (method === previous.method) {
+    for (const key of ["degree", "span", "confidence", "interval"]) {
+      if (!Object.hasOwn(raw, key) && Object.hasOwn(previous, key)) {
+        raw[key] = previous[key];
+      }
+    }
+  } else if (method !== "loess" && previous.method !== "loess") {
+    for (const key of ["confidence", "interval"]) {
+      if (!Object.hasOwn(raw, key) && Object.hasOwn(previous, key)) {
+        raw[key] = previous[key];
+      }
+    }
+  }
+  return normalizeRegressionParameters(raw);
+}
+
+function nextRevisionId(program, ownerId) {
+  let revision = 1;
+  while (hasDataset(program, `${ownerId}RegressionDataRevision${revision}`)) {
+    revision += 1;
+  }
+  return `${ownerId}RegressionDataRevision${revision}`;
+}
+
+function removeBand(program, id) {
+  return program
+    .editSemantic({ property: `layer[${id}]`, remove: true })
+    .editGraphics({ target: id, remove: true })
+    ._withoutMaterializationConfig(["marks", id]);
+}
+
+export const editRegression = action(
+  {
+    op: "editRegression",
+    description: "Revise a regression model and its owned visible components."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "editRegression");
+    if (!OPTIONS.slice(1).some(key => Object.hasOwn(args, key))) {
+      throw new Error("editRegression requires a statistical or component option.");
+    }
+    const owner = resolveRegressionOwner(this, args.target);
+    const current = this.markConfigs[owner.id].regression;
+    const parameters = resolveParameters(current.parameters, args);
+    const changesStatistics = STATISTICAL_OPTIONS.some(
+      key => Object.hasOwn(args, key)
+    ) && JSON.stringify(parameters) !== JSON.stringify(current.parameters);
+    const bandPatch = Object.hasOwn(args, "band")
+      ? validateBandPatch(args.band)
+      : undefined;
+    const linePatch = Object.hasOwn(args, "line")
+      ? validateLinePatch(args.line)
+      : undefined;
+    if (parameters.method === "loess" && bandPatch !== undefined && bandPatch !== false) {
+      throw new Error("LOESS regression does not support a band object.");
+    }
+
+    const hadBand = current.bandId !== undefined;
+    const wantsBand = parameters.method !== "loess" &&
+      (bandPatch === false
+        ? false
+        : hadBand || bandPatch !== undefined || current.parameters.method === "loess");
+    let dataId = current.dataId;
+    let next = this;
+
+    if (changesStatistics) {
+      dataId = nextRevisionId(this, owner.id);
+      next = next.createRegressionData({
+        id: dataId,
+        source: current.source,
+        x: current.x,
+        y: current.y,
+        ...(current.groupBy === undefined ? {} : { groupBy: current.groupBy }),
+        ...parameters
+      });
+    }
+
+    let bandId = current.bandId;
+    if (hadBand && !wantsBand) {
+      next = removeBand(next, current.bandId);
+      bandId = undefined;
+    } else if (!hadBand && wantsBand) {
+      bandId = `${owner.id}RegressionBands`;
+      next = next.createRegressionBand({
+        id: bandId,
+        data: dataId,
+        x: current.x,
+        lower: "__regression_ci_lower",
+        upper: "__regression_ci_upper",
+        ...(current.groupBy === undefined ? {} : { groupBy: current.groupBy }),
+        coordinate: current.coordinate,
+        xScale: current.xScale,
+        yScale: current.yScale,
+        ...(bandPatch === undefined || bandPatch === false ? {} : bandPatch)
+      });
+    } else if (hadBand && changesStatistics) {
+      const bandConfig = next.markConfigs[bandId];
+      next = next
+        .editSemantic({ property: `layer[${bandId}].data`, value: dataId })
+        ._withMarkConfig(bandId, {
+          ...bandConfig,
+          errorBand: { ...bandConfig.errorBand, data: dataId }
+        });
+    }
+
+    if (changesStatistics) {
+      next = next.editSemantic({
+        property: `layer[${current.lineId}].data`,
+        value: dataId
+      });
+    }
+
+    if (bandId !== undefined) {
+      if (
+        bandPatch !== undefined &&
+        bandPatch !== false &&
+        Object.keys(bandPatch).length > 0 &&
+        hadBand
+      ) {
+        next = next.editRegressionBand({ target: bandId, ...bandPatch });
+      } else if (changesStatistics) {
+        next = next.rematerializeAreaMark({ id: bandId });
+      }
+    }
+    if (linePatch !== undefined && Object.keys(linePatch).length > 0) {
+      next = next.editRegressionLine({ target: current.lineId, ...linePatch });
+    } else if (changesStatistics) {
+      next = next.rematerializeLineMark({ id: current.lineId });
+    }
+
+    if (changesStatistics) {
+      next = next.releaseDerivedData({ id: current.dataId });
+    }
+    return next._withMarkConfig(owner.id, {
+      ...next.markConfigs[owner.id],
+      regression: {
+        ...current,
+        dataId,
+        bandId,
+        parameters
+      }
+    });
+  }
+);

package/src/actions/regression/index.js

@@ -5,6 +5,7 @@ import {
   editRegressionLine
 } from "./components.js";
 import { createRegression } from "./create.js";
+import { editRegression } from "./edit.js";
 
 export {
   createRegressionBand,
@@ -13,6 +14,7 @@ export {
   editRegressionLine
 } from "./components.js";
 export { createRegression } from "./create.js";
+export { editRegression } from "./edit.js";
 
 export function registerRegressionActions(ProgramClass) {
   ProgramClass.prototype.createRegressionBand = createRegressionBand;
@@ -20,4 +22,5 @@ export function registerRegressionActions(ProgramClass) {
   ProgramClass.prototype.editRegressionBand = editRegressionBand;
   ProgramClass.prototype.editRegressionLine = editRegressionLine;
   ProgramClass.prototype.createRegression = createRegression;
+  ProgramClass.prototype.editRegression = editRegression;
 }

package/src/actions/regression/resolve.js

@@ -47,7 +47,9 @@ export function inferRegressionGroup(layer, args) {
   }
   const candidates = [...new Set(
     [layer.encoding?.color, layer.encoding?.shape]
-      .filter(encoding => encoding?.fieldType === "nominal")
+      .filter(encoding =>
+        ["nominal", "ordinal"].includes(encoding?.fieldType)
+      )
       .map(encoding => encoding.field)
   )];
   if (candidates.length > 1) {

package/src/actions/scales/consumers/common.js

@@ -0,0 +1,91 @@
+import {
+  readNominalField,
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField
+} from "../../../grammar/scales/index.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { requireSemanticScale } from "../../../selectors/scales.js";
+import { SCALED_ENCODING_CHANNELS } from "../../../core/vocabulary.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 SCALED_ENCODING_CHANNELS) {
+      const encoding = layer.encoding?.[channel];
+      if (encoding?.scale === id) consumers.push({ layer, channel, encoding });
+    }
+  }
+  return consumers;
+}
+
+export function requireConsumerDataset(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}".`
+    );
+  }
+  return dataset;
+}
+
+export function isDirectCategoricalConsumer(consumer) {
+  return ["color", "strokeDash", "xOffset", "yOffset", "shape"].includes(
+    consumer.channel
+  ) && consumer.encoding.fieldType === "nominal";
+}
+
+export function readConsumerFieldValues(
+  program,
+  consumer,
+  dataset,
+  scale = findScale(program, consumer.encoding.scale)
+) {
+  const allowUnknown = Object.hasOwn(scale, "unknown");
+  if (isDirectCategoricalConsumer(consumer)) {
+    return allowUnknown
+      ? readScaleField(
+          dataset.values,
+          consumer.encoding.field,
+          consumer.encoding.fieldType,
+          { allowUnknown: true }
+        )
+      : readNominalField(dataset.values, consumer.encoding.field);
+  }
+  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);
+}

package/src/actions/scales/consumers/families.js

@@ -0,0 +1,47 @@
+import { deriveBarAggregates } from "../../../grammar/bars/aggregate.js";
+import {
+  BAR_GRAINS,
+  resolveBarGrain
+} from "../../../grammar/bars/policy.js";
+import { deriveLineSeries } from "../../../grammar/lineSeries.js";
+import { isAggregate } from "../../../grammar/aggregate.js";
+import {
+  resolveRectConsumerValues
+} from "../../../materialization/rect.js";
+
+export function resolveMarkFamilyConsumerValues(consumer, dataset) {
+  if (consumer.layer.mark?.type === "rect") {
+    return {
+      matched: true,
+      values: resolveRectConsumerValues(
+        consumer.layer,
+        dataset,
+        consumer.channel
+      )
+    };
+  }
+  if (
+    consumer.layer.mark?.type === "line" &&
+    isAggregate(consumer.layer.encoding?.y?.aggregate)
+  ) {
+    const derived = deriveLineSeries(dataset.values, consumer.layer);
+    return {
+      matched: true,
+      values: 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 {
+        matched: true,
+        values: derived.values.map(value => value.color)
+      };
+    }
+    return {
+      matched: true,
+      values: consumer.channel === "x" ? derived.xValues : derived.yValues
+    };
+  }
+  return { matched: false };
+}

package/src/actions/scales/consumers/index.js

@@ -0,0 +1,41 @@
+import { normalizeRuleDatum } from "../../../grammar/rules.js";
+import {
+  findScale,
+  isDirectCategoricalConsumer,
+  readConsumerFieldValues,
+  requireConsumerDataset
+} from "./common.js";
+import { resolveMarkFamilyConsumerValues } from "./families.js";
+
+export { findScale, findScaleConsumers } from "./common.js";
+export {
+  resolveHistogramCountValues,
+  resolveSeriesLayoutScaleValues
+} from "./seriesLayout.js";
+
+export function resolveConsumerValues(program, consumer) {
+  const dataset = requireConsumerDataset(program, consumer);
+  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);
+  if (isDirectCategoricalConsumer(consumer)) {
+    return readConsumerFieldValues(program, consumer, dataset, scale);
+  }
+  const family = resolveMarkFamilyConsumerValues(consumer, dataset);
+  return family.matched
+    ? family.values
+    : readConsumerFieldValues(program, consumer, dataset, scale);
+}

package/src/actions/scales/{consumers.js → consumers/seriesLayout.js}

@@ -1,138 +1,26 @@
-import { deriveBarAggregates } from "../../grammar/bars/aggregate.js";
+import { deriveBarAggregates } from "../../../grammar/bars/aggregate.js";
 import {
   BAR_GRAINS,
   resolveBarChannels,
   resolveBarColorLayout,
   resolveBarGrain
-} from "../../grammar/bars/policy.js";
+} 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";
+} from "../../../grammar/histogram.js";
+import { deriveDensityAreaSeries } from "../../../grammar/areaSeries.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);
-}
+} from "../../../grammar/scales/index.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { findScale } from "./common.js";
 
 export function resolveHistogramCountValues(program, consumer) {
   const xEncoding = consumer.layer.encoding?.x;
@@ -140,7 +28,6 @@ export function resolveHistogramCountValues(program, consumer) {
     ? 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.`
@@ -151,7 +38,6 @@ export function resolveHistogramCountValues(program, consumer) {
       `Histogram mark "${consumer.layer.id}" requires an existing dataset.`
     );
   }
-
   const xValues = readQuantitativeField(dataset.values, xEncoding.field);
   const bins = resolveHistogramBins({
     values: xValues,
@@ -180,7 +66,6 @@ function resolveHistogramPartitions(program, consumer) {
   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);
@@ -208,14 +93,16 @@ function resolveAggregatePartitions(program, consumer) {
     : derived.yValues;
   const categoryDomain = resolveOrdinalDomain(categoryScale.domain, categoryValues);
   const colorEncoding = layer.encoding?.color;
-  if (colorEncoding?.scale === undefined) {
+  if (
+    colorEncoding?.scale === undefined ||
+    colorEncoding.fieldType === "quantitative"
+  ) {
     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);

package/src/actions/scales/create.js

@@ -15,7 +15,7 @@ import {
   isContinuousColorScaleType,
   isDiscretizedColorScaleType,
   normalizeScaleDefinition
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import { findSemanticScale } from "../../selectors/scales.js";
 
 const CREATE_SCALE_OPTIONS = Object.freeze([