ggaction 0.0.12 → 0.0.15

package/src/grammar/density.js

@@ -10,6 +10,15 @@ import {
   requireFiniteResult,
   stableFiniteDeviation
 } from "./numeric.js";
+import {
+  normalizeStatisticalWeight,
+  readStatisticalWeights,
+  summarizeStatisticalWeights,
+  validateWeightedNumericFields,
+  weightedBandwidth,
+  weightedEntriesExtent,
+  weightedKernelEstimate
+} from "./weightedStatistics.js";
 
 const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
 
@@ -37,6 +46,25 @@ export const DENSITY_WIDTH_RESOLUTIONS = Object.freeze([
   "shared", "independent"
 ]);
 
+export function normalizeDensityTransform(args = {}) {
+  const transform = {
+    type: "density",
+    field: args.field,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bandwidth: args.bandwidth ?? "auto",
+    extent: args.extent ?? "auto",
+    steps: args.steps ?? 100,
+    kernel: args.kernel ?? "gaussian",
+    normalization: args.normalization ?? "unit",
+    as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
+    resolve: args.resolve ?? "shared",
+    ...(args.weight === undefined ? {} : { weight: args.weight }),
+    ...(args.placement === undefined ? {} : { placement: args.placement })
+  };
+  validateDensityTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
 export function validateDensitySteps(value, label = "Density steps") {
   if (!Number.isInteger(value) || value < 2) {
     throw new RangeError(`${label} must be an integer of at least 2.`);
@@ -261,10 +289,88 @@ function validateStoredDensityPlacement(value, groupBy) {
   return value;
 }
 
+function validateResolvedBandwidths(value, transform) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError(
+      "Density resolved bandwidths must be a non-empty array."
+    );
+  }
+  const normalized = value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} must be a plain object.`
+      );
+    }
+    const unknown = Object.keys(item).find(
+      key => !["group", "split", "bandwidth"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(
+        `Unknown density resolved bandwidth property "${unknown}".`
+      );
+    }
+    if (!Number.isFinite(item.bandwidth) || item.bandwidth <= 0) {
+      throw new RangeError(
+        `Density resolved bandwidth ${index} must be positive and finite.`
+      );
+    }
+    if (transform.groupBy === undefined) {
+      if (Object.hasOwn(item, "group")) {
+        throw new Error(
+          "Density resolved bandwidth cannot store a group without groupBy."
+        );
+      }
+    } else if (!Object.hasOwn(item, "group") || !isNominalValue(item.group)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} requires a nominal group.`
+      );
+    }
+    if (transform.placement?.split === undefined) {
+      if (Object.hasOwn(item, "split")) {
+        throw new Error(
+          "Density resolved bandwidth cannot store a split without split placement."
+        );
+      }
+    } else if (!Object.hasOwn(item, "split") || !isNominalValue(item.split)) {
+      throw new TypeError(
+        `Density resolved bandwidth ${index} requires a nominal split.`
+      );
+    }
+    return item;
+  });
+  for (let index = 0; index < normalized.length; index += 1) {
+    const duplicate = normalized.slice(0, index).some(item =>
+      Object.is(item.group, normalized[index].group) &&
+      Object.is(item.split, normalized[index].split)
+    );
+    if (duplicate) {
+      throw new Error(
+        `Density resolved bandwidth ${index} duplicates an earlier profile.`
+      );
+    }
+  }
+  return value;
+}
+
+function hasValidResolvedBandwidthState(resolved, transform) {
+  const hasBandwidth = Object.hasOwn(resolved, "bandwidth");
+  const hasBandwidths = Object.hasOwn(resolved, "bandwidths");
+  if (hasBandwidth === hasBandwidths) return false;
+  if (hasBandwidth) {
+    return Number.isFinite(resolved.bandwidth) && resolved.bandwidth > 0;
+  }
+  try {
+    validateResolvedBandwidths(resolved.bandwidths, transform);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function validateDensityTransform(transform) {
   const supported = [
     "type", "field", "groupBy", "bandwidth", "extent", "steps", "as",
-    "resolve", "kernel", "normalization", "placement", "resolved"
+    "resolve", "kernel", "normalization", "placement", "weight", "resolved"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
@@ -274,6 +380,9 @@ export function validateDensityTransform(transform) {
     throw new Error(`Unsupported density transform "${transform.type}".`);
   }
   requireField(transform.field, "Density field");
+  if (transform.weight !== undefined) {
+    normalizeStatisticalWeight(transform.weight, "Density weight");
+  }
   if (transform.groupBy !== undefined) {
     requireField(transform.groupBy, "Density groupBy");
   }
@@ -301,10 +410,9 @@ export function validateDensityTransform(transform) {
       typeof resolved !== "object" ||
       Array.isArray(resolved) ||
       Object.keys(resolved).some(
-        key => !["bandwidth", "extent", "splitDomain"].includes(key)
+        key => !["bandwidth", "bandwidths", "extent", "splitDomain"].includes(key)
       ) ||
-      !Number.isFinite(resolved.bandwidth) ||
-      resolved.bandwidth <= 0 ||
+      !hasValidResolvedBandwidthState(resolved, transform) ||
       !Array.isArray(resolved.extent) ||
       resolved.extent.length !== 2 ||
       !resolved.extent.every(Number.isFinite) ||
@@ -319,7 +427,7 @@ export function validateDensityTransform(transform) {
       })())
     ) {
       throw new TypeError(
-        "Density resolved provenance requires a positive bandwidth, ascending finite extent, and optional two-value split domain."
+        "Density resolved provenance requires one positive bandwidth or profile bandwidth list, an ascending finite extent, and an optional two-value split domain."
       );
     }
   }
@@ -363,22 +471,26 @@ export function estimateDensityBandwidth(values) {
   return bandwidth;
 }
 
-function resolveBandwidth(value, sourceValues) {
+function resolveBandwidth(value, sourceValues, weightSummary, field) {
   if (value === undefined || value === "auto") {
-    return estimateDensityBandwidth(sourceValues);
+    return weightSummary === undefined
+      ? estimateDensityBandwidth(sourceValues)
+      : weightedBandwidth(weightSummary, field);
   }
   return validateDensityBandwidth(value);
 }
 
-function resolveExtent(value, sourceValues) {
+function resolveExtent(value, sourceValues, weightSummary, field) {
   if (value === undefined || value === "auto") {
-    let lower = Infinity;
-    let upper = -Infinity;
-    for (const sourceValue of sourceValues) {
-      lower = Math.min(lower, sourceValue);
-      upper = Math.max(upper, sourceValue);
-    }
-    const extent = [lower, upper];
+    const extent = weightSummary === undefined
+      ? sourceValues.reduce(
+          ([lower, upper], sourceValue) => [
+            Math.min(lower, sourceValue),
+            Math.max(upper, sourceValue)
+          ],
+          [Infinity, -Infinity]
+        )
+      : weightedEntriesExtent(weightSummary, field);
     if (extent[0] === extent[1]) {
       throw new Error("Density observed extent requires varying finite values.");
     }
@@ -407,6 +519,17 @@ function estimateAt(sample, values, bandwidth, kernel, normalization) {
   return requireFiniteResult(stable, "Density estimate");
 }
 
+function estimateWeightedAt(sample, summary, field, bandwidth, kernel, normalization) {
+  return weightedKernelEstimate(
+    summary,
+    field,
+    sample,
+    bandwidth,
+    KERNEL_FUNCTIONS[kernel],
+    normalization
+  );
+}
+
 export function deriveKernelDensity(values, {
   field,
   groupBy,
@@ -416,7 +539,8 @@ export function deriveKernelDensity(values, {
   kernel = "gaussian",
   normalization = "unit",
   as,
-  placement
+  placement,
+  weight
 } = {}) {
   if (!Array.isArray(values)) {
     throw new TypeError("Density values must be an array.");
@@ -437,29 +561,66 @@ export function deriveKernelDensity(values, {
   )];
   const resolvedKernel = validateDensityKernel(kernel);
   const resolvedNormalization = validateDensityNormalization(normalization);
-  const validRows = values.filter(row =>
-    row !== null &&
-    typeof row === "object" &&
-    Number.isFinite(row[sourceField]) &&
-    (groupField === undefined || isNominalValue(row[groupField])) &&
-    (placement?.split === undefined || isNominalValue(row[placement.split.field]))
-  );
+  const statisticalWeights = weight === undefined
+    ? undefined
+    : readStatisticalWeights(values, weight, "Density");
+  if (statisticalWeights !== undefined) {
+    validateWeightedNumericFields(
+      statisticalWeights.entries,
+      [sourceField],
+      "Density"
+    );
+  }
+  const validEntries = statisticalWeights === undefined
+    ? undefined
+    : statisticalWeights.entries.filter(entry =>
+        (groupField === undefined || isNominalValue(entry.row[groupField])) &&
+        (placement?.split === undefined ||
+          isNominalValue(entry.row[placement.split.field]))
+      );
+  const validRows = statisticalWeights === undefined
+    ? values.filter(row =>
+        row !== null &&
+        typeof row === "object" &&
+        Number.isFinite(row[sourceField]) &&
+        (groupField === undefined || isNominalValue(row[groupField])) &&
+        (placement?.split === undefined || isNominalValue(row[placement.split.field]))
+      )
+    : validEntries.map(entry => entry.row);
   if (validRows.length === 0) {
     throw new Error("Density requires at least one valid field/group row.");
   }
-  validateWorkLimit(validRows.length * steps, "Density computation");
-  const sourceValues = validRows.map(row => row[sourceField]);
-  const resolvedBandwidth = resolveBandwidth(bandwidth, sourceValues);
-  const resolvedExtent = resolveExtent(extent, sourceValues);
+  const globalWeightSummary = statisticalWeights === undefined
+    ? undefined
+    : summarizeStatisticalWeights(
+        validEntries,
+        statisticalWeights.definition.kind,
+        "Density data"
+      );
+  validateWorkLimit(
+    (globalWeightSummary?.positive.length ?? validRows.length) * steps,
+    "Density computation"
+  );
+  const sourceValues = globalWeightSummary === undefined
+    ? validRows.map(row => row[sourceField])
+    : globalWeightSummary.positive.map(entry => entry.row[sourceField]);
+  const resolvedExtent = resolveExtent(
+    extent,
+    sourceValues,
+    globalWeightSummary,
+    sourceField
+  );
   const groupedValues = new Map();
-  for (const row of validRows) {
+  const groupedSource = statisticalWeights === undefined ? validRows : validEntries;
+  for (const source of groupedSource) {
+    const row = statisticalWeights === undefined ? source : source.row;
     const group = groupField === undefined ? undefined : row[groupField];
     const split = placement?.split === undefined
       ? undefined
       : row[placement.split.field];
     const bySplit = groupedValues.get(group) ?? new Map();
     const groupValues = bySplit.get(split) ?? [];
-    groupValues.push(row[sourceField]);
+    groupValues.push(statisticalWeights === undefined ? row[sourceField] : source);
     bySplit.set(split, groupValues);
     groupedValues.set(group, bySplit);
   }
@@ -492,6 +653,16 @@ export function deriveKernelDensity(values, {
     outputGroups * steps,
     "Density generated row count"
   );
+  const profileBandwidths = statisticalWeights !== undefined &&
+    bandwidth === "auto" && outputGroups > 1;
+  const resolvedBandwidth = profileBandwidths
+    ? undefined
+    : resolveBandwidth(
+        bandwidth,
+        sourceValues,
+        globalWeightSummary,
+        sourceField
+      );
   const extentSpan = resolvedExtent[1] - resolvedExtent[0];
   const sampleStep = extentSpan / (steps - 1);
   const samples = Array.from(
@@ -516,10 +687,30 @@ export function deriveKernelDensity(values, {
     );
   }
   const rows = [];
+  const resolvedBandwidths = [];
   for (const group of groups) {
     for (const split of splits) {
       const groupValues = groupedValues.get(group).get(split) ?? [];
       if (groupValues.length === 0) continue;
+      const groupWeightSummary = statisticalWeights === undefined
+        ? undefined
+        : summarizeStatisticalWeights(
+            groupValues,
+            statisticalWeights.definition.kind,
+            "Density group"
+          );
+      const groupBandwidth = resolvedBandwidth ?? weightedBandwidth(
+        groupWeightSummary,
+        sourceField,
+        "Density group auto bandwidth"
+      );
+      if (profileBandwidths) {
+        resolvedBandwidths.push({
+          ...(groupField === undefined ? {} : { group }),
+          ...(placement?.split === undefined ? {} : { split }),
+          bandwidth: groupBandwidth
+        });
+      }
       for (const sample of samples) {
         rows.push({
           ...(groupField === undefined
@@ -531,13 +722,22 @@ export function deriveKernelDensity(values, {
             ? {}
             : { [placement.split.field]: split }),
           [outputFields[0]]: sample,
-          [outputFields[1]]: estimateAt(
-            sample,
-            groupValues,
-            resolvedBandwidth,
-            resolvedKernel,
-            resolvedNormalization
-          )
+          [outputFields[1]]: groupWeightSummary === undefined
+            ? estimateAt(
+                sample,
+                groupValues,
+                groupBandwidth,
+                resolvedKernel,
+                resolvedNormalization
+              )
+            : estimateWeightedAt(
+                sample,
+                groupWeightSummary,
+                sourceField,
+                groupBandwidth,
+                resolvedKernel,
+                resolvedNormalization
+              )
         });
       }
     }
@@ -551,7 +751,9 @@ export function deriveKernelDensity(values, {
     },
     groups,
     ...(splitDomain === undefined ? {} : { splitDomain }),
-    bandwidth: resolvedBandwidth,
+    ...(resolvedBandwidth === undefined
+      ? { bandwidths: resolvedBandwidths }
+      : { bandwidth: resolvedBandwidth }),
     kernel: resolvedKernel,
     normalization: resolvedNormalization,
     extent: resolvedExtent,

package/src/grammar/displayLabels.js

@@ -0,0 +1,57 @@
+import { isPlainObject } from "../core/immutable.js";
+
+const ENTRY_KEYS = Object.freeze(["value", "label"]);
+
+export function sameDisplayLabelValue(left, right) {
+  return left === right;
+}
+
+function isDisplayLabelValue(value) {
+  return value === null || typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+export function normalizeDisplayLabelMap(value, label = "labelMap") {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} must be an array.`);
+  }
+  const normalized = [];
+  for (const [index, entry] of value.entries()) {
+    if (!isPlainObject(entry)) {
+      throw new TypeError(`${label}[${index}] must be a plain object.`);
+    }
+    const keys = Reflect.ownKeys(entry);
+    if (keys.length !== ENTRY_KEYS.length ||
+        ENTRY_KEYS.some(key => !Object.hasOwn(entry, key))) {
+      throw new Error(`${label}[${index}] must contain exactly value and label.`);
+    }
+    if (!isDisplayLabelValue(entry.value)) {
+      throw new TypeError(
+        `${label}[${index}].value must be a string, boolean, null, or finite number.`
+      );
+    }
+    if (typeof entry.label !== "string") {
+      throw new TypeError(`${label}[${index}].label must be a string.`);
+    }
+    if (normalized.some(previous =>
+      sameDisplayLabelValue(previous.value, entry.value))) {
+      throw new Error(`${label} contains a duplicate typed value.`);
+    }
+    normalized.push(Object.freeze({ value: entry.value, label: entry.label }));
+  }
+  return Object.freeze(normalized);
+}
+
+export function resolveDisplayLabel(value, map, fallback) {
+  if (map !== undefined) {
+    for (const entry of map) {
+      if (sameDisplayLabelValue(entry.value, value)) return entry.label;
+    }
+  }
+  const resolved = fallback(value);
+  if (typeof resolved !== "string") {
+    throw new TypeError("Display label fallback must return a string.");
+  }
+  return resolved;
+}

package/src/grammar/ecdf.js

@@ -0,0 +1,198 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { stableDecimal } from "./numeric.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "field", "groupBy", "weight", "missing", "as", "resolved"
+]);
+const OUTPUT_KEYS = Object.freeze(["value", "cumulative", "probability"]);
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+
+function normalizeGroupBy(groupBy) {
+  const fields = groupBy === undefined
+    ? []
+    : Array.isArray(groupBy) ? [...groupBy] : [groupBy];
+  fields.forEach(field => nonEmptyString(field, "ECDF groupBy field"));
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("ECDF groupBy fields must be distinct.");
+  }
+  return fields;
+}
+
+function validateOutputs(as, occupied) {
+  if (!isPlainObject(as)) throw new TypeError("ECDF 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("ECDF as requires exactly value, cumulative, and probability.");
+  }
+  const values = OUTPUT_KEYS.map(key => as[key]);
+  values.forEach((field, index) => nonEmptyString(field, `ECDF as.${OUTPUT_KEYS[index]}`));
+  if (new Set(values).size !== values.length) {
+    throw new Error("ECDF output fields must be distinct.");
+  }
+  if (values.some(field => occupied.has(field))) {
+    throw new Error("ECDF output fields must not collide with input or grouping fields.");
+  }
+}
+
+function validateResolved(resolved, groupBy) {
+  if (resolved === undefined) return;
+  if (!isPlainObject(resolved) || !Array.isArray(resolved.groups)) {
+    throw new TypeError("ECDF resolved provenance must contain a groups array.");
+  }
+  for (const group of resolved.groups) {
+    if (!isPlainObject(group) || !isPlainObject(group.keys) ||
+        !Number.isFinite(group.denominator) || group.denominator <= 0 ||
+        !Number.isInteger(group.validCount) || group.validCount <= 0 ||
+        Object.keys(group.keys).length !== groupBy.length ||
+        !groupBy.every(field => Object.hasOwn(group.keys, field))) {
+      throw new TypeError("ECDF resolved group provenance is invalid.");
+    }
+  }
+}
+
+export function validateECDFTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("ECDF transform must be a plain object.");
+  }
+  const unknown = Object.keys(transform).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ECDF transform property "${unknown}".`);
+  }
+  if (transform.type !== "ecdf") {
+    throw new Error(`Unsupported ECDF transform "${transform.type}".`);
+  }
+  nonEmptyString(transform.field, "ECDF field");
+  const groupBy = normalizeGroupBy(transform.groupBy);
+  if (groupBy.includes(transform.field)) {
+    throw new Error("ECDF field must not also be a grouping field.");
+  }
+  if (transform.weight !== undefined) {
+    nonEmptyString(transform.weight, "ECDF weight field");
+    if (transform.weight === transform.field || groupBy.includes(transform.weight)) {
+      throw new Error("ECDF weight field must be distinct from value and grouping fields.");
+    }
+  }
+  if (!["drop", "error"].includes(transform.missing)) {
+    throw new Error('ECDF missing must be "drop" or "error".');
+  }
+  validateOutputs(
+    transform.as,
+    new Set([transform.field, transform.weight, ...groupBy].filter(Boolean))
+  );
+  validateResolved(transform.resolved, groupBy);
+}
+
+export function normalizeECDFTransform({ field, groupBy, weight, missing = "drop", as }) {
+  const transform = {
+    type: "ecdf",
+    field,
+    groupBy: normalizeGroupBy(groupBy),
+    ...(weight === undefined ? {} : { weight }),
+    missing,
+    as
+  };
+  validateECDFTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function groupValue(value) {
+  return typeof value === "string" || typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+function rejectOrDrop(transform, index, reason) {
+  if (transform.missing === "error") {
+    throw new TypeError(`ECDF row ${index} ${reason}.`);
+  }
+  return false;
+}
+
+export function deriveECDF(rows, transform) {
+  if (!Array.isArray(rows)) throw new TypeError("ECDF rows must be an array.");
+  validateECDFTransform(transform);
+  const groups = new Map();
+
+  rows.forEach((row, index) => {
+    if (!isPlainObject(row)) {
+      rejectOrDrop(transform, index, "must be a plain object");
+      return;
+    }
+    const value = row[transform.field];
+    if (!Number.isFinite(value)) {
+      rejectOrDrop(transform, index, `has an invalid value in "${transform.field}"`);
+      return;
+    }
+    const keys = transform.groupBy.map(field => row[field]);
+    if (!keys.every(groupValue)) {
+      rejectOrDrop(transform, index, "has an invalid grouping value");
+      return;
+    }
+    const weight = transform.weight === undefined ? 1 : row[transform.weight];
+    if (!Number.isFinite(weight)) {
+      rejectOrDrop(transform, index, `has an invalid weight in "${transform.weight}"`);
+      return;
+    }
+    if (weight < 0) {
+      throw new RangeError(`ECDF row ${index} has a negative weight.`);
+    }
+    const key = JSON.stringify(keys);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        keys: Object.fromEntries(transform.groupBy.map((field, offset) => [field, keys[offset]])),
+        values: new Map(),
+        denominator: 0,
+        validCount: 0
+      });
+    }
+    const group = groups.get(key);
+    if (weight === 0) return;
+    group.values.set(value, (group.values.get(value) ?? 0) + weight);
+    group.denominator += weight;
+    group.validCount += 1;
+  });
+
+  if (groups.size === 0) {
+    throw new RangeError("ECDF denominator must be greater than zero.");
+  }
+
+  const values = [];
+  const provenance = [];
+  for (const group of groups.values()) {
+    if (!(group.denominator > 0) || !Number.isFinite(group.denominator)) {
+      throw new RangeError("ECDF denominator must be finite and greater than zero.");
+    }
+    const support = [...group.values.keys()].sort((left, right) => left - right);
+    values.push({
+      ...group.keys,
+      [transform.as.value]: support[0],
+      [transform.as.cumulative]: 0,
+      [transform.as.probability]: 0
+    });
+    let cumulative = 0;
+    for (const value of support) {
+      cumulative += group.values.get(value);
+      values.push({
+        ...group.keys,
+        [transform.as.value]: value,
+        [transform.as.cumulative]: stableDecimal(cumulative),
+        [transform.as.probability]: stableDecimal(cumulative / group.denominator)
+      });
+    }
+    provenance.push({
+      keys: group.keys,
+      denominator: stableDecimal(group.denominator),
+      validCount: group.validCount
+    });
+  }
+  return cloneAndFreeze({ values, resolved: { groups: provenance } });
+}
+
+export function resolveECDFTransform(result, transform) {
+  return cloneAndFreeze([{ ...transform, resolved: result.resolved }]);
+}