ggaction 0.0.1

package/src/grammar/interval.js

@@ -0,0 +1,343 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { aggregateScalarValues } from "./aggregate.js";
+
+const CENTER_VALUES = Object.freeze(["mean", "median"]);
+const EXTENT_VALUES = Object.freeze(["stderr", "stdev", "ci", "iqr"]);
+const TRANSFORM_KEYS = Object.freeze([
+  "type",
+  "field",
+  "groupBy",
+  "center",
+  "extent",
+  "level",
+  "as"
+]);
+const OUTPUT_KEYS = Object.freeze(["center", "lower", "upper"]);
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+
+function validateGrouping(groupBy) {
+  if (
+    !Array.isArray(groupBy) ||
+    !groupBy.every(field => typeof field === "string" && field.length > 0) ||
+    new Set(groupBy).size !== groupBy.length
+  ) {
+    throw new TypeError(
+      "Interval groupBy must contain unique field names."
+    );
+  }
+}
+
+function validateOutputs(as, occupied) {
+  if (!isPlainObject(as)) {
+    throw new TypeError("Interval 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("Interval as requires exactly center, lower, and upper.");
+  }
+  const values = OUTPUT_KEYS.map(key => as[key]);
+  values.forEach((value, index) => {
+    nonEmptyString(value, `Interval as.${OUTPUT_KEYS[index]}`);
+  });
+  if (new Set(values).size !== values.length) {
+    throw new Error("Interval output fields must be distinct.");
+  }
+  if (values.some(value => occupied.has(value))) {
+    throw new Error("Interval output fields must not collide with input fields.");
+  }
+}
+
+export function validateIntervalTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Interval transform must be a plain object.");
+  }
+  const unknown = Object.keys(transform).find(
+    key => !TRANSFORM_KEYS.includes(key)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown interval transform property "${unknown}".`);
+  }
+  if (transform.type !== "interval") {
+    throw new Error(`Unsupported interval transform "${transform.type}".`);
+  }
+  nonEmptyString(transform.field, "Interval field");
+  validateGrouping(transform.groupBy);
+  if (!CENTER_VALUES.includes(transform.center)) {
+    throw new Error(`Unsupported interval center "${transform.center}".`);
+  }
+  if (!EXTENT_VALUES.includes(transform.extent)) {
+    throw new Error(`Unsupported interval extent "${transform.extent}".`);
+  }
+  if (
+    (transform.center === "median") !== (transform.extent === "iqr")
+  ) {
+    throw new Error("Median intervals require iqr, and iqr requires median.");
+  }
+  if (transform.extent === "ci") {
+    if (
+      !Number.isFinite(transform.level) ||
+      transform.level <= 0 ||
+      transform.level >= 1
+    ) {
+      throw new RangeError("Interval CI level must be between 0 and 1.");
+    }
+  } else if (transform.level !== undefined) {
+    throw new Error("Interval level is supported only for ci extent.");
+  }
+  validateOutputs(
+    transform.as,
+    new Set([transform.field, ...transform.groupBy])
+  );
+}
+
+function normalizeGrouping(groupBy) {
+  const values = groupBy === undefined
+    ? []
+    : Array.isArray(groupBy) ? [...groupBy] : [groupBy];
+  validateGrouping(values);
+  return values;
+}
+
+export function normalizeIntervalParameters({
+  center = "mean",
+  extent = "ci",
+  level
+} = {}) {
+  const resolvedLevel = extent === "ci" ? level ?? 0.95 : level;
+  const candidate = {
+    type: "interval",
+    field: "__interval_input",
+    groupBy: [],
+    center,
+    extent,
+    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel }),
+    as: {
+      center: "__interval_center",
+      lower: "__interval_lower",
+      upper: "__interval_upper"
+    }
+  };
+  validateIntervalTransform(candidate);
+  return cloneAndFreeze({
+    center,
+    extent,
+    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel })
+  });
+}
+
+const LANCZOS = Object.freeze([
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9.984369578019572e-6,
+  1.5056327351493116e-7
+]);
+
+function logGamma(value) {
+  if (value < 0.5) {
+    return Math.log(Math.PI) - Math.log(Math.sin(Math.PI * value)) -
+      logGamma(1 - value);
+  }
+  const shifted = value - 1;
+  let sum = 0.9999999999998099;
+  for (const [index, coefficient] of LANCZOS.entries()) {
+    sum += coefficient / (shifted + index + 1);
+  }
+  const t = shifted + LANCZOS.length - 0.5;
+  return 0.5 * Math.log(2 * Math.PI) +
+    (shifted + 0.5) * Math.log(t) - t + Math.log(sum);
+}
+
+function betaFraction(a, b, x) {
+  const maximumIterations = 200;
+  const epsilon = 3e-14;
+  const floor = 1e-300;
+  const sum = a + b;
+  let c = 1;
+  let d = 1 - sum * x / (a + 1);
+  if (Math.abs(d) < floor) d = floor;
+  d = 1 / d;
+  let result = d;
+
+  for (let iteration = 1; iteration <= maximumIterations; iteration += 1) {
+    const even = 2 * iteration;
+    let coefficient = iteration * (b - iteration) * x /
+      ((a + even - 1) * (a + even));
+    d = 1 + coefficient * d;
+    if (Math.abs(d) < floor) d = floor;
+    c = 1 + coefficient / c;
+    if (Math.abs(c) < floor) c = floor;
+    d = 1 / d;
+    result *= d * c;
+
+    coefficient = -(a + iteration) * (sum + iteration) * x /
+      ((a + even) * (a + even + 1));
+    d = 1 + coefficient * d;
+    if (Math.abs(d) < floor) d = floor;
+    c = 1 + coefficient / c;
+    if (Math.abs(c) < floor) c = floor;
+    d = 1 / d;
+    const delta = d * c;
+    result *= delta;
+    if (Math.abs(delta - 1) <= epsilon) return result;
+  }
+  throw new Error("Student-t calculation did not converge.");
+}
+
+function regularizedBeta(x, a, b) {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const front = Math.exp(
+    logGamma(a + b) - logGamma(a) - logGamma(b) +
+    a * Math.log(x) + b * Math.log1p(-x)
+  );
+  return x < (a + 1) / (a + b + 2)
+    ? front * betaFraction(a, b, x) / a
+    : 1 - front * betaFraction(b, a, 1 - x) / b;
+}
+
+function studentTCdf(value, degreesOfFreedom) {
+  if (value === 0) return 0.5;
+  const x = degreesOfFreedom /
+    (degreesOfFreedom + value * value);
+  const tail = 0.5 * regularizedBeta(
+    x,
+    degreesOfFreedom / 2,
+    0.5
+  );
+  return value > 0 ? 1 - tail : tail;
+}
+
+export function studentTCritical(degreesOfFreedom, level) {
+  if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
+    throw new RangeError("Student-t degreesOfFreedom must be a positive integer.");
+  }
+  if (!Number.isFinite(level) || level <= 0 || level >= 1) {
+    throw new RangeError("Student-t level must be between 0 and 1.");
+  }
+  const target = 0.5 + level / 2;
+  let low = 0;
+  let high = 1;
+  while (studentTCdf(high, degreesOfFreedom) < target) high *= 2;
+  for (let iteration = 0; iteration < 100; iteration += 1) {
+    const midpoint = (low + high) / 2;
+    if (studentTCdf(midpoint, degreesOfFreedom) < target) low = midpoint;
+    else high = midpoint;
+  }
+  return (low + high) / 2;
+}
+
+function isMissing(value) {
+  return value === undefined || value === null ||
+    (typeof value === "number" && Number.isNaN(value));
+}
+
+function isGroupValue(value) {
+  return typeof value === "string" || typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+function stableNumber(value) {
+  return Number(value.toFixed(12));
+}
+
+function deriveGroup(values, transform) {
+  if (transform.center === "median") {
+    if (values.length === 0) return undefined;
+    return {
+      center: aggregateScalarValues(values, "median"),
+      lower: aggregateScalarValues(values, "q1"),
+      upper: aggregateScalarValues(values, "q3")
+    };
+  }
+  if (values.length < 2) return undefined;
+  const center = aggregateScalarValues(values, "mean");
+  const spread = transform.extent === "stdev"
+    ? aggregateScalarValues(values, "stdev")
+    : transform.extent === "stderr"
+      ? aggregateScalarValues(values, "stderr")
+      : studentTCritical(values.length - 1, transform.level) *
+        aggregateScalarValues(values, "stderr");
+  return { center, lower: center - spread, upper: center + spread };
+}
+
+export function deriveInterval(rows, transform) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Interval rows must be an array.");
+  }
+  validateIntervalTransform(transform);
+  const groups = new Map();
+  for (const row of rows) {
+    if (!isPlainObject(row)) continue;
+    const value = row[transform.field];
+    if (isMissing(value) || !Number.isFinite(value)) {
+      if (value !== undefined && value !== null && typeof value !== "number") {
+        throw new TypeError(
+          `Interval field "${transform.field}" must contain numeric or missing values.`
+        );
+      }
+      continue;
+    }
+    const groupValues = transform.groupBy.map(field => row[field]);
+    if (groupValues.some(isMissing)) continue;
+    if (!groupValues.every(isGroupValue)) {
+      throw new TypeError("Interval grouping fields must contain nominal values.");
+    }
+    const key = JSON.stringify(groupValues);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        fields: Object.fromEntries(
+          transform.groupBy.map((field, index) => [field, groupValues[index]])
+        ),
+        values: []
+      });
+    }
+    groups.get(key).values.push(value);
+  }
+
+  const output = [];
+  for (const group of groups.values()) {
+    const result = deriveGroup(group.values, transform);
+    if (result === undefined) continue;
+    output.push({
+      ...group.fields,
+      [transform.as.center]: stableNumber(result.center),
+      [transform.as.lower]: stableNumber(result.lower),
+      [transform.as.upper]: stableNumber(result.upper)
+    });
+  }
+  return cloneAndFreeze(output);
+}
+
+export function normalizeIntervalTransform({
+  field,
+  groupBy,
+  center,
+  extent,
+  level,
+  as
+}) {
+  nonEmptyString(field, "Interval field");
+  const grouping = normalizeGrouping(groupBy);
+  const parameters = normalizeIntervalParameters({ center, extent, level });
+  const transform = {
+    type: "interval",
+    field,
+    groupBy: grouping,
+    ...parameters,
+    as
+  };
+  validateIntervalTransform(transform);
+  return cloneAndFreeze(transform);
+}

package/src/grammar/lineSeries.js

@@ -0,0 +1,197 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readTemporalField
+} from "./scales.js";
+import {
+  aggregateRows,
+  isAggregate,
+  validateAggregateFieldType,
+  validateAggregateFieldValues,
+} from "./aggregate.js";
+
+const SERIES_CHANNELS = Object.freeze(["group", "color", "strokeDash"]);
+
+function requireLineEncoding(layer) {
+  if (layer?.mark?.type !== "line") {
+    throw new Error("Line series derivation requires a semantic line mark.");
+  }
+
+  const x = layer.encoding?.x;
+  const y = layer.encoding?.y;
+
+  if (x === undefined) {
+    throw new Error(`Line mark "${layer.id}" requires a temporal x encoding.`);
+  }
+
+  const aggregateMode =
+    x?.fieldType === "temporal" && isAggregate(y?.aggregate);
+  const directQuantitative =
+    x?.fieldType === "quantitative" &&
+    y?.fieldType === "quantitative" &&
+    y.aggregate === undefined;
+  const directTemporal =
+    y?.aggregate === undefined &&
+    ((x?.fieldType === "temporal" && y?.fieldType === "quantitative") ||
+      (x?.fieldType === "quantitative" && y?.fieldType === "temporal"));
+  if (!aggregateMode && !directQuantitative && !directTemporal) {
+    if (x?.fieldType === "temporal") {
+      throw new Error(
+        `Line mark "${layer.id}" requires a supported aggregate y encoding.`
+      );
+    }
+    throw new Error(
+      `Line mark "${layer.id}" requires temporal/aggregate or direct quantitative x/y encodings.`
+    );
+  }
+  if (aggregateMode) {
+    validateAggregateFieldType(y.aggregate, y.fieldType);
+  }
+  return {
+    x,
+    y,
+    isAggregate: aggregateMode,
+    directTemporal
+  };
+}
+
+function readSeriesFields(rows, layer) {
+  const fields = [];
+  const values = new Map();
+
+  for (const channel of SERIES_CHANNELS) {
+    const encoding = layer.encoding?.[channel];
+
+    if (encoding?.field === undefined) continue;
+    if (encoding.fieldType !== "nominal") {
+      throw new Error(`Line ${channel} encoding on mark "${layer.id}" must be nominal.`);
+    }
+
+    if (!values.has(encoding.field)) {
+      fields.push(encoding.field);
+      values.set(encoding.field, readNominalField(rows, encoding.field));
+    }
+  }
+
+  return { fields, values };
+}
+
+function groupKey(values) {
+  return JSON.stringify(values);
+}
+
+export function deriveLineSeries(rows, layer) {
+  const { x, y, isAggregate, directTemporal } = requireLineEncoding(layer);
+  if (isAggregate) {
+    validateAggregateFieldValues(rows, y.field, y.fieldType);
+  }
+  const xValues = x.fieldType === "temporal"
+    ? readTemporalField(rows, x.field)
+    : readQuantitativeField(rows, x.field);
+  const yValues = isAggregate
+    ? undefined
+    : y.fieldType === "temporal"
+      ? readTemporalField(rows, y.field)
+      : readQuantitativeField(rows, y.field);
+  const seriesFields = readSeriesFields(rows, layer);
+
+  if (directTemporal) {
+    const groups = new Map();
+    for (let index = 0; index < rows.length; index += 1) {
+      const dimensions = seriesFields.fields.map(
+        field => seriesFields.values.get(field)[index]
+      );
+      const key = groupKey(dimensions);
+      const series = groups.get(key) ?? {
+        key: Object.fromEntries(
+          seriesFields.fields.map((field, item) => [field, dimensions[item]])
+        ),
+        values: []
+      };
+      series.values.push({ x: xValues[index], y: yValues[index] });
+      groups.set(key, series);
+    }
+    const orderBy = x.fieldType === "temporal" ? "x" : "y";
+    const series = [...groups.values()].flatMap(item => {
+      const values = item.values.sort(
+        (left, right) => left[orderBy] - right[orderBy]
+      );
+      return values.length < 2 ? [] : [{ key: item.key, values }];
+    });
+    if (series.length === 0) {
+      throw new Error(
+        `Line series on mark "${layer.id}" requires at least two direct points.`
+      );
+    }
+    return cloneAndFreeze({
+      xValues: series.flatMap(item => item.values.map(value => value.x)),
+      yValues: series.flatMap(item => item.values.map(value => value.y)),
+      series
+    });
+  }
+  const aggregateGroups = new Map();
+
+  for (let index = 0; index < rows.length; index += 1) {
+    const dimensions = seriesFields.fields.map(
+      field => seriesFields.values.get(field)[index]
+    );
+    const key = groupKey([xValues[index], ...dimensions]);
+    const group = aggregateGroups.get(key) ?? {
+      x: xValues[index],
+      dimensions,
+      rows: []
+    };
+
+    group.rows.push(rows[index]);
+    aggregateGroups.set(key, group);
+  }
+
+  if (aggregateGroups.size === 0) {
+    throw new Error(`Line mark "${layer.id}" has no values to aggregate.`);
+  }
+
+  const seriesGroups = new Map();
+
+  for (const group of aggregateGroups.values()) {
+    const value = isAggregate
+      ? aggregateRows(group.rows, y.field, y.aggregate)
+      : group.rows.reduce((sum, row) => sum + row[y.field], 0);
+    if (value === undefined) continue;
+    const key = groupKey(group.dimensions);
+    const series = seriesGroups.get(key) ?? {
+      key: Object.fromEntries(
+        seriesFields.fields.map((field, index) => [field, group.dimensions[index]])
+      ),
+      values: []
+    };
+
+    series.values.push({
+      x: group.x,
+      y: value
+    });
+    seriesGroups.set(key, series);
+  }
+
+  const series = [...seriesGroups.values()].flatMap(item => {
+    const values = item.values.sort((left, right) => left.x - right.x);
+
+    if (values.length < 2) {
+      return [];
+    }
+
+    return [{ key: item.key, values }];
+  });
+
+  if (series.length === 0) {
+    throw new Error(
+      `Line series on mark "${layer.id}" requires at least two aggregate points.`
+    );
+  }
+
+  return cloneAndFreeze({
+    xValues: series.flatMap(item => item.values.map(value => value.x)),
+    yValues: series.flatMap(item => item.values.map(value => value.y)),
+    series
+  });
+}

package/src/grammar/markFilter.js

@@ -0,0 +1,46 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { normalizeMarkSelector } from "./markSelection.js";
+
+const TRANSFORM_KEYS = Object.freeze(["type", "target", "selector"]);
+
+export function validateMarkFilterTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Mark filter transform must be a plain object.");
+  }
+  const unknown = Object.keys(transform).find(
+    key => !TRANSFORM_KEYS.includes(key)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown mark filter transform property "${unknown}".`);
+  }
+  if (transform.type !== "markFilter") {
+    throw new Error(`Unsupported mark filter transform "${transform.type}".`);
+  }
+  if (typeof transform.target !== "string" || transform.target.length === 0) {
+    throw new TypeError("Mark filter target must be a non-empty string.");
+  }
+  normalizeMarkSelector(transform.selector);
+}
+
+export function normalizeMarkFilterTransform(target, selector) {
+  const transform = {
+    type: "markFilter",
+    target,
+    selector: normalizeMarkSelector(selector)
+  };
+  validateMarkFilterTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function deriveMarkFilteredRows(sourceRows, items, selectedKeys) {
+  if (!Array.isArray(sourceRows)) {
+    throw new TypeError("Mark filter source values must be an array.");
+  }
+  const selected = new Set(selectedKeys);
+  const members = new Set(
+    items
+      .filter(item => selected.has(item.key))
+      .flatMap(item => item.members)
+  );
+  return cloneAndFreeze(sourceRows.filter(row => members.has(row)));
+}