ggaction 0.0.3 → 0.0.5

package/src/grammar/gradientProfile.js

@@ -0,0 +1,213 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  deriveKernelDensity,
+  validateDensityKernel,
+  validateDensityNormalization
+} from "./density.js";
+
+export const GRADIENT_PROFILE_FIELDS = Object.freeze({
+  category: "__gradientPlot_category",
+  values: "__gradientPlot_values",
+  intensities: "__gradientPlot_intensities",
+  lower: "__gradientPlot_lower",
+  upper: "__gradientPlot_upper",
+  center: "__gradientPlot_center",
+  count: "__gradientPlot_count"
+});
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "category", "field", "bandwidth", "extent", "steps", "kernel",
+  "normalization", "center", "as", "resolve", "resolved"
+]);
+const OUTPUT_KEYS = Object.freeze(Object.keys(GRADIENT_PROFILE_FIELDS));
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function validatePair(value, label) {
+  if (
+    !Array.isArray(value) || value.length !== 2 ||
+    !value.every(Number.isFinite) || value[0] >= value[1]
+  ) {
+    throw new RangeError(`${label} must be an ascending pair of finite numbers.`);
+  }
+  return value;
+}
+
+function validateOutputs(as, { category, field }) {
+  if (!isPlainObject(as)) {
+    throw new TypeError("Gradient profile 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(`Gradient profile as requires exactly ${OUTPUT_KEYS.join(", ")}.`);
+  }
+  const values = OUTPUT_KEYS.map(key =>
+    requireField(as[key], `Gradient profile as.${key}`)
+  );
+  if (new Set(values).size !== values.length) {
+    throw new Error("Gradient profile output fields must be distinct.");
+  }
+  const inputCollisions = values.filter(value => value === category || value === field);
+  if (
+    inputCollisions.some(value => value !== category) ||
+    as.category !== category ||
+    values.slice(1).includes(category)
+  ) {
+    throw new Error("Gradient profile output fields must not collide with input fields.");
+  }
+}
+
+export function validateGradientProfileTransform(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Gradient profile transform must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown gradient profile transform property "${unknown}".`);
+  }
+  if (value.type !== "gradientProfile") {
+    throw new Error(`Unsupported gradient profile transform "${value.type}".`);
+  }
+  const category = requireField(value.category, "Gradient profile category");
+  const field = requireField(value.field, "Gradient profile field");
+  if (category === field) {
+    throw new Error("Gradient profile category and field must be distinct.");
+  }
+  if (
+    value.bandwidth !== "auto" &&
+    (!Number.isFinite(value.bandwidth) || value.bandwidth <= 0)
+  ) {
+    throw new RangeError(
+      "Gradient profile bandwidth must be a positive finite number or auto."
+    );
+  }
+  if (value.extent !== "auto") {
+    validatePair(value.extent, "Gradient profile extent");
+  }
+  if (!Number.isInteger(value.steps) || value.steps < 2) {
+    throw new RangeError("Gradient profile steps must be an integer of at least 2.");
+  }
+  validateDensityKernel(value.kernel);
+  validateDensityNormalization(value.normalization);
+  if (!["mean", "median"].includes(value.center)) {
+    throw new Error(`Unsupported gradient profile center "${value.center}".`);
+  }
+  if (value.resolve !== "shared") {
+    throw new Error(`Unsupported gradient profile resolve "${value.resolve}".`);
+  }
+  validateOutputs(value.as, { category, field });
+  if (value.resolved !== undefined) {
+    const resolved = value.resolved;
+    if (
+      !isPlainObject(resolved) ||
+      Object.keys(resolved).some(key => ![
+        "bandwidth", "extent", "intensityDomain"
+      ].includes(key)) ||
+      !Number.isFinite(resolved.bandwidth) || resolved.bandwidth <= 0
+    ) {
+      throw new TypeError("Gradient profile resolved provenance is invalid.");
+    }
+    validatePair(resolved.extent, "Gradient profile resolved extent");
+    validatePair(
+      resolved.intensityDomain,
+      "Gradient profile resolved intensityDomain"
+    );
+  }
+  return value;
+}
+
+export function normalizeGradientProfileTransform(options = {}) {
+  const transform = {
+    type: "gradientProfile",
+    category: options.category,
+    field: options.field,
+    bandwidth: options.bandwidth ?? "auto",
+    extent: options.extent ?? "auto",
+    steps: options.steps ?? 64,
+    kernel: options.kernel ?? "gaussian",
+    normalization: options.normalization ?? "unit",
+    center: options.center ?? "median",
+    as: options.as ?? { ...GRADIENT_PROFILE_FIELDS, category: options.category },
+    resolve: "shared"
+  };
+  validateGradientProfileTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function requestedGradientProfileTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  return cloneAndFreeze(requested);
+}
+
+function centerOf(values, type) {
+  if (type === "mean") {
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = (sorted.length - 1) / 2;
+  const lower = Math.floor(middle);
+  const upper = Math.ceil(middle);
+  return (sorted[lower] + sorted[upper]) / 2;
+}
+
+export function deriveGradientProfiles(rows, transform) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Gradient profile rows must be an array.");
+  }
+  validateGradientProfileTransform(transform);
+  const density = deriveKernelDensity(rows, {
+    field: transform.field,
+    groupBy: transform.category,
+    bandwidth: transform.bandwidth,
+    extent: transform.extent,
+    steps: transform.steps,
+    kernel: transform.kernel,
+    normalization: transform.normalization,
+    as: ["__gradientProfile_value", "__gradientProfile_intensity"]
+  });
+  const validRows = rows.filter(row =>
+    row !== null && typeof row === "object" &&
+    row[transform.category] !== undefined && row[transform.category] !== null &&
+    row[transform.category] !== "" && Number.isFinite(row[transform.field])
+  );
+  const maximumIntensity = Math.max(
+    ...density.values.map(row => row.__gradientProfile_intensity)
+  );
+  if (!Number.isFinite(maximumIntensity) || maximumIntensity <= 0) {
+    throw new Error("Gradient profile requires a positive resolved density range.");
+  }
+  const values = density.groups.map(category => {
+    const samples = density.values.filter(
+      row => row[transform.category] === category
+    );
+    const observations = validRows
+      .filter(row => row[transform.category] === category)
+      .map(row => row[transform.field]);
+    return {
+      [transform.as.category]: category,
+      [transform.as.values]: samples.map(row => row.__gradientProfile_value),
+      [transform.as.intensities]: samples.map(
+        row => row.__gradientProfile_intensity
+      ),
+      [transform.as.lower]: density.extent[0],
+      [transform.as.upper]: density.extent[1],
+      [transform.as.center]: centerOf(observations, transform.center),
+      [transform.as.count]: observations.length
+    };
+  });
+  return cloneAndFreeze({
+    values,
+    categories: density.groups,
+    bandwidth: density.bandwidth,
+    extent: density.extent,
+    intensityDomain: [0, maximumIntensity]
+  });
+}

package/src/grammar/horizon.js

@@ -0,0 +1,455 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { normalizePalette } from "./palettes.js";
+import {
+  isNominalValue,
+  normalizeTemporalValue
+} from "./scales/index.js";
+
+export const HORIZON_RESOLUTIONS = Object.freeze(["shared", "independent"]);
+export const HORIZON_MISSING_POLICIES = Object.freeze(["break", "error"]);
+export const HORIZON_OVERFLOW_POLICIES = Object.freeze(["clip", "error"]);
+
+const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType"]);
+const OUTPUT_PROPERTIES = Object.freeze([
+  "x", "lower", "upper", "group", "color", "sign", "band", "segment"
+]);
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function validateEncoding(value, role) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`Horizon ${role} encoding must be a plain object.`);
+  }
+  const unknown = Object.keys(value).find(
+    property => !ENCODING_PROPERTIES.includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon ${role} encoding property "${unknown}".`);
+  }
+  const field = requireField(value.field, `Horizon ${role} field`);
+  const fieldType = value.fieldType ?? (role === "x" ? "quantitative" : "quantitative");
+  const supported = role === "x"
+    ? ["quantitative", "temporal"]
+    : ["quantitative"];
+  if (!supported.includes(fieldType)) {
+    throw new Error(
+      `Horizon ${role} fieldType must be ${supported.join(" or ")}.`
+    );
+  }
+  return { field, fieldType };
+}
+
+function validateOutputFields(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Horizon as must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    property => !OUTPUT_PROPERTIES.includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon output field "${unknown}".`);
+  }
+  const output = Object.fromEntries(OUTPUT_PROPERTIES.map(property => [
+    property,
+    requireField(value[property], `Horizon ${property} output field`)
+  ]));
+  if (new Set(Object.values(output)).size !== OUTPUT_PROPERTIES.length) {
+    throw new Error("Horizon output fields must be distinct.");
+  }
+  return output;
+}
+
+function validatePalette(value = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Horizon palette must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    property => !["positive", "negative"].includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon palette property "${unknown}".`);
+  }
+  return {
+    positive: normalizePalette(value.positive ?? "blues"),
+    negative: normalizePalette(value.negative ?? "reds")
+  };
+}
+
+function validateResolved(value) {
+  if (!isPlainObject(value) || Object.keys(value).some(key => key !== "extents")) {
+    throw new TypeError("Horizon resolved provenance must contain only extents.");
+  }
+  if (!Array.isArray(value.extents) || value.extents.length === 0) {
+    throw new TypeError("Horizon resolved extents must be a non-empty array.");
+  }
+  for (const [index, entry] of value.extents.entries()) {
+    if (
+      !isPlainObject(entry) ||
+      Object.keys(entry).some(key => !["group", "extent", "bandHeight"].includes(key)) ||
+      !Number.isFinite(entry.extent) ||
+      entry.extent < 0 ||
+      !Number.isFinite(entry.bandHeight) ||
+      entry.bandHeight < 0
+    ) {
+      throw new TypeError(`Horizon resolved extent ${index} is invalid.`);
+    }
+    if (Object.hasOwn(entry, "group") && !isNominalValue(entry.group)) {
+      throw new TypeError(`Horizon resolved group ${index} must be nominal.`);
+    }
+  }
+  return value;
+}
+
+export function requestedHorizonTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  void _resolved;
+  return requested;
+}
+
+export function validateHorizonTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Horizon transform must be a plain object.");
+  }
+  const supported = [
+    "type", "x", "y", "groupBy", "bands", "baseline", "extent",
+    "resolve", "missing", "overflow", "palette", "as", "resolved"
+  ];
+  const unknown = Object.keys(transform).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon transform property "${unknown}".`);
+  }
+  if (transform.type !== "horizon") {
+    throw new Error(`Unsupported Horizon transform "${transform.type}".`);
+  }
+  const x = validateEncoding(transform.x, "x");
+  const y = validateEncoding(transform.y, "y");
+  if (x.field === y.field) {
+    throw new Error("Horizon x and y fields must differ.");
+  }
+  if (transform.groupBy !== undefined) {
+    requireField(transform.groupBy, "Horizon groupBy");
+    if ([x.field, y.field].includes(transform.groupBy)) {
+      throw new Error("Horizon groupBy must differ from x and y fields.");
+    }
+  }
+  if (!Number.isInteger(transform.bands) || transform.bands <= 0) {
+    throw new RangeError("Horizon bands must be a positive integer.");
+  }
+  if (!Number.isFinite(transform.baseline)) {
+    throw new TypeError("Horizon baseline must be finite.");
+  }
+  if (
+    transform.extent !== "auto" &&
+    (!Number.isFinite(transform.extent) || transform.extent <= 0)
+  ) {
+    throw new RangeError('Horizon extent must be "auto" or a positive number.');
+  }
+  if (!HORIZON_RESOLUTIONS.includes(transform.resolve)) {
+    throw new Error(`Unknown Horizon resolve "${transform.resolve}".`);
+  }
+  if (!HORIZON_MISSING_POLICIES.includes(transform.missing)) {
+    throw new Error(`Unknown Horizon missing policy "${transform.missing}".`);
+  }
+  if (!HORIZON_OVERFLOW_POLICIES.includes(transform.overflow)) {
+    throw new Error(`Unknown Horizon overflow policy "${transform.overflow}".`);
+  }
+  const palette = validatePalette(transform.palette);
+  for (const [sign, value] of Object.entries(palette)) {
+    if (value.count !== undefined && value.count !== transform.bands) {
+      throw new Error(
+        `Horizon ${sign} palette count must equal bands (${transform.bands}).`
+      );
+    }
+  }
+  const as = validateOutputFields(transform.as);
+  if (transform.groupBy !== undefined && Object.values(as).includes(transform.groupBy)) {
+    throw new Error("Horizon output fields must not collide with groupBy.");
+  }
+  if (transform.resolved !== undefined) validateResolved(transform.resolved);
+  return cloneAndFreeze({
+    ...transform,
+    x,
+    y,
+    palette,
+    as
+  });
+}
+
+function orderedX(value, encoding, rowIndex) {
+  if (encoding.fieldType === "temporal") {
+    return normalizeTemporalValue(value, encoding.field, rowIndex);
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `Horizon x field "${encoding.field}" must contain finite numbers at row ${rowIndex}.`
+    );
+  }
+  return value;
+}
+
+function groupRows(rows, transform) {
+  const groups = [];
+  const indexed = new Map();
+  for (const [sourceRowIndex, row] of rows.entries()) {
+    if (!isPlainObject(row)) {
+      throw new TypeError(`Horizon row ${sourceRowIndex} must be a plain object.`);
+    }
+    const group = transform.groupBy === undefined ? undefined : row[transform.groupBy];
+    if (transform.groupBy !== undefined && !isNominalValue(group)) {
+      throw new TypeError(
+        `Horizon groupBy field "${transform.groupBy}" must contain nominal values at row ${sourceRowIndex}.`
+      );
+    }
+    const key = transform.groupBy === undefined
+      ? "__horizon_ungrouped__"
+      : `${typeof group}:${String(group)}`;
+    if (!indexed.has(key)) {
+      const entry = { group, groupIndex: groups.length, rows: [] };
+      indexed.set(key, entry);
+      groups.push(entry);
+    }
+    const y = row[transform.y.field];
+    const missing = !Number.isFinite(y);
+    if (missing && transform.missing === "error") {
+      throw new Error(
+        `Horizon y field "${transform.y.field}" is missing at source row ${sourceRowIndex}.`
+      );
+    }
+    indexed.get(key).rows.push({
+      sourceRowIndex,
+      x: orderedX(row[transform.x.field], transform.x, sourceRowIndex),
+      y,
+      missing
+    });
+  }
+  for (const entry of groups) {
+    entry.rows.sort((left, right) =>
+      left.x - right.x || left.sourceRowIndex - right.sourceRowIndex
+    );
+    for (let index = 1; index < entry.rows.length; index += 1) {
+      if (entry.rows[index - 1].x === entry.rows[index].x) {
+        throw new Error(
+          `Horizon group ${JSON.stringify(entry.group ?? null)} has duplicate x value ${entry.rows[index].x}.`
+        );
+      }
+    }
+  }
+  return groups;
+}
+
+function splitSegments(rows, baseline) {
+  const segments = [];
+  let current = [];
+  const flush = () => {
+    if (current.length > 0) segments.push(current);
+    current = [];
+  };
+  for (const row of rows) {
+    if (row.missing) {
+      flush();
+      continue;
+    }
+    current.push({ ...row, signed: row.y - baseline, interpolated: false });
+  }
+  flush();
+  return segments;
+}
+
+function insertCrossings(points, baseline) {
+  if (points.length < 2) return points.map(point => ({ ...point }));
+  const output = [{ ...points[0] }];
+  for (let index = 1; index < points.length; index += 1) {
+    const left = points[index - 1];
+    const right = points[index];
+    if (left.signed * right.signed < 0) {
+      const fraction = (baseline - left.y) / (right.y - left.y);
+      output.push({
+        sourceRowIndex: undefined,
+        x: left.x + (right.x - left.x) * fraction,
+        y: baseline,
+        missing: false,
+        signed: 0,
+        interpolated: true,
+        leftSourceRowIndex: left.sourceRowIndex,
+        rightSourceRowIndex: right.sourceRowIndex,
+        fraction
+      });
+    }
+    output.push({ ...right });
+  }
+  return output;
+}
+
+function pointSign(value) {
+  return value > 0 ? "positive" : value < 0 ? "negative" : "zero";
+}
+
+function runsForSign(points, desired) {
+  const runs = [];
+  let current = [];
+  let pendingZeros = [];
+  const flush = () => {
+    if (current.some(point => pointSign(point.signed) === desired)) {
+      runs.push(current);
+    }
+    current = [];
+  };
+  for (const point of points) {
+    const sign = pointSign(point.signed);
+    if (sign === desired) {
+      if (current.length === 0 && pendingZeros.length > 0) {
+        current.push(...pendingZeros);
+      }
+      current.push(point);
+      pendingZeros = [];
+    } else if (sign === "zero") {
+      if (current.length > 0) {
+        current.push(point);
+        flush();
+      }
+      pendingZeros = [point];
+    } else {
+      flush();
+      pendingZeros = [];
+    }
+  }
+  flush();
+  return runs;
+}
+
+function maximumMagnitude(group) {
+  return Math.max(
+    0,
+    ...group.segments.flatMap(segment =>
+      segment.map(point => Math.abs(point.signed))
+    )
+  );
+}
+
+function resolvedExtents(groups, transform) {
+  if (transform.extent !== "auto") return groups.map(() => transform.extent);
+  if (transform.resolve === "shared") {
+    const shared = Math.max(0, ...groups.map(maximumMagnitude));
+    return groups.map(() => shared);
+  }
+  return groups.map(maximumMagnitude);
+}
+
+function seriesForGroup(group, extent, transform) {
+  if (extent === 0) return [];
+  const bandHeight = extent / transform.bands;
+  const output = [];
+  for (const sign of ["negative", "positive"]) {
+    const runs = [];
+    let segmentIndex = 0;
+    for (const source of group.segments) {
+      for (const points of runsForSign(source, sign)) {
+        runs.push({ points, segmentIndex });
+        segmentIndex += 1;
+      }
+    }
+    for (let bandIndex = 0; bandIndex < transform.bands; bandIndex += 1) {
+      for (const run of runs) {
+        const points = run.points.map(point => {
+          const rawMagnitude = Math.abs(point.signed);
+          if (rawMagnitude > extent && transform.overflow === "error") {
+            throw new RangeError(
+              `Horizon magnitude ${rawMagnitude} exceeds extent ${extent}.`
+            );
+          }
+          const magnitude = Math.min(rawMagnitude, extent);
+          const amplitude = Math.min(
+            bandHeight,
+            Math.max(0, magnitude - bandIndex * bandHeight)
+          );
+          return {
+            ...point,
+            magnitude,
+            rawMagnitude,
+            amplitude,
+            fraction: amplitude / bandHeight,
+            overflowed: rawMagnitude > extent
+          };
+        });
+        if (points.some(point => point.amplitude > 0)) {
+          const groupIdentity = transform.groupBy === undefined
+            ? null
+            : group.group;
+          output.push({
+            group: group.group,
+            groupIndex: group.groupIndex,
+            sign,
+            bandIndex,
+            segmentIndex: run.segmentIndex,
+            seriesKey: JSON.stringify([
+              groupIdentity,
+              sign,
+              bandIndex,
+              run.segmentIndex
+            ]),
+            colorKey: `${sign}:${bandIndex}`,
+            bandHeight,
+            points
+          });
+        }
+      }
+    }
+  }
+  return output;
+}
+
+function generatedRows(series, transform) {
+  return series.flatMap(item => item.points.map(point => ({
+    ...(transform.groupBy === undefined
+      ? {}
+      : { [transform.groupBy]: item.group }),
+    [transform.as.x]: point.x,
+    [transform.as.lower]: 0,
+    [transform.as.upper]: point.fraction,
+    [transform.as.group]: item.seriesKey,
+    [transform.as.color]: item.colorKey,
+    [transform.as.sign]: item.sign,
+    [transform.as.band]: item.bandIndex,
+    [transform.as.segment]: item.segmentIndex
+  })));
+}
+
+export function deriveHorizon(rows, requested) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Horizon values must be an array.");
+  }
+  if (rows.length === 0) {
+    throw new Error("Horizon requires at least one source row.");
+  }
+  const transform = validateHorizonTransform(requested);
+  const grouped = groupRows(rows, transform).map(group => ({
+    ...group,
+    segments: splitSegments(group.rows, transform.baseline).map(segment =>
+      insertCrossings(segment, transform.baseline)
+    )
+  }));
+  if (!grouped.some(group => group.rows.some(row => !row.missing))) {
+    throw new Error("Horizon requires at least one finite y value.");
+  }
+  const extents = resolvedExtents(grouped, transform);
+  const groups = grouped.map((group, index) => ({
+    ...(transform.groupBy === undefined ? {} : { group: group.group }),
+    extent: extents[index],
+    bandHeight: extents[index] / transform.bands
+  }));
+  const series = grouped.flatMap((group, index) =>
+    seriesForGroup(group, extents[index], transform)
+  );
+  return cloneAndFreeze({
+    transform: requestedHorizonTransform(transform),
+    resolved: { extents: groups },
+    groups,
+    series,
+    values: generatedRows(series, transform)
+  });
+}