ggaction 0.0.4 → 0.0.5

package/src/actions/violinPlots/create.js

@@ -0,0 +1,198 @@
+import { action } from "../../core/action.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "../charts/shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "split", "color", "density",
+  "area", "guides"
+]);
+const POSITION_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
+const DENSITY_OPTIONS = Object.freeze([
+  "bandwidth", "extent", "steps", "kernel", "normalization", "width"
+]);
+const WIDTH_OPTIONS = Object.freeze(["band", "resolve"]);
+const SPLIT_OPTIONS = Object.freeze(["field", "domain"]);
+const AREA_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
+
+function inferFieldType(dataset, encoding, label) {
+  if (encoding.fieldType !== undefined) return encoding.fieldType;
+  if (typeof encoding.field !== "string" || encoding.field.length === 0) {
+    throw new TypeError(`${label} field must be a non-empty string.`);
+  }
+  const values = dataset.values
+    .map(row => row?.[encoding.field])
+    .filter(value => value !== undefined && value !== null && value !== "");
+  if (values.length === 0) {
+    throw new Error(`${label} field "${encoding.field}" has no values.`);
+  }
+  return values.every(Number.isFinite) ? "quantitative" : "nominal";
+}
+
+function normalizePosition(dataset, value, label) {
+  const encoding = normalizeFieldEncoding(value, label);
+  validateOptionObject(encoding, POSITION_OPTIONS, label);
+  return {
+    ...encoding,
+    fieldType: inferFieldType(dataset, encoding, label)
+  };
+}
+
+function normalizeDensity(value) {
+  if (value === undefined) return { options: {}, width: undefined };
+  validateOptionObject(value, DENSITY_OPTIONS, "createViolinPlot density");
+  if (value.width !== undefined) {
+    validateOptionObject(
+      value.width,
+      WIDTH_OPTIONS,
+      "createViolinPlot density.width"
+    );
+  }
+  const { width, ...options } = value;
+  return { options, width };
+}
+
+function normalizeSplit(value) {
+  if (value === undefined) return undefined;
+  validateOptionObject(value, SPLIT_OPTIONS, "createViolinPlot split");
+  if (typeof value.field !== "string" || value.field.length === 0) {
+    throw new TypeError("createViolinPlot split.field must be a non-empty string.");
+  }
+  return { ...value };
+}
+
+function axisGuideOptions(value, field) {
+  if (value === false) return false;
+  return {
+    ...(value ?? {}),
+    title: {
+      text: field,
+      ...(value?.title ?? {})
+    }
+  };
+}
+
+function guideOptions(guides, x, y, category, color) {
+  if (guides === false) return false;
+  const axes = guides.axes === false
+    ? false
+    : {
+        ...(guides.axes ?? {}),
+        x: axisGuideOptions(guides.axes?.x, x.field),
+        y: axisGuideOptions(guides.axes?.y, y.field)
+      };
+  const redundantLegend = color?.field === category.field &&
+    !Object.hasOwn(guides, "legend");
+  return {
+    ...guides,
+    axes,
+    ...(redundantLegend ? { legend: false } : {})
+  };
+}
+
+export const createViolinPlot = action(
+  {
+    op: "createViolinPlot",
+    description: "Create a categorical kernel-density violin plot."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createViolinPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "violinPlot",
+      operation: "createViolinPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createViolinPlot");
+    const dataset = findDataset(this, data);
+    const x = normalizePosition(dataset, args.x, "createViolinPlot x");
+    const y = normalizePosition(dataset, args.y, "createViolinPlot y");
+    const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
+    const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
+    if (xCategorical === yCategorical || (
+      x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
+    )) {
+      throw new Error(
+        "createViolinPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const category = xCategorical ? x : y;
+    const value = xCategorical ? y : x;
+    if (value.fieldType !== "quantitative") {
+      throw new Error(
+        "createViolinPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const split = normalizeSplit(args.split);
+    if (split?.field === category.field) {
+      throw new Error("createViolinPlot split field must differ from its category field.");
+    }
+    const color = normalizeEncoding(args.color, "createViolinPlot color");
+    if (
+      color !== undefined &&
+      ![category.field, split?.field].includes(color.field)
+    ) {
+      throw new Error(
+        "createViolinPlot color must encode its category or split field."
+      );
+    }
+    const density = normalizeDensity(args.density);
+    const area = normalizeAppearance(
+      args.area,
+      AREA_OPTIONS,
+      "createViolinPlot area"
+    );
+    if (color !== undefined && Object.hasOwn(area, "fill")) {
+      throw new Error("createViolinPlot area.fill cannot be combined with color.");
+    }
+    const guides = guideOptions(
+      normalizeGuides(args.guides, "createViolinPlot"),
+      x,
+      y,
+      category,
+      color
+    );
+    const { strokeWidth, ...areaCreate } = area;
+    const hasFillStroke = strokeWidth !== undefined && area.stroke === undefined;
+    let next = this.createAreaMark({
+      id,
+      data,
+      ...areaCreate,
+      ...(area.stroke === undefined || strokeWidth === undefined
+        ? {}
+        : { strokeWidth })
+    });
+    if (hasFillStroke) {
+      next = next.configureAreaStrokeFromFill({ id, strokeWidth });
+    }
+    next = next.encodeDensity({
+      target: id,
+      source: data,
+      field: value.field,
+      groupBy: category.field,
+      densityChannel: xCategorical ? "x" : "y",
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...(value.scale === undefined ? {} : { valueScale: value.scale }),
+      ...density.options,
+      placement: {
+        type: "category",
+        ...(density.width === undefined ? {} : { width: density.width }),
+        ...(split === undefined ? {} : { split }),
+        ...(category.scale === undefined ? {} : { scale: category.scale })
+      }
+    });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/violinPlots/index.js

@@ -0,0 +1,5 @@
+import { createViolinPlot } from "./create.js";
+
+export function registerViolinPlotActions(ProgramClass) {
+  ProgramClass.prototype.createViolinPlot = createViolinPlot;
+}

package/src/core/textMetrics.js

@@ -21,3 +21,50 @@ export function measureTextWidth(text, { fontSize } = {}) {
     0
   );
 }
+
+function horizontalExtents(width, align) {
+  if (align === "center") return [-width / 2, width / 2];
+  if (["right", "end"].includes(align)) return [-width, 0];
+  return [0, width];
+}
+
+function verticalExtents(fontSize, baseline) {
+  if (baseline === "middle") return [-fontSize / 2, fontSize / 2];
+  if (["top", "hanging"].includes(baseline)) return [0, fontSize];
+  if (["bottom", "ideographic"].includes(baseline)) return [-fontSize, 0];
+  return [-fontSize * 0.8, fontSize * 0.2];
+}
+
+export function resolveTextBounds({
+  x,
+  y,
+  text,
+  fontSize,
+  textAlign = "left",
+  textBaseline = "alphabetic",
+  rotation = 0
+} = {}) {
+  if (![x, y, rotation].every(Number.isFinite)) {
+    throw new TypeError("Text bounds require finite x, y, and rotation values.");
+  }
+  const width = measureTextWidth(text, { fontSize });
+  const [left, right] = horizontalExtents(width, textAlign);
+  const [top, bottom] = verticalExtents(fontSize, textBaseline);
+  const cosine = Math.cos(rotation);
+  const sine = Math.sin(rotation);
+  const corners = [
+    [left, top],
+    [right, top],
+    [right, bottom],
+    [left, bottom]
+  ].map(([localX, localY]) => ({
+    x: x + localX * cosine - localY * sine,
+    y: y + localX * sine + localY * cosine
+  }));
+  return Object.freeze({
+    left: Math.min(...corners.map(point => point.x)),
+    right: Math.max(...corners.map(point => point.x)),
+    top: Math.min(...corners.map(point => point.y)),
+    bottom: Math.max(...corners.map(point => point.y))
+  });
+}

package/src/core/vocabulary.js

@@ -31,9 +31,11 @@ export const ENCODING_CHANNELS = Object.freeze([
   "radius",
   "color",
   "strokeDash",
+  "strokeWidth",
   "size",
   "shape",
   "group",
+  "pathOrder",
   "opacity",
   "text"
 ]);
@@ -111,7 +113,9 @@ export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
 });
 
 export const SCALED_ENCODING_CHANNELS = Object.freeze(
-  ENCODING_CHANNELS.filter(channel => !["group", "text"].includes(channel))
+  ENCODING_CHANNELS.filter(channel =>
+    !["group", "pathOrder", "text"].includes(channel)
+  )
 );
 
 export const POSITION_ENCODING_CHANNELS = Object.freeze(
@@ -200,7 +204,8 @@ export const LEGEND_CONFIG_KINDS = Object.freeze([
   "size",
   "gradient",
   "interval",
-  "opacity"
+  "opacity",
+  "strokeWidth"
 ]);
 
 export function includesVocabulary(vocabulary, value) {

package/src/grammar/arcs.js

@@ -36,42 +36,79 @@ function colorValues(rows, encoding) {
     : readNominalField(rows, encoding.field);
 }
 
-function countSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
+export function readArcThetaWeights(rows, field, layerId = "arc") {
+  if (!Array.isArray(rows)) throw new TypeError("Arc theta weights require rows.");
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("Arc theta weight must be a non-empty string.");
+  }
+  const weights = rows.map((row, index) => {
+    const value = row?.[field];
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TypeError(
+        `Arc theta weight field "${field}" must contain non-negative finite numbers at row ${index}.`
+      );
+    }
+    return value;
+  });
+  if (weights.every(value => value === 0)) {
+    throw new Error(`Arc mark "${layerId}" theta weights must have a positive total.`);
+  }
+  return cloneAndFreeze(weights);
+}
+
+function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
   const theta = layer.encoding.theta;
-  if (theta.aggregate !== "count") {
-    throw new Error(`Arc mark "${layer.id}" requires count or radial layout.`);
+  if (!["count", "sum"].includes(theta.aggregate)) {
+    throw new Error(`Arc mark "${layer.id}" requires count, sum, or radial layout.`);
   }
   const values = readNominalField(rows, theta.field);
   const colors = colorValues(rows, layer.encoding?.color);
+  const weights = theta.aggregate === "count"
+    ? rows.map(() => 1)
+    : readArcThetaWeights(rows, theta.weight, layer.id);
   const groups = new Map(thetaScale.domain.map(value => [value, []]));
   for (let index = 0; index < rows.length; index += 1) {
     const group = groups.get(values[index]);
     if (group === undefined) {
       throw new Error(`Arc theta value "${values[index]}" is outside the scale domain.`);
     }
-    group.push({ row: rows[index], color: colors[index], sourceIndex: index });
+    group.push({
+      row: rows[index],
+      color: colors[index],
+      sourceIndex: index,
+      weight: weights[index]
+    });
   }
-  const total = [...groups.values()].reduce((sum, group) => sum + group.length, 0);
-  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no rows to count.`);
+  const total = [...groups.values()].reduce(
+    (sum, group) => sum + group.reduce((groupSum, item) => groupSum + item.weight, 0),
+    0
+  );
+  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no positive theta weight.`);
   const start = thetaScale.range[0];
   const span = thetaScale.range[1] - thetaScale.range[0];
   const innerRadius = frame.availableRadius * innerRadiusRatio;
   let cursor = start;
   const sectors = [];
-  for (const value of thetaScale.domain) {
+  const positiveValues = thetaScale.domain.filter(value =>
+    groups.get(value).some(item => item.weight > 0)
+  );
+  for (const [positiveIndex, value] of positiveValues.entries()) {
     const group = groups.get(value);
-    if (group.length === 0) continue;
-    const endTheta = cursor + group.length / total * span;
+    const aggregateValue = group.reduce((sum, item) => sum + item.weight, 0);
+    const endTheta = positiveIndex === positiveValues.length - 1
+      ? thetaScale.range[1]
+      : cursor + aggregateValue / total * span;
     const distinctColors = [...new Set(group.map(item => item.color))];
     if (distinctColors.length > 1) {
       throw new Error(
-        `Count arc theta group "${value}" must resolve to one color value.`
+        `Aggregated arc theta group "${value}" must resolve to one color value.`
       );
     }
     sectors.push({
       key: value,
       theta: value,
       count: group.length,
+      aggregateValue,
       color: distinctColors[0],
       startTheta: cursor,
       endTheta,
@@ -147,8 +184,8 @@ export function deriveArcSectors(rows, layer, {
   ) {
     throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
   }
-  const sectors = theta.aggregate === "count"
-    ? countSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
+  const sectors = ["count", "sum"].includes(theta.aggregate)
+    ? proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
     : radialSectors(rows, layer, thetaScale, radiusScale);
   return cloneAndFreeze({ sectors });
 }

package/src/grammar/areaSeries.js

@@ -8,12 +8,14 @@ import {
   layoutSeriesPartition,
   validateColorLayout
 } from "./seriesLayout.js";
+import { stableOrderPathValues } from "./pathOrder.js";
+import { deriveCategoricalDensitySeries } from "./categoricalDensity.js";
 
 export function deriveAreaSeries(rows, layer) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Area series derivation requires a semantic area mark.");
   }
-  const { x, y, x2, y2, group } = layer.encoding ?? {};
+  const { x, y, x2, y2, group, color } = layer.encoding ?? {};
   const vertical =
     ["quantitative", "temporal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
@@ -46,24 +48,44 @@ export function deriveAreaSeries(rows, layer) {
   const groupValues = group === undefined
     ? rows.map(() => undefined)
     : readNominalField(rows, group.field);
+  const colorValues = color === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, color.field);
+  const pathOrder = layer.encoding?.pathOrder;
+  const orderValues = pathOrder === undefined
+    ? undefined
+    : readQuantitativeField(rows, pathOrder.field);
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
     const key = groupValues[index];
     const series = groups.get(key) ?? {
-      key: group === undefined ? {} : { [group.field]: key },
+      key: {
+        ...(group === undefined ? {} : { [group.field]: key }),
+        ...(color === undefined ? {} : { [color.field]: colorValues[index] })
+      },
       values: []
     };
+    if (
+      color !== undefined &&
+      !Object.is(series.key[color.field], colorValues[index])
+    ) {
+      throw new Error(
+        `Area series "${String(key)}" must have one color value.`
+      );
+    }
     series.values.push(vertical
       ? {
           x: independentValues[index],
           y: lower[index],
-          y2: upper[index]
+          y2: upper[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         }
       : {
           x: lower[index],
           x2: upper[index],
-          y: independentValues[index]
+          y: independentValues[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         });
     groups.set(key, series);
   }
@@ -72,7 +94,13 @@ export function deriveAreaSeries(rows, layer) {
   }
   const series = [...groups.values()].map(item => {
     const key = vertical ? "x" : "y";
-    const values = item.values.sort((left, right) => left[key] - right[key]);
+    const values = pathOrder === undefined
+      ? item.values.sort((left, right) => left[key] - right[key])
+      : stableOrderPathValues(
+          item.values.map(({ pathOrder: _pathOrder, ...value }) => value),
+          item.values.map(value => value.pathOrder),
+          pathOrder.order
+        );
     if (values.length < 2) {
       throw new Error(
         `Area series on mark "${layer.id}" requires at least two points.`
@@ -96,9 +124,17 @@ export function deriveDensityAreaSeries(rows, layer, transform) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Density area derivation requires a semantic area mark.");
   }
+  if (layer.encoding?.pathOrder !== undefined) {
+    throw new Error(
+      `Density area mark "${layer.id}" does not support path order.`
+    );
+  }
   if (transform?.type !== "density" || !Array.isArray(transform.as)) {
     throw new Error(`Area mark "${layer.id}" requires density provenance.`);
   }
+  if (transform.placement?.type === "category") {
+    return deriveCategoricalDensitySeries(rows, layer, transform);
+  }
   const { x, y, group } = layer.encoding ?? {};
   if (
     x?.fieldType !== "quantitative" ||