ggaction 0.0.2 → 0.0.3

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.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.js

@@ -24,6 +24,8 @@ import { findDataset } from "../../selectors/datasets.js";
 import { requireSemanticScale } from "../../selectors/scales.js";
 import { isAggregate } from "../../grammar/aggregate.js";
 import { normalizeRuleDatum } from "../../grammar/rules.js";
+import { SCALED_ENCODING_CHANNELS } from "../../core/vocabulary.js";
+import { resolveRectConsumerValues } from "../../materialization/rect.js";
 
 export function findScale(program, id) {
   return requireSemanticScale(program, id);
@@ -32,10 +34,7 @@ export function findScale(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"
-    ]) {
+    for (const channel of SCALED_ENCODING_CHANNELS) {
       const encoding = layer.encoding?.[channel];
       if (encoding?.scale === id) consumers.push({ layer, channel, encoding });
     }
@@ -67,9 +66,16 @@ export function resolveConsumerValues(program, consumer) {
   }
   const scale = findScale(program, consumer.encoding.scale);
   const allowUnknown = Object.hasOwn(scale, "unknown");
+  if (consumer.layer.mark?.type === "rect") {
+    return resolveRectConsumerValues(
+      consumer.layer,
+      dataset,
+      consumer.channel
+    );
+  }
 
   if (
-    ["color", "strokeDash", "xOffset", "shape"].includes(consumer.channel) &&
+    ["color", "strokeDash", "xOffset", "yOffset", "shape"].includes(consumer.channel) &&
     consumer.encoding.fieldType === "nominal"
   ) {
     return allowUnknown
@@ -208,7 +214,10 @@ 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]

package/src/actions/scales/definitions.js

@@ -23,6 +23,10 @@ import {
   validateScaleTypeForRole,
   isDiscretePositionScaleType
 } from "../../grammar/scales.js";
+import {
+  validateRadialRange,
+  validateThetaRange
+} from "../../grammar/polar.js";
 import { withScaleUnknown } from "../../grammar/scales.js";
 import { findSemanticScale } from "../../selectors/scales.js";
 
@@ -87,6 +91,7 @@ export function resolvePositionScaleDefinition(
       );
     }
   }
+  else if (channel === "theta") validateLinearScaleType(type);
   else validateScaleTypeForRole(type, SCALE_ROLES.quantitativePosition);
   const scale = {
     id,
@@ -108,7 +113,11 @@ export function resolvePositionScaleDefinition(
         ["ordinal", "nominal"].includes(fieldType)
           ? validateOrdinalDomain(value)
           : validateScaleDomain(value),
-      validateRange: (_scaleType, value) => validateScaleRange(value)
+      validateRange: (_scaleType, value) => channel === "theta"
+        ? validateThetaRange(value)
+        : channel === "radius"
+          ? validateRadialRange(value)
+          : validateScaleRange(value)
     })
   };
   return withScaleUnknown(scale, { ...existing, ...options }, channel);
@@ -305,15 +314,15 @@ export function resolveOpacityScaleDefinition(program, options) {
   return withScaleUnknown(scale, { ...existing, ...options }, "opacity");
 }
 
-export function resolveOffsetScaleDefinition(program, options) {
+export function resolveOffsetScaleDefinition(program, options, channel = "xOffset") {
   optionsObject(options);
   validateKeys(options, [...BASE_OPTIONS, "unknown"], "scale");
-  const id = validateUserId(options.id ?? "xOffset", "Scale id");
+  const id = validateUserId(options.id ?? channel, "Scale id");
   const existing = findSemanticScale(program, id);
   return withScaleUnknown({
     id,
     type: validateOrdinalScaleType(options.type ?? existing?.type ?? "ordinal"),
     domain: validateOrdinalDomain(options.domain ?? existing?.domain ?? "auto"),
     range: validateScaleRange(options.range ?? existing?.range ?? "auto")
-  }, { ...existing, ...options }, "xOffset");
+  }, { ...existing, ...options }, channel);
 }

package/src/actions/scales/edit.js

@@ -1,7 +1,6 @@
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
-import { isPlainObject } from "../../core/immutable.js";
-import { validateKeys } from "../../core/validation.js";
+import { validateOptionObject } from "../../core/validation.js";
 import {
   isTransformedScaleType,
   SCALE_ROLES,
@@ -23,6 +22,10 @@ import {
   hasOrdinalDomain,
   normalizeScaleDefinition
 } from "../../grammar/scales.js";
+import {
+  validateRadialRange,
+  validateThetaRange
+} from "../../grammar/polar.js";
 import { getMarkMaterializationStep } from "../../materialization/marks.js";
 import {
   applyMaterializationPlan
@@ -32,13 +35,17 @@ import {
   requireSemanticScale
 } from "../../selectors/scales.js";
 import { findScaleConsumers } from "./consumers.js";
+import { normalizePositionScaleChannel } from "../../core/vocabulary.js";
 
 const OPTIONS = Object.freeze([
   "id", "type", "domain", "range", "nice", "zero", "clamp", "reverse",
   "base", "exponent", "constant", "paddingInner", "paddingOuter", "padding",
-  "align", "interpolate", "unknown"
+  "align", "interpolate", "unknown", "palette"
 ]);
-const EDITABLE = Object.freeze(OPTIONS.filter(option => option !== "id"));
+const EDITABLE = Object.freeze(
+  OPTIONS.filter(option => !["id", "palette"].includes(option))
+);
+const REQUESTED_CHANGES = Object.freeze(OPTIONS.filter(option => option !== "id"));
 
 function resolveScaleId(program, requested) {
   if (requested !== undefined) {
@@ -60,13 +67,9 @@ function resolveScaleId(program, requested) {
   );
 }
 
-function normalizeChannel(channel) {
-  return channel === "x2" ? "x" : channel === "y2" ? "y" : channel;
-}
-
 function resolveChannel(consumers, id) {
   const channels = new Set(
-    consumers.map(consumer => normalizeChannel(consumer.channel))
+    consumers.map(consumer => normalizePositionScaleChannel(consumer.channel))
   );
   if (channels.size > 1) {
     throw new Error(`Scale "${id}" cannot be shared across channels.`);
@@ -76,6 +79,8 @@ function resolveChannel(consumers, id) {
 
 function validateRangeForChannel(scale, channel, value) {
   if (value === "auto") return value;
+  if (channel === "theta") return validateThetaRange(value);
+  if (channel === "radius") return validateRadialRange(value);
   if (scale.type === "sequential") {
     return validateSequentialColorRange(value);
   }
@@ -97,7 +102,7 @@ function validateTypeTransition(scale, nextType, channel, consumers) {
   if (nextType === "sequential" || isDiscretizedColorScaleType(nextType)) {
     const discretized = isDiscretizedColorScaleType(nextType);
     if (channel !== "color" || consumers.some(consumer =>
-      consumer.encoding.fieldType === "nominal" ||
+      ["nominal", "ordinal"].includes(consumer.encoding.fieldType) ||
       (discretized && (
         consumer.encoding.fieldType !== "quantitative" ||
         consumer.layer.mark?.type !== "point"
@@ -113,7 +118,7 @@ function validateTypeTransition(scale, nextType, channel, consumers) {
   if (nextType === "time") {
     if (
       consumers.length > 0 &&
-      (!["x", "y"].includes(channel) ||
+      (!["x", "y", "theta"].includes(channel) ||
         consumers.some(consumer => consumer.encoding.fieldType !== "temporal"))
     ) {
       throw new Error(
@@ -126,7 +131,7 @@ function validateTypeTransition(scale, nextType, channel, consumers) {
   if (discrete) {
     if (
       consumers.length > 0 &&
-      (!["x", "y"].includes(channel) || consumers.some(consumer =>
+      (!["x", "y", "theta"].includes(channel) || consumers.some(consumer =>
         !["nominal", "ordinal"].includes(consumer.encoding.fieldType)
       ))
     ) {
@@ -145,13 +150,16 @@ function validateTypeTransition(scale, nextType, channel, consumers) {
   const quantitative = nextType === "linear" || isTransformedScaleType(nextType);
   if (
     !quantitative ||
-    (consumers.length > 0 && !["x", "y"].includes(channel))
+    (consumers.length > 0 && !["x", "y", "theta", "radius"].includes(channel))
   ) {
     throw new Error(
       "editScale type transition currently requires a quantitative position scale."
     );
   }
   validateScaleTypeForRole(nextType, SCALE_ROLES.quantitativePosition);
+  if (channel === "theta" && nextType !== "linear") {
+    throw new Error("Theta quantitative position currently requires a linear scale.");
+  }
   if (consumers.some(consumer => consumer.encoding.fieldType !== "quantitative")) {
     throw new Error(
       `Scale "${scale.id}" has a consumer incompatible with type "${nextType}".`
@@ -242,20 +250,35 @@ export const editScale = action(
     description: "Edit an existing scale and rematerialize its consumers."
   },
   function (args = {}) {
-    if (!isPlainObject(args)) {
-      throw new TypeError("editScale options must be a plain object.");
-    }
-    validateKeys(args, OPTIONS, "editScale");
-    if (!EDITABLE.some(property => Object.hasOwn(args, property))) {
+    validateOptionObject(args, OPTIONS, "editScale");
+    if (!REQUESTED_CHANGES.some(property => Object.hasOwn(args, property))) {
       throw new Error("editScale requires at least one editable property.");
     }
+    const hasPalette = Object.hasOwn(args, "palette");
+    if (hasPalette && Object.hasOwn(args, "range")) {
+      throw new Error("editScale cannot specify both palette and range.");
+    }
 
     const id = resolveScaleId(this, args.id);
     const scale = requireSemanticScale(this, id);
     const consumers = findScaleConsumers(this, id);
     const channel = resolveChannel(consumers, id);
+    if (
+      hasPalette &&
+      channel !== "color" &&
+      scale.type !== "sequential" &&
+      !isDiscretizedColorScaleType(scale.type)
+    ) {
+      throw new Error("editScale palette requires a color scale.");
+    }
+    const patch = !hasPalette
+      ? args
+      : Object.fromEntries([
+          ...Object.entries(args).filter(([key]) => key !== "palette"),
+          ["range", { palette: args.palette }]
+        ]);
     validateLegendTypeTransition(this, scale, args.type ?? scale.type);
-    const definition = normalizeDefinition(scale, channel, consumers, args);
+    const definition = normalizeDefinition(scale, channel, consumers, patch);
 
     let next = this;
     for (const property of EDITABLE) {