ggaction 0.0.11 → 0.0.13

package/src/grammar/markLabels.js

@@ -0,0 +1,93 @@
+import { aggregateRows } from "./aggregate.js";
+import { BAR_GRAINS, resolveBarChannels, resolveBarGrain } from "./bars/policy.js";
+import { stableFiniteSum } from "./numeric.js";
+
+const CONTENTS = new Set(["category", "value", "share"]);
+const NORMALIZATIONS = new Set(["source", "category"]);
+
+export function validateMarkLabelContent(content) {
+  if (!CONTENTS.has(content)) throw new Error(`Unsupported text content "${content}".`);
+  return content;
+}
+
+export function validateMarkLabelNormalization(normalizeBy) {
+  if (!NORMALIZATIONS.has(normalizeBy)) throw new Error(`Unsupported text normalizeBy "${normalizeBy}".`);
+  return normalizeBy;
+}
+
+export function normalizeMarkLabelContent(source, { content, normalizeBy }) {
+  validateMarkLabelContent(content);
+  if (!["bar", "arc"].includes(source?.mark?.type)) {
+    throw new Error("Semantic text content requires a Bar or Arc source; use field or value for other marks.");
+  }
+  if (content !== "share" && normalizeBy !== undefined) {
+    throw new Error("Text normalizeBy is only supported with share content.");
+  }
+  const normalization = content === "share" ? normalizeBy ?? "source" : undefined;
+  if (normalization !== undefined) validateMarkLabelNormalization(normalization);
+  if (normalization === "category" && source.mark.type !== "bar") {
+    throw new Error("Category share normalization requires a Bar source.");
+  }
+  if (source.mark.type === "bar") {
+    const grain = resolveBarGrain(source);
+    if (grain === BAR_GRAINS.ranged) {
+      throw new Error("Ranged Bar text requires an explicit field or value.");
+    }
+    if (content === "category" && grain === BAR_GRAINS.histogram) {
+      throw new Error("Histogram categories are intervals; use an explicit text field or value.");
+    }
+  } else if (content === "category" && source.encoding?.theta?.fieldType === "quantitative") {
+    throw new Error("Category text requires categorical Arc theta.");
+  }
+  return { content, ...(normalization === undefined ? {} : { normalizeBy: normalization }) };
+}
+
+function itemValue(source, item) {
+  if (source.mark.type === "bar") {
+    if (resolveBarGrain(source) === BAR_GRAINS.histogram) return item.members.length;
+    const measure = source.encoding[resolveBarChannels(source).measure];
+    return measure.aggregate === "count" ? item.members.length
+      : aggregateRows(item.members, measure.field, measure.aggregate);
+  }
+  if (source.encoding?.radius !== undefined) return item.channels.radius;
+  const theta = source.encoding.theta;
+  if (theta.fieldType === "quantitative") return item.channels.theta;
+  return theta.aggregate === "count" ? item.members.length
+    : aggregateRows(item.members, theta.weight, "sum");
+}
+
+function categoryValue(source, item) {
+  return item.channels[source.mark.type === "arc" ? "theta" : resolveBarChannels(source).category];
+}
+
+function categoryKey(source, item) {
+  return JSON.stringify(resolveBarGrain(source) === BAR_GRAINS.histogram
+    ? [item.channels.x, item.channels.x2]
+    : [categoryValue(source, item)]);
+}
+
+export function resolveMarkLabelValues(source, items, options) {
+  const config = normalizeMarkLabelContent(source, options);
+  if (config.content === "category") return items.map(item => categoryValue(source, item));
+  const values = items.map(item => itemValue(source, item));
+  if (config.content === "value" || items.length === 0) return values;
+  if (values.some(value => !Number.isFinite(value) || value < 0)) {
+    throw new Error("Share labels require finite non-negative source values.");
+  }
+  const groups = new Map();
+  items.forEach((item, index) => {
+    const key = config.normalizeBy === "source" ? "source" : categoryKey(source, item);
+    const group = groups.get(key) ?? [];
+    group.push(index);
+    groups.set(key, group);
+  });
+  const shares = [];
+  for (const indices of groups.values()) {
+    const maximum = indices.reduce((max, index) => Math.max(max, values[index]), 0);
+    if (maximum === 0) throw new Error("Share label denominator must be positive.");
+    // Ratios remain defined even when the unscaled sum would overflow.
+    const total = stableFiniteSum(indices.map(index => values[index] / maximum), "Share label denominator");
+    for (const index of indices) shares[index] = (values[index] / maximum) / total;
+  }
+  return shares;
+}

package/src/grammar/parallelAxisTitles.js

@@ -0,0 +1,16 @@
+import { validateNonEmptyString, validateOptionObject } from "../core/validation.js";
+
+export function validateParallelAxisTitles(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError("Parallel axis titles must be a non-empty field/text array.");
+  }
+  const fields = new Set();
+  for (const title of value) {
+    validateOptionObject(title, ["field", "text"], "Parallel axis title");
+    validateNonEmptyString(title.field, "Parallel axis title field");
+    validateNonEmptyString(title.text, "Parallel axis title text");
+    if (fields.has(title.field)) throw new Error("Parallel axis titles require unique fields.");
+    fields.add(title.field);
+  }
+  return value;
+}

package/src/grammar/pathSeries.js

@@ -0,0 +1,91 @@
+import { validateNonEmptyString } from "../core/validation.js";
+import { readNominalField, readQuantitativeField } from "./scales/fields.js";
+
+export function normalizeGroupFields(value) {
+  const fields = Array.isArray(value) ? [...value] : [value];
+  for (const field of fields) validateNonEmptyString(field, "Path group field");
+  if (fields.length === 0 || new Set(fields).size !== fields.length) {
+    throw new Error("Path group fields must be non-empty and unique.");
+  }
+  return fields;
+}
+
+export function pathGroupFields(layer) {
+  const group = layer.encoding?.group;
+  if (group !== undefined) {
+    if (group.fieldType !== "nominal") {
+      throw new Error(`Path group on mark "${layer.id}" must be nominal.`);
+    }
+    if (Object.hasOwn(group, "field") && Object.hasOwn(group, "fields")) {
+      throw new Error("Path group requires exactly one of field or fields.");
+    }
+    return normalizeGroupFields(group.fields ?? group.field);
+  }
+  if (layer.mark?.type !== "line") return [];
+  const color = layer.encoding?.color?.field;
+  const dash = layer.encoding?.strokeDash?.field;
+  if (color !== undefined && dash !== undefined && color !== dash) {
+    throw new Error("Line color field must match strokeDash field unless encodeGroup defines the series.");
+  }
+  return color === undefined && dash === undefined ? [] : [color ?? dash];
+}
+
+export function readPathSeriesFields(rows, layer) {
+  const fields = pathGroupFields(layer);
+  for (const field of fields) readNominalField(rows, field);
+  return fields;
+}
+
+function seriesValueIndex(rows, fields, field, channel) {
+  const quantitative = channel === "strokeWidth" || channel === "opacity";
+  const values = quantitative
+    ? readQuantitativeField(rows, field)
+    : readNominalField(rows, field);
+  const result = new Map();
+  rows.forEach((row, index) => {
+    const key = JSON.stringify(fields.map(field => row[field]));
+    const value = values[index];
+    if (channel === "strokeWidth" && value < 0) {
+      throw new RangeError(`Line strokeWidth field "${field}" cannot contain negative values.`);
+    }
+    if (result.has(key) && result.get(key) !== value) {
+      throw new Error(`Path ${channel} field "${field}" must have one value within each series.`);
+    }
+    result.set(key, value);
+  });
+  return result;
+}
+
+export function derivePathSeriesFieldValues(rows, series, field, channel) {
+  const fields = Object.keys(series[0]?.key ?? {});
+  const values = seriesValueIndex(rows, fields, field, channel);
+  return series.map(item => values.get(JSON.stringify(Object.values(item.key))));
+}
+
+export function validatePathSeriesAppearance(rows, layer) {
+  if (!["line", "area"].includes(layer.mark?.type) ||
+      layer.encoding?.parallel !== undefined) return;
+  const grouping = readPathSeriesFields(rows, layer);
+  const channels = layer.mark.type === "line"
+    ? ["color", "strokeDash", "strokeWidth", "opacity"] : ["color"];
+  for (const channel of channels) {
+    const encoding = layer.encoding?.[channel];
+    if (encoding?.field === undefined) continue;
+    const allowed = channel === "color" ? ["nominal", "ordinal"]
+      : channel === "strokeDash" ? ["nominal"] : ["quantitative"];
+    if (!allowed.includes(encoding.fieldType)) {
+      throw new Error(`Path ${channel} encoding has an unsupported field type.`);
+    }
+    seriesValueIndex(rows, grouping, encoding.field, channel);
+  }
+  return grouping;
+}
+
+export function readSeriesIdentity(rows, layer) {
+  const group = layer.encoding?.group;
+  const fields = group === undefined ? [] : normalizeGroupFields(group.fields ?? group.field);
+  for (const field of fields) readNominalField(rows, field);
+  const values = rows.map(row => fields.length === 0 ? undefined : fields.length === 1
+    ? row[fields[0]] : JSON.stringify(fields.map(field => row[field])));
+  return { fields, values, domain: [...new Set(values)] };
+}

package/src/grammar/pointPacking.js

@@ -0,0 +1,183 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateNonEmptyString } from "../core/validation.js";
+import { resolveJitterSlotWidth } from "./jitter.js";
+
+export const POINT_PACKING_ALGORITHM = "point-pack-greedy-v1";
+
+export function normalizePointPackingPolicy(options = {}) {
+  if (!isPlainObject(options)) {
+    throw new TypeError("Point packing options must be a plain object.");
+  }
+  if (!["x", "y"].includes(options.channel)) {
+    throw new Error('Point packing channel must be "x" or "y".');
+  }
+  let maxOffset;
+  if (options.maxOffset !== undefined) {
+    if (!isPlainObject(options.maxOffset)) {
+      throw new TypeError("Point packing maxOffset must be a plain object.");
+    }
+    const keys = Object.keys(options.maxOffset);
+    if (keys.length !== 1 || !["pixels", "band"].includes(keys[0])) {
+      throw new Error("Point packing maxOffset requires exactly one of pixels or band.");
+    }
+    const value = options.maxOffset[keys[0]];
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new RangeError(`Point packing ${keys[0]} must be positive and finite.`);
+    }
+    if (keys[0] === "band" && value > 0.5) {
+      throw new RangeError("Point packing band must be at most 0.5.");
+    }
+    maxOffset = { [keys[0]]: value };
+  }
+  const padding = options.padding ?? 1;
+  if (!Number.isFinite(padding) || padding < 0) {
+    throw new RangeError("Point packing padding must be non-negative and finite.");
+  }
+  const key = options.key === undefined
+    ? undefined
+    : validateNonEmptyString(options.key, "Point packing key");
+  const overflow = options.overflow ?? "error";
+  if (!["error", "overlap"].includes(overflow)) {
+    throw new Error('Point packing overflow must be "error" or "overlap".');
+  }
+  return cloneAndFreeze({
+    algorithm: POINT_PACKING_ALGORITHM,
+    channel: options.channel,
+    ...(maxOffset === undefined ? {} : { maxOffset }),
+    padding,
+    ...(key === undefined ? {} : { key }),
+    overflow
+  });
+}
+
+function offsetLimit(policy, slotWidth) {
+  if (policy.maxOffset?.pixels !== undefined) return policy.maxOffset.pixels;
+  if (policy.maxOffset?.band !== undefined) return slotWidth * policy.maxOffset.band;
+  return slotWidth / 2;
+}
+
+function candidateOffsets(entry, placed, minimum, maximum, padding) {
+  const candidates = [0, minimum - entry.base, maximum - entry.base];
+  for (const other of placed) {
+    if (Math.abs(entry.fixed - other.fixed) >=
+        entry.fixedHalfExtent + other.fixedHalfExtent + padding) continue;
+    const distance = entry.halfExtent + other.halfExtent + padding;
+    candidates.push(other.final - entry.base - distance, other.final - entry.base + distance);
+  }
+  return [...new Set(candidates
+    .map(value => Math.max(minimum - entry.base, Math.min(maximum - entry.base, value)))
+    .map(value => Object.is(value, -0) ? 0 : value))]
+    .sort((left, right) => Math.abs(left) - Math.abs(right) || left - right);
+}
+
+function collisions(entry, final, placed, padding) {
+  return placed.filter(other =>
+    Math.abs(entry.fixed - other.fixed) <
+      entry.fixedHalfExtent + other.fixedHalfExtent + padding &&
+    Math.abs(final - other.final) < entry.halfExtent + other.halfExtent + padding
+  );
+}
+
+export function resolvePointPacking({
+  target,
+  policy,
+  scale,
+  entries,
+  plotMinimum,
+  plotMaximum
+}) {
+  validateNonEmptyString(target, "Point packing target");
+  if (!Array.isArray(entries)) throw new TypeError("Point packing entries must be an array.");
+  if (!Number.isFinite(plotMinimum) || !Number.isFinite(plotMaximum) || plotMaximum < plotMinimum) {
+    throw new RangeError("Point packing plot bounds are invalid.");
+  }
+  const slotWidth = resolveJitterSlotWidth(scale);
+  if (slotWidth === undefined) {
+    throw new Error("Point packing requires a categorical position scale with a positive slot.");
+  }
+  const maximumOffset = offsetLimit(policy, slotWidth);
+  const seenIndices = new Set();
+  const seenIdentities = new Set();
+  const ordered = entries.map((entry, offset) => {
+    for (const field of ["index", "base", "fixed", "halfExtent", "fixedHalfExtent"]) {
+      if (!Number.isFinite(entry[field])) {
+        throw new TypeError(`Point packing entry ${offset} ${field} must be finite.`);
+      }
+    }
+    if (!Number.isInteger(entry.index) || entry.index < 0 ||
+        entry.halfExtent < 0 || entry.fixedHalfExtent < 0) {
+      throw new RangeError(`Point packing entry ${offset} geometry is invalid.`);
+    }
+    validateNonEmptyString(entry.identity, `Point packing entry ${offset} identity`);
+    if (seenIndices.has(entry.index)) {
+      throw new Error(`Point packing entry index ${entry.index} must be unique.`);
+    }
+    if (seenIdentities.has(entry.identity)) {
+      throw new Error(`Point packing entry identity "${entry.identity}" must be unique.`);
+    }
+    seenIndices.add(entry.index);
+    seenIdentities.add(entry.identity);
+    return { ...entry };
+  }).sort((left, right) =>
+    left.fixed - right.fixed ||
+    (left.identity < right.identity ? -1 : left.identity > right.identity ? 1 : 0)
+  );
+  const placed = [];
+  for (const entry of ordered) {
+    const minimum = Math.max(
+      plotMinimum + entry.halfExtent,
+      entry.base - slotWidth / 2 + entry.halfExtent,
+      entry.base - maximumOffset
+    );
+    const maximum = Math.min(
+      plotMaximum - entry.halfExtent,
+      entry.base + slotWidth / 2 - entry.halfExtent,
+      entry.base + maximumOffset
+    );
+    if (minimum > maximum) {
+      if (policy.overflow === "error") {
+        throw new RangeError(`Point packing for "${target}" has no available category-slot position.`);
+      }
+      placed.push({ ...entry, final: entry.base, offset: 0, unresolved: true, collisionCount: 0 });
+      continue;
+    }
+    const candidates = candidateOffsets(entry, placed, minimum, maximum, policy.padding)
+      .map(offset => ({
+        offset,
+        final: entry.base + offset,
+        collisions: collisions(entry, entry.base + offset, placed, policy.padding)
+      }));
+    const resolved = candidates.find(candidate => candidate.collisions.length === 0);
+    if (resolved !== undefined) {
+      placed.push({ ...entry, final: resolved.final, offset: resolved.offset,
+        unresolved: false, collisionCount: 0 });
+      continue;
+    }
+    if (policy.overflow === "error") {
+      throw new RangeError(`Point packing for "${target}" cannot avoid glyph overlap.`);
+    }
+    const best = candidates.sort((left, right) =>
+      left.collisions.length - right.collisions.length ||
+      Math.abs(left.offset) - Math.abs(right.offset) || left.offset - right.offset
+    )[0];
+    placed.push({ ...entry, final: best.final, offset: best.offset,
+      unresolved: true, collisionCount: best.collisions.length });
+  }
+  const items = placed.sort((left, right) => left.index - right.index).map(item => ({
+    index: item.index,
+    identity: item.identity,
+    base: item.base,
+    final: item.final,
+    finalOffset: item.offset,
+    unresolved: item.unresolved,
+    collisionCount: item.collisionCount
+  }));
+  return cloneAndFreeze({
+    algorithm: POINT_PACKING_ALGORITHM,
+    slotWidth,
+    maximumOffset,
+    itemCount: items.length,
+    unresolvedItemCount: items.filter(item => item.unresolved).length,
+    items
+  });
+}

package/src/grammar/positionCompatibility.js

@@ -16,7 +16,7 @@ export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
     y: Object.freeze(["quantitative", "temporal"])
   }),
   arc: Object.freeze({
-    theta: Object.freeze(["ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "ordinal", "nominal"]),
     radius: Object.freeze(["quantitative"])
   }),
   rule: Object.freeze({

package/src/grammar/positionDatum.js

@@ -0,0 +1,12 @@
+import { isNominalValue, normalizeTemporalValue, validateSemanticFieldType } from "./scales/index.js";
+
+export function normalizePositionDatum(value, fieldType, channel, temporalUnit, mark = "Position") {
+  validateSemanticFieldType(fieldType);
+  if (fieldType === "quantitative") {
+    if (!Number.isFinite(value)) throw new TypeError(`${mark} ${channel} datum must be a finite number.`);
+    return value;
+  }
+  if (fieldType === "temporal") return normalizeTemporalValue(value, `${channel} datum`, 0, temporalUnit);
+  if (!isNominalValue(value)) throw new TypeError(`${mark} ${channel} datum must be a nominal value.`);
+  return value;
+}

package/src/grammar/rects.js

@@ -1,6 +1,8 @@
 export const RECT_MODES = Object.freeze({
   discrete: "discrete",
-  ranged: "ranged"
+  ranged: "ranged",
+  xSpan: "x-span",
+  ySpan: "y-span"
 });
 
 function categorical(encoding) {
@@ -22,5 +24,11 @@ export function resolveRectMode(layer) {
     return RECT_MODES.discrete;
   }
   if (ranged(x, x2) && ranged(y, y2)) return RECT_MODES.ranged;
+  if (ranged(x, x2) && y === undefined && y2 === undefined) return RECT_MODES.xSpan;
+  if (ranged(y, y2) && x === undefined && x2 === undefined) return RECT_MODES.ySpan;
   return undefined;
 }
+
+export function rectUsesFields(layer) {
+  return ["x", "y", "x2", "y2", "color"].some(channel => Object.hasOwn(layer.encoding?.[channel] ?? {}, "field"));
+}

package/src/grammar/regression/derive.js

@@ -24,6 +24,8 @@ export function deriveRegression(values, {
   method,
   degree,
   span,
+  confidenceMethod,
+  level,
   confidence,
   interval
 } = {}) {
@@ -39,6 +41,8 @@ export function deriveRegression(values, {
     method,
     degree,
     span,
+    confidenceMethod,
+    level,
     confidence,
     interval
   });

package/src/grammar/regression/index.js

@@ -1,4 +1,5 @@
-import { studentTCriticalValue } from "../statistics/studentT.js";
+import { confidenceCriticalValue } from
+  "../statistics/confidenceInterval.js";
 
 export {
   REGRESSION_LOWER_FIELD,
@@ -18,5 +19,9 @@ export function studentTCritical(confidence, degreesOfFreedom) {
   if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom <= 0) {
     throw new RangeError("Student-t degrees of freedom must be positive.");
   }
-  return studentTCriticalValue(confidence, degreesOfFreedom);
+  return confidenceCriticalValue({
+    method: "student-t",
+    level: confidence,
+    degreesOfFreedom
+  });
 }

package/src/grammar/regression/models.js

@@ -1,4 +1,5 @@
-import { studentTCriticalValue } from "../statistics/studentT.js";
+import { confidenceCriticalValue } from
+  "../statistics/confidenceInterval.js";
 import {
   maximumMagnitude,
   requireFiniteResult,
@@ -56,7 +57,9 @@ function linearPrediction(model, xValue) {
   );
 }
 
-function fitLinearGroup(rows, { x, y, group, confidence }) {
+function fitLinearGroup(rows, {
+  x, y, group, confidenceMethod, level
+}) {
   const count = rows.length;
   const groupLabel = group === undefined ? "all" : String(group);
   const label = `Regression group "${groupLabel}"`;
@@ -152,7 +155,11 @@ function fitLinearGroup(rows, { x, y, group, confidence }) {
   return Object.assign(model, {
     residualSumSquares,
     residualStandardError: Math.sqrt(residualSumSquares / degreesOfFreedom),
-    critical: studentTCriticalValue(confidence, degreesOfFreedom)
+    critical: confidenceCriticalValue({
+      method: confidenceMethod,
+      level,
+      degreesOfFreedom
+    })
   });
 }
 
@@ -230,7 +237,9 @@ function polynomialResponse(design, values, size, scale = 1) {
   ));
 }
 
-function fitPolynomialGroup(rows, { x, y, group, confidence, degree }) {
+function fitPolynomialGroup(rows, {
+  x, y, group, confidenceMethod, level, degree
+}) {
   const count = rows.length;
   const parameterCount = degree + 1;
   const groupLabel = group === undefined ? "all" : String(group);
@@ -310,7 +319,11 @@ function fitPolynomialGroup(rows, { x, y, group, confidence, degree }) {
     inverse,
     residualSumSquares,
     residualStandardError: Math.sqrt(residualVariance),
-    critical: studentTCriticalValue(confidence, degreesOfFreedom)
+    critical: confidenceCriticalValue({
+      method: confidenceMethod,
+      level,
+      degreesOfFreedom
+    })
   };
   if (!normalizedXByDifference) model.normalizedXByDifference = false;
   if (stableResponse) Object.assign(model, { responseScale, scaledCoefficients });
@@ -416,7 +429,8 @@ export function fitRegressionGroup(rows, { x, y, group, parameters }) {
       x,
       y,
       group,
-      confidence: parameters.confidence
+      confidenceMethod: parameters.confidenceMethod,
+      level: parameters.level
     });
   }
   if (parameters.method === "polynomial") {
@@ -424,7 +438,8 @@ export function fitRegressionGroup(rows, { x, y, group, parameters }) {
       x,
       y,
       group,
-      confidence: parameters.confidence,
+      confidenceMethod: parameters.confidenceMethod,
+      level: parameters.level,
       degree: parameters.degree
     });
   }

package/src/grammar/regression/parameters.js

@@ -1,5 +1,7 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
 import { validateGeneratedItemLimit } from "../../core/validation.js";
+import { normalizeConfidenceInterval } from
+  "../statistics/confidenceInterval.js";
 
 const MAX_POLYNOMIAL_DEGREE = 32;
 
@@ -14,6 +16,8 @@ export function normalizeRegressionParameters({
   method = "linear",
   degree,
   span,
+  confidenceMethod,
+  level,
   confidence,
   interval
 } = {}) {
@@ -24,7 +28,10 @@ export function normalizeRegressionParameters({
     if (degree !== undefined) {
       throw new Error("Regression degree requires the polynomial method.");
     }
-    if (confidence !== undefined || interval !== undefined) {
+    if (
+      confidenceMethod !== undefined || level !== undefined ||
+      confidence !== undefined || interval !== undefined
+    ) {
       throw new Error("LOESS regression does not support confidence intervals.");
     }
     const resolvedSpan = span ?? 0.75;
@@ -38,14 +45,18 @@ export function normalizeRegressionParameters({
   if (span !== undefined) {
     throw new Error("Regression span requires the loess method.");
   }
-  const resolvedConfidence = confidence ?? 0.95;
-  if (
-    !Number.isFinite(resolvedConfidence) ||
-    resolvedConfidence <= 0 ||
-    resolvedConfidence >= 1
-  ) {
-    throw new RangeError("Regression confidence must be between 0 and 1.");
+  if (level !== undefined && confidence !== undefined && level !== confidence) {
+    throw new Error(
+      "Regression level and confidence alias must match when both are provided."
+    );
   }
+  const confidenceInterval = normalizeConfidenceInterval({
+    method: confidenceMethod,
+    level: level ?? confidence
+  }, {
+    defaultMethod: "student-t",
+    label: "Regression confidence interval"
+  });
   const resolvedInterval = interval ?? "mean";
   if (!["mean", "prediction"].includes(resolvedInterval)) {
     throw new Error(`Unsupported regression interval "${resolvedInterval}".`);
@@ -65,7 +76,8 @@ export function normalizeRegressionParameters({
     return cloneAndFreeze({
       method,
       degree: resolvedDegree,
-      confidence: resolvedConfidence,
+      confidenceMethod: confidenceInterval.method,
+      level: confidenceInterval.level,
       interval: resolvedInterval
     });
   }
@@ -74,14 +86,16 @@ export function normalizeRegressionParameters({
   }
   return cloneAndFreeze({
     method,
-    confidence: resolvedConfidence,
+    confidenceMethod: confidenceInterval.method,
+    level: confidenceInterval.level,
     interval: resolvedInterval
   });
 }
 
 export function validateRegressionTransform(transform) {
   const supported = [
-    "type", "method", "x", "y", "groupBy", "confidence", "interval",
+    "type", "method", "x", "y", "groupBy", "confidenceMethod", "level",
+    "confidence", "interval",
     "degree", "span"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
@@ -96,16 +110,29 @@ export function validateRegressionTransform(transform) {
   if (transform.groupBy !== undefined) {
     requireRegressionField(transform.groupBy, "Regression groupBy field");
   }
+  if (
+    transform.confidence !== undefined &&
+    (transform.confidenceMethod !== undefined || transform.level !== undefined)
+  ) {
+    throw new Error(
+      "Regression confidence provenance must use either the legacy confidence field or method and level."
+    );
+  }
   const normalized = normalizeRegressionParameters({
     method: transform.method,
     degree: transform.degree,
     span: transform.span,
+    confidenceMethod: transform.confidenceMethod,
+    level: transform.level,
     confidence: transform.confidence,
     interval: transform.interval
   });
   if (normalized.method === "loess") return transform;
-  if (!Number.isFinite(transform.confidence)) {
-    throw new RangeError("Regression confidence must be between 0 and 1.");
+  if (
+    transform.confidence === undefined &&
+    (transform.confidenceMethod === undefined || transform.level === undefined)
+  ) {
+    throw new Error("Regression confidence provenance requires method and level.");
   }
   if (transform.interval === undefined) {
     throw new Error(`Unsupported regression interval "${transform.interval}".`);