ggaction 0.0.11 → 0.0.13

package/src/core/compositionState.js

@@ -11,24 +11,23 @@ function validateFacetSpec(compositionSpec) {
   }
   if (
     !Number.isInteger(compositionSpec.columns) ||
-    compositionSpec.columns <= 0 ||
-    compositionSpec.columns > compositionSpec.children.length
+    compositionSpec.columns <= 0
   ) {
     throw new RangeError(
-      "Facet compositionSpec.columns must be a positive integer no larger than its children."
+      "Facet compositionSpec.columns must be a positive integer."
     );
   }
   if (!isPlainObject(compositionSpec.facet)) {
     throw new TypeError("Facet compositionSpec.facet must be a plain object.");
   }
-  const facetKeys = ["data", "field", "values", "scales", "guides"];
+  const facetKeys = ["data", "field", "values", "grid", "repeat", "scales", "guides"];
   const unknownFacet = Object.keys(compositionSpec.facet).find(
     key => !facetKeys.includes(key)
   );
   if (unknownFacet !== undefined) {
     throw new Error(`Unknown compositionSpec.facet property "${unknownFacet}".`);
   }
-  for (const property of ["data", "field"]) {
+  for (const property of ["data"]) {
     if (
       typeof compositionSpec.facet[property] !== "string" ||
       compositionSpec.facet[property].length === 0
@@ -36,6 +35,129 @@ function validateFacetSpec(compositionSpec) {
       throw new TypeError(`compositionSpec.facet.${property} must be a non-empty string.`);
     }
   }
+  const grid = compositionSpec.facet.grid;
+  const repeat = compositionSpec.facet.repeat;
+  if (grid !== undefined && repeat !== undefined) {
+    throw new Error("Facet compositionSpec cannot combine grid and repeat recipes.");
+  }
+  if (grid === undefined && repeat === undefined) {
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Facet compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (
+      typeof compositionSpec.facet.field !== "string" ||
+      compositionSpec.facet.field.length === 0
+    ) {
+      throw new TypeError("compositionSpec.facet.field must be a non-empty string.");
+    }
+  } else if (grid !== undefined) {
+    if (compositionSpec.columns !== grid.columns?.values?.length) {
+      throw new RangeError(
+        "Grid facet compositionSpec.columns must match its column domain."
+      );
+    }
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Grid facet compositionSpec does not use facet.field.");
+    }
+    if (!isPlainObject(grid)) {
+      throw new TypeError("compositionSpec.facet.grid must be a plain object.");
+    }
+    const gridKeys = ["rows", "columns", "combinations", "cells"];
+    const unknownGrid = Object.keys(grid).find(key => !gridKeys.includes(key));
+    if (unknownGrid !== undefined) {
+      throw new Error(`Unknown compositionSpec.facet.grid property "${unknownGrid}".`);
+    }
+    for (const role of ["rows", "columns"]) {
+      const value = grid[role];
+      if (!isPlainObject(value) || Object.keys(value).some(
+        key => !["field", "values"].includes(key)
+      )) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role} requires field and values.`
+        );
+      }
+      if (typeof value.field !== "string" || value.field.length === 0) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.field must be a non-empty string.`
+        );
+      }
+      if (
+        !Array.isArray(value.values) || value.values.length === 0 ||
+        value.values.some(item => !(
+          typeof item === "string" || typeof item === "boolean" ||
+          (typeof item === "number" && Number.isFinite(item))
+        )) || new Set(value.values).size !== value.values.length
+      ) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.values must contain unique scalars.`
+        );
+      }
+    }
+    if (grid.rows.field === grid.columns.field) {
+      throw new Error("compositionSpec.facet.grid fields must be different.");
+    }
+    if (!["observed", "full"].includes(grid.combinations)) {
+      throw new Error(
+        'compositionSpec.facet.grid.combinations must be "observed" or "full".'
+      );
+    }
+    if (!Array.isArray(grid.cells) || grid.cells.length !== compositionSpec.children.length) {
+      throw new TypeError(
+        "compositionSpec.facet.grid.cells must contain one descriptor per child."
+      );
+    }
+    const cellKeys = ["id", "row", "column", "rowValue", "columnValue", "empty"];
+    const coordinates = new Set();
+    for (const cell of grid.cells) {
+      if (!isPlainObject(cell) || Object.keys(cell).some(key => !cellKeys.includes(key))) {
+        throw new TypeError("compositionSpec.facet.grid cells must be canonical objects.");
+      }
+      if (!compositionSpec.children.includes(cell.id)) {
+        throw new Error(`Unknown grid facet child "${cell.id}".`);
+      }
+      if (!Number.isInteger(cell.row) || cell.row < 0 || cell.row >= grid.rows.values.length ||
+          !Number.isInteger(cell.column) || cell.column < 0 || cell.column >= grid.columns.values.length) {
+        throw new RangeError("Grid facet cell coordinates must be inside their domains.");
+      }
+      if (cell.rowValue !== grid.rows.values[cell.row] ||
+          cell.columnValue !== grid.columns.values[cell.column]) {
+        throw new Error("Grid facet cell values must match their row and column coordinates.");
+      }
+      if (typeof cell.empty !== "boolean") {
+        throw new TypeError("Grid facet cell empty must be a boolean.");
+      }
+      const key = `${cell.row}:${cell.column}`;
+      if (coordinates.has(key)) {
+        throw new Error("Grid facet cells must occupy unique coordinates.");
+      }
+      coordinates.add(key);
+    }
+  } else {
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Repeat compositionSpec does not use facet.field.");
+    }
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Repeat compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (!isPlainObject(repeat) || Object.keys(repeat).some(
+      key => !["target", "channel", "fields"].includes(key)
+    )) {
+      throw new TypeError(
+        "compositionSpec.facet.repeat requires target, channel, and fields."
+      );
+    }
+    if (typeof repeat.target !== "string" || repeat.target.length === 0 ||
+        !["x", "y"].includes(repeat.channel) ||
+        !Array.isArray(repeat.fields) || repeat.fields.length === 0 ||
+        repeat.fields.some(field => typeof field !== "string" || field.length === 0) ||
+        new Set(repeat.fields).size !== repeat.fields.length) {
+      throw new TypeError("compositionSpec.facet.repeat is not canonical.");
+    }
+  }
   const values = compositionSpec.facet.values;
   if (
     !Array.isArray(values) ||
@@ -45,12 +167,18 @@ function validateFacetSpec(compositionSpec) {
       typeof value === "boolean" ||
       (typeof value === "number" && Number.isFinite(value))
     )) ||
-    new Set(values).size !== values.length
+    (grid === undefined && new Set(values).size !== values.length)
   ) {
     throw new TypeError(
       "compositionSpec.facet.values must contain one unique scalar per child."
     );
   }
+  if (repeat !== undefined && (
+    values.length !== repeat.fields.length ||
+    values.some((value, index) => value !== repeat.fields[index])
+  )) {
+    throw new Error("compositionSpec.facet.values must match repeat fields.");
+  }
   const scales = compositionSpec.facet.scales;
   if (
     !isPlainObject(scales) ||
@@ -80,13 +208,13 @@ function validateFacetSpec(compositionSpec) {
 function validateCompositionChildren(compositionSpec, childIds, facet) {
   if (
     !Array.isArray(compositionSpec.children) ||
-    compositionSpec.children.length < (facet ? 1 : 2) ||
+    compositionSpec.children.length < 1 ||
     !compositionSpec.children.every(id => typeof id === "string" && id.length > 0)
   ) {
     throw new TypeError(
       facet
         ? "Facet compositionSpec.children requires at least one child ID."
-        : "compositionSpec.children requires at least two child IDs."
+        : "compositionSpec.children requires at least one child ID."
     );
   }
   if (new Set(compositionSpec.children).size !== compositionSpec.children.length) {

package/src/core/vocabulary.js

@@ -86,14 +86,14 @@ export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
     role: "offset",
     scaleChannel: "xOffset",
     coordinate: Object.freeze({ id: "main", type: "cartesian" }),
-    markTypes: Object.freeze(["bar"])
+    markTypes: Object.freeze(["bar", "point", "rule"])
   }),
   yOffset: Object.freeze({
     family: "cartesian",
     role: "offset",
     scaleChannel: "yOffset",
     coordinate: Object.freeze({ id: "main", type: "cartesian" }),
-    markTypes: Object.freeze(["bar"])
+    markTypes: Object.freeze(["bar", "point", "rule"])
   }),
   theta: Object.freeze({
     family: "polar",

package/src/grammar/aggregate.js

@@ -7,6 +7,10 @@ import {
   stableFiniteMean,
   stableFiniteSum
 } from "./numeric.js";
+import {
+  confidenceCriticalValue,
+  normalizeConfidenceInterval
+} from "./statistics/confidenceInterval.js";
 
 export const SCALAR_AGGREGATE_OPERATIONS = Object.freeze([
   "count", "sum", "mean", "median", "min", "max",
@@ -17,7 +21,9 @@ export const SCALAR_AGGREGATE_OPERATIONS = Object.freeze([
 
 const SCALAR_OPERATIONS = new Set(SCALAR_AGGREGATE_OPERATIONS);
 const NOMINAL_OPERATIONS = ["count", "distinct", "valid", "missing"];
-const PARAMETERIZED_OPERATIONS = ["quantile", "first", "last"];
+const PARAMETERIZED_OPERATIONS = [
+  "quantile", "first", "last", "ciLower", "ciUpper"
+];
 
 function nonEmptyString(value, label) {
   if (typeof value !== "string" || value.length === 0) {
@@ -83,6 +89,21 @@ export function validateAggregate(value) {
       order: value.order ?? "ascending"
     };
   }
+  if (value.op === "ciLower" || value.op === "ciUpper") {
+    const unknown = Object.keys(value).find(
+      key => !["op", "method", "level"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(`Unknown confidence aggregate property "${unknown}".`);
+    }
+    return {
+      op: value.op,
+      ...normalizeConfidenceInterval(value, {
+        defaultMethod: "normal",
+        label: "Aggregate confidence interval"
+      })
+    };
+  }
   throw new Error(`Unsupported aggregate "${value.op}".`);
 }
 
@@ -194,39 +215,44 @@ export function aggregateScalarValues(values, operation) {
   if (!Array.isArray(values)) {
     throw new TypeError("Aggregate values must be an array.");
   }
-  validateAggregate(operation);
-  if (!isScalarAggregate(operation)) {
+  const aggregate = validateAggregate(operation);
+  const scalarOperation = isScalarAggregate(aggregate)
+    ? aggregate
+    : ["ciLower", "ciUpper"].includes(aggregate.op)
+      ? aggregate.op
+      : undefined;
+  if (scalarOperation === undefined) {
     throw new Error("Scalar aggregate calculation requires a scalar operation.");
   }
 
-  if (operation === "count") return values.length;
+  if (scalarOperation === "count") return values.length;
   const valid = values.filter(value => !isMissing(value));
-  if (operation === "valid") return valid.length;
-  if (operation === "missing") return values.length - valid.length;
-  if (operation === "distinct") return new Set(valid).size;
+  if (scalarOperation === "valid") return valid.length;
+  if (scalarOperation === "missing") return values.length - valid.length;
+  if (scalarOperation === "distinct") return new Set(valid).size;
 
   const finite = finiteValues(values);
   if (finite.length === 0) return undefined;
-  if (operation === "sum") {
+  if (scalarOperation === "sum") {
     return stableFiniteSum(finite, "Aggregate sum");
   }
-  if (operation === "min") return numericExtent(finite)[0];
-  if (operation === "max") return numericExtent(finite)[1];
-  if (operation === "median") return quantile(finite, 0.5);
-  if (operation === "q1") return quantile(finite, 0.25);
-  if (operation === "q3") return quantile(finite, 0.75);
+  if (scalarOperation === "min") return numericExtent(finite)[0];
+  if (scalarOperation === "max") return numericExtent(finite)[1];
+  if (scalarOperation === "median") return quantile(finite, 0.5);
+  if (scalarOperation === "q1") return quantile(finite, 0.25);
+  if (scalarOperation === "q3") return quantile(finite, 0.75);
 
   const mean = stableFiniteMean(finite, "Aggregate mean");
-  if (operation === "mean") return mean;
-  if (["variance", "varianceP", "stdev", "stdevP"].includes(operation)) {
-    const population = operation.endsWith("P");
+  if (scalarOperation === "mean") return mean;
+  if (["variance", "varianceP", "stdev", "stdevP"].includes(scalarOperation)) {
+    const population = scalarOperation.endsWith("P");
     if (!population && finite.length < 2) return undefined;
     const kind = population ? "population" : "sample";
     const deviation = stableFiniteDeviation(finite, {
       sample: !population,
       label: `Aggregate ${kind} deviation`
     });
-    if (operation.startsWith("stdev")) return deviation.deviation;
+    if (scalarOperation.startsWith("stdev")) return deviation.deviation;
     return deviation.squared === undefined
       ? requireFiniteResult(
           deviation.deviation ** 2,
@@ -240,14 +266,25 @@ export function aggregateScalarValues(values, operation) {
     divisor: Math.sqrt(finite.length),
     label: "Aggregate standard error"
   }).deviation;
-  if (operation === "stderr") return stderr;
-  if (operation === "ciLower") {
-    return requireFiniteResult(mean - 1.96 * stderr, "Aggregate lower CI");
+  if (scalarOperation === "stderr") return stderr;
+  const confidence = isScalarAggregate(aggregate)
+    ? normalizeConfidenceInterval({}, {
+        defaultMethod: "normal",
+        label: "Aggregate confidence interval"
+      })
+    : aggregate;
+  const critical = confidenceCriticalValue({
+    method: confidence.method,
+    level: confidence.level,
+    degreesOfFreedom: finite.length - 1
+  });
+  if (scalarOperation === "ciLower") {
+    return requireFiniteResult(mean - critical * stderr, "Aggregate lower CI");
   }
-  if (operation === "ciUpper") {
-    return requireFiniteResult(mean + 1.96 * stderr, "Aggregate upper CI");
+  if (scalarOperation === "ciUpper") {
+    return requireFiniteResult(mean + critical * stderr, "Aggregate upper CI");
   }
-  throw new Error(`Unsupported scalar aggregate "${operation}".`);
+  throw new Error(`Unsupported scalar aggregate "${scalarOperation}".`);
 }
 
 export function aggregateRows(rows, field, operation) {
@@ -265,6 +302,9 @@ export function aggregateRows(rows, field, operation) {
       ? undefined
       : quantile(values, aggregate.probability);
   }
+  if (aggregate.op === "ciLower" || aggregate.op === "ciUpper") {
+    return aggregateScalarValues(rows.map(row => row[field]), aggregate);
+  }
   return aggregateOrderedRows(rows, field, aggregate);
 }
 
@@ -275,5 +315,8 @@ export function formatAggregateTitle(operation, field) {
   if (aggregate.op === "quantile") {
     return `quantile(${field}, ${aggregate.probability})`;
   }
+  if (aggregate.op === "ciLower" || aggregate.op === "ciUpper") {
+    return `${aggregate.op}(${field}, ${aggregate.method}, ${aggregate.level})`;
+  }
   return `${aggregate.op}(${field}, ${aggregate.orderBy} ${aggregate.order})`;
 }