graphein 0.18.0 → 0.20.0

package/dist/analyze/recommend.js

@@ -0,0 +1,717 @@
+import { validateSpec } from "../spec/validate.js";
+import { getField, toDate, toNumber, uniqueValues } from "../util/data.js";
+import { isMissingValue, profileData, profileEncoding } from "../util/profile.js";
+import { profileColumns, profileData as profileData2 } from "../util/profile.js";
+function title(text) {
+  return text.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().replace(/\b\w/g, (m) => m.toUpperCase());
+}
+function fieldDef(profile) {
+  return { field: profile.field, type: profile.type };
+}
+function boost(score, family, intent) {
+  if (!intent) return score;
+  const matches = family === intent || intent === "comparison" && family === "density";
+  return Math.min(1, score + (matches ? 0.12 : 0));
+}
+function pushValid(candidates, candidate, intent) {
+  const score = Number(boost(candidate.score, candidate.family, intent).toFixed(3));
+  const spec = candidate.spec;
+  if (!validateSpec(spec).valid) return;
+  candidates.push({ ...candidate, score });
+}
+function firstLowCardNominal(profiles, exclude = /* @__PURE__ */ new Set()) {
+  return profiles.find((p) => p.type === "nominal" && p.valid > 0 && p.cardinality <= 12 && !exclude.has(p.field));
+}
+function numericValues(data, field) {
+  return data.map((row) => toNumber(getField(row, field))).filter((value) => Number.isFinite(value));
+}
+function stringValues(data, field) {
+  return data.map((row) => getField(row, field)).filter((value) => !isMissingValue(value)).map((value) => String(value));
+}
+function hasPositiveValues(data, field) {
+  const values = numericValues(data, field);
+  return values.length === data.length && values.length > 0 && values.every((value) => value > 0);
+}
+function fieldNameMatches(field, words) {
+  const normalized = field.toLowerCase();
+  return words.some((word) => normalized.includes(word));
+}
+function hasConversionVocabulary(values) {
+  const vocabulary = [
+    "visit",
+    "lead",
+    "signup",
+    "sign up",
+    "register",
+    "activate",
+    "subscribe",
+    "convert",
+    "purchase",
+    "checkout",
+    "renew",
+    "trial",
+    "demo",
+    "onboard"
+  ];
+  return values.some((value) => {
+    const normalized = value.toLowerCase();
+    return vocabulary.some((word) => normalized.includes(word));
+  });
+}
+function isNearMonotoneDecreasing(values) {
+  if (values.length < 3) return false;
+  let decreases = 0;
+  for (let i = 1; i < values.length; i++) {
+    if (values[i] <= values[i - 1] * 1.05) decreases++;
+  }
+  return decreases / (values.length - 1) >= 0.8;
+}
+function distinctDates(data, field) {
+  return uniqueValues(data, field).map(toDate).filter((value) => value !== null).sort((a, b) => a.getTime() - b.getTime());
+}
+function groupsWithAllValues(data, groupField, valueField, expected) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of data) {
+    const group = getField(row, groupField);
+    const value = getField(row, valueField);
+    if (isMissingValue(group) || isMissingValue(value)) continue;
+    const key = String(group);
+    const values = groups.get(key) ?? /* @__PURE__ */ new Set();
+    values.add(String(value));
+    groups.set(key, values);
+  }
+  let complete = 0;
+  for (const values of groups.values()) {
+    if ([...expected].every((value) => values.has(value))) complete++;
+  }
+  return complete;
+}
+function profileByName(profiles, words) {
+  return profiles.find((profile) => fieldNameMatches(profile.field, words));
+}
+function hasFlowCycle(data, source, target) {
+  const edges = /* @__PURE__ */ new Map();
+  const indegree = /* @__PURE__ */ new Map();
+  for (const row of data) {
+    const from = String(getField(row, source));
+    const to = String(getField(row, target));
+    const targets = edges.get(from) ?? /* @__PURE__ */ new Set();
+    if (!targets.has(to)) {
+      targets.add(to);
+      indegree.set(to, (indegree.get(to) ?? 0) + 1);
+    }
+    edges.set(from, targets);
+    if (!indegree.has(from)) indegree.set(from, 0);
+  }
+  const queue = [...indegree].filter(([, degree]) => degree === 0).map(([node]) => node);
+  for (let i = 0; i < queue.length; i++) {
+    for (const target2 of edges.get(queue[i]) ?? []) {
+      const degree = indegree.get(target2) - 1;
+      indegree.set(target2, degree);
+      if (degree === 0) queue.push(target2);
+    }
+  }
+  return queue.length < indegree.size;
+}
+function candidateEncoding(spec) {
+  const encoding = "encoding" in spec ? spec.encoding : {};
+  const values = Object.values(encoding).filter((ref) => !!ref?.field);
+  const key = (channels) => channels.map((channel) => encoding[channel]).filter((ref) => !!ref);
+  switch (spec.type) {
+    case "line":
+    case "area":
+    case "bar":
+      return { keys: key(["x", "series"]), values };
+    case "scatter":
+      return { keys: key(["x", "y", "color"]), values };
+    case "heatmap":
+      return { keys: key(["x", "y"]), values, complete: true };
+    case "slope":
+      return { keys: key(["x", "series"]), values, complete: true };
+    case "dumbbell":
+      return { keys: key(["category", "group"]), values, complete: true };
+    case "pie":
+      return { keys: key(["color"]), values };
+    case "funnel":
+      return { keys: key(["stage"]), values };
+    case "treemap":
+      return { keys: key(["group", "category"]), values };
+    case "sankey":
+      return { keys: key(["source", "target"]), values };
+    case "matrix":
+      return {
+        keys: [...spec.rows, ...spec.columns ?? []],
+        values: spec.values.map((value) => ({ field: value.field, type: "quantitative" })),
+        complete: true
+      };
+    case "kpi":
+    case "gauge":
+    case "bullet":
+      return {
+        keys: [],
+        values: [spec.value, "target" in spec ? spec.target : void 0].filter((ref) => typeof ref === "object" && ref !== null).map((ref) => ({ field: ref.field, type: "quantitative" }))
+      };
+    default:
+      return { keys: [], values };
+  }
+}
+function explainCandidate(candidate, data, profile, opts) {
+  const { spec } = candidate;
+  const refs = candidateEncoding(spec);
+  const selected = new Set([...refs.keys, ...refs.values ?? []].map((ref) => typeof ref === "string" ? ref : ref.field));
+  if (spec.type === "table") {
+    for (const column of spec.columns ?? []) selected.add(column.field);
+  }
+  const columns = profile.columns.filter((column) => selected.has(column.field));
+  const findings = profile.findings.filter((finding) => !finding.fields || finding.fields.some((field) => selected.has(field)));
+  const encoding = selected.size && spec.type !== "table" ? profileEncoding(data, refs, profile.columns, true) : void 0;
+  if (encoding && encoding.usableRows === 0) return void 0;
+  const add = (code, message, fields, requiresDecision = true, count) => {
+    findings.push({ code, message, fields, requiresDecision, severity: requiresDecision ? "warning" : "info", ...count === void 0 ? {} : { count } });
+  };
+  const measures = profile.columns.filter((column) => column.type === "quantitative" && column.quantitative.valid > 0);
+  const unusedMeasures = measures.filter((column) => !selected.has(column.field));
+  if (unusedMeasures.length && spec.type !== "table") {
+    add("measure-choice", `Other quantitative fields are plausible measures: ${unusedMeasures.map((column) => column.field).join(", ")}. Confirm the selected field roles; column order does not establish intent.`, measures.map((column) => column.field));
+  }
+  const unusedPositions = profile.columns.filter((column) => (column.type === "temporal" || column.type === "ordinal") && column.valid > 0 && !selected.has(column.field));
+  if (unusedPositions.length && columns.some((column) => column.type === "temporal" || column.type === "ordinal") && spec.type !== "table") {
+    add("position-choice", `Other ordered fields are plausible positions: ${unusedPositions.map((column) => column.field).join(", ")}. Confirm which date/order answers the question.`, unusedPositions.map((column) => column.field));
+  }
+  const unusedCategories = profile.columns.filter((column) => column.type === "nominal" && column.valid > 0 && !selected.has(column.field));
+  if (unusedCategories.length && columns.some((column) => column.type === "nominal") && spec.type !== "table") {
+    add("category-choice", `Confirm the category/series roles; ${unusedCategories.map((column) => column.field).join(", ")} are also plausible grouping fields.`, unusedCategories.map((column) => column.field));
+  }
+  if (encoding?.missingRows) {
+    add("incomplete-observations", `${encoding.missingRows} rows lack at least one required encoded value. The candidate preserves these rows; missing values are not zero.`, [...selected], true, encoding.missingRows);
+  }
+  if (encoding?.invalidRows) {
+    add("invalid-observations", `${encoding.invalidRows} rows have an invalid encoded value and cannot supply a complete mark.`, [...selected], true, encoding.invalidRows);
+  }
+  if (encoding?.duplicateRows) {
+    if (["pie", "funnel", "treemap", "matrix"].includes(spec.type)) {
+      add("aggregation-choice", `${spec.type} combines repeated encoded keys using its aggregation behavior. Confirm that summing these observations is meaningful; no input rows were pre-aggregated.`, encoding.keys, true, encoding.duplicateRows);
+    } else if (spec.type === "scatter" || spec.type === "sankey") {
+      add("overlapping-observations", "Repeated encoded positions/links remain separate observations and can overlap.", encoding.keys, false, encoding.duplicateRows);
+    } else {
+      add("duplicate-keys", "Several observations share an encoded position. Choose a series, an explicit aggregate transform, or a row-preserving display; this candidate does not decide for you.", encoding.keys, true, encoding.duplicateRows);
+    }
+  }
+  if (encoding?.missingCombinations) {
+    add("sparse-combinations", "Some combinations of the observed categories are absent. Confirm whether the comparison is intentionally sparse; no combinations are filled.", encoding.keys, true, encoding.missingCombinations);
+  }
+  if ((spec.type === "kpi" || spec.type === "matrix") && data.length > 1 && !findings.some((finding) => finding.code === "aggregation-choice")) {
+    add("aggregation-choice", "This candidate proposes a sum. Confirm the aggregation is meaningful for this measure; use an explicit aggregate transform or a different aggregate when appropriate.", columns.filter((column) => column.type === "quantitative").map((column) => column.field));
+  }
+  if (spec.type === "waterfall") {
+    add("delta-semantics", "Signed values alone do not establish ordered changes. Confirm that these rows are deltas in the intended order before using a running total.", [spec.encoding.stage.field, spec.encoding.value.field]);
+  }
+  if (spec.type === "calendarHeatmap") {
+    const days = /* @__PURE__ */ new Set();
+    let repeated = 0;
+    for (const row of data) {
+      const date = toDate(getField(row, spec.encoding.date.field));
+      if (!date) continue;
+      const key = `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+      if (days.has(key)) repeated++;
+      days.add(key);
+    }
+    if (repeated) add("aggregation-choice", "Calendar heatmaps sum observations within each local calendar day. Confirm this daily aggregation is intended.", [spec.encoding.date.field], true, repeated);
+  }
+  const categoricalAxis = columns.find((column) => refs.keys.some((ref) => (typeof ref === "string" ? ref : ref.field) === column.field) && (column.type === "nominal" || column.type === "ordinal"));
+  if (categoricalAxis && ["bar", "line", "area", "slope", "dumbbell"].includes(spec.type)) {
+    const count = categoricalAxis.nonMissingCardinality;
+    const width = opts.targetSize?.width;
+    if (count > 12 || width && Number.isFinite(width) && count * 24 > width) {
+      add("size-cardinality", `${count} categories may not remain individually legible${width ? ` at ${width}px wide` : ""}. Consider more space, orientation, or a table; filtering/grouping requires your explicit choice.`, [categoricalAxis.field], true, count);
+    }
+  }
+  const decisions = findings.filter((finding) => finding.requiresDecision).length;
+  const score = Math.max(0, Number((candidate.score - Math.min(0.3, decisions * 0.06)).toFixed(3)));
+  return {
+    spec,
+    score,
+    rationale: candidate.rationale,
+    status: decisions ? "needs-decision" : "ready",
+    findings,
+    evidence: {
+      columns,
+      sampling: profile.sampling,
+      ...encoding ? { encoding } : {},
+      ...opts.intent ? { intent: opts.intent } : {},
+      ...opts.targetSize ? { targetSize: { ...opts.targetSize } } : {}
+    }
+  };
+}
+function createRecommendContext(input, opts) {
+  const data = Array.isArray(input) ? input : [];
+  const profile = profileData(data);
+  const profiles = profile.columns;
+  const quantitative = profiles.filter((p) => p.type === "quantitative" && p.quantitative.valid > 0);
+  const nominal = profiles.filter((p) => p.type === "nominal" && p.valid > 0);
+  const measure = quantitative.find((p) => p.cardinality > 2) ?? quantitative[0];
+  return {
+    data,
+    opts,
+    profile,
+    profiles,
+    quantitative,
+    ordered: profiles.filter((p) => (p.type === "temporal" || p.type === "ordinal") && p.valid > 0),
+    nominal,
+    lowNominal: nominal.filter((p) => p.cardinality <= 12),
+    manyNominal: nominal.filter((p) => p.cardinality > 12),
+    candidates: [],
+    guidance: [],
+    ...measure ? { measure } : {}
+  };
+}
+function finishRecommendations(ctx, recommendations, extra = []) {
+  if (!ctx.opts.detailed) return recommendations;
+  const findings = [.../* @__PURE__ */ new Set([...ctx.profile.findings, ...recommendations[0]?.findings ?? [], ...extra])];
+  if (!recommendations.length) findings.push({
+    code: ctx.data.length ? "no-usable-candidate" : "empty-data",
+    severity: "warning",
+    requiresDecision: true,
+    message: ctx.data.length ? "No candidate can represent the available fields. Supply usable observations or specify the intended field types/roles." : "No observations were supplied; no data or chart values were invented."
+  });
+  return {
+    recommendations,
+    profile: ctx.profile,
+    findings,
+    status: !recommendations.length ? "no-candidate" : findings.some((finding) => finding.requiresDecision) || recommendations[0].status === "needs-decision" ? "needs-decision" : "ready"
+  };
+}
+function addGuidance(ctx) {
+  const { opts, measure, guidance } = ctx;
+  if (opts.intent === "composition" && measure && measure.quantitative.negative > 0) {
+    guidance.push({
+      code: "signed-composition",
+      severity: "warning",
+      fields: [measure.field],
+      requiresDecision: true,
+      message: `"${measure.field}" contains negative values. A pie/treemap cannot faithfully show signed composition; choose a signed comparison or explicitly define a different measure.`
+    });
+  }
+}
+function addFunnelCandidate(ctx) {
+  const { data, profiles, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const stage = profiles.find((p) => (p.type === "nominal" || p.type === "ordinal") && p.cardinality >= 3 && p.cardinality <= 12 && p.cardinality === data.length);
+  if (!stage || !hasPositiveValues(data, measure.field)) return;
+  const values = numericValues(data, measure.field);
+  const stages = stringValues(data, stage.field);
+  const stageLike = fieldNameMatches(stage.field, ["stage", "step", "funnel", "phase", "status"]);
+  const conversionLike = hasConversionVocabulary(stages);
+  if (!isNearMonotoneDecreasing(values) || !stageLike && !conversionLike) return;
+  pushValid(candidates, {
+    spec: {
+      type: "funnel",
+      data,
+      encoding: { stage: fieldDef(stage), value: fieldDef(measure) },
+      title: `${title(measure.field)} funnel by ${title(stage.field)}`,
+      percent: "first"
+    },
+    score: 0.88,
+    family: "composition",
+    rationale: `${title(stage.field)} looks like ordered funnel stages and ${title(measure.field)} mostly decreases, so a funnel shows conversion drop-off.`
+  }, opts.intent);
+}
+function addWaterfallCandidate(ctx) {
+  const { data, profiles, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const stage = profiles.find((p) => (p.type === "nominal" || p.type === "ordinal") && p.cardinality >= 3 && p.cardinality <= 20 && p.cardinality === data.length);
+  if (!stage) return;
+  const values = numericValues(data, measure.field);
+  const hasIncrease = values.some((value) => value > 0);
+  const hasDecrease = values.some((value) => value < 0);
+  if (values.length !== data.length || !hasIncrease || !hasDecrease) return;
+  pushValid(candidates, {
+    spec: {
+      type: "waterfall",
+      data,
+      encoding: { stage: fieldDef(stage), value: fieldDef(measure) },
+      title: `${title(measure.field)} bridge by ${title(stage.field)}`,
+      showTotal: true
+    },
+    score: 0.87,
+    family: "comparison",
+    rationale: `${title(measure.field)} contains signed positive and negative steps, so a waterfall shows how each ${title(stage.field)} changes the running total.`
+  }, opts.intent);
+}
+function addSankeyCandidate(ctx) {
+  const { data, nominal, candidates, guidance, opts, measure } = ctx;
+  if (nominal.length < 2 || !measure || !hasPositiveValues(data, measure.field)) return;
+  const source = profileByName(nominal, ["source", "from", "origin", "upstream"]) ?? nominal.find((profile) => profile.cardinality >= 2 && profile.cardinality <= 30);
+  const target = profileByName(nominal.filter((profile) => profile.field !== source?.field), [
+    "target",
+    "to",
+    "destination",
+    "downstream"
+  ]) ?? nominal.find((profile) => profile.field !== source?.field && profile.cardinality >= 2 && profile.cardinality <= 30);
+  if (!source || !target) return;
+  const sharedNodes = [...new Set(stringValues(data, source.field))].filter((value) => new Set(stringValues(data, target.field)).has(value)).length;
+  const namedFlow = fieldNameMatches(source.field, ["source", "from", "origin", "upstream"]) || fieldNameMatches(target.field, ["target", "to", "destination", "downstream"]);
+  const cyclic = hasFlowCycle(data, source.field, target.field);
+  if ((namedFlow || sharedNodes > 0) && !cyclic) {
+    pushValid(candidates, {
+      spec: {
+        type: "sankey",
+        data,
+        encoding: { source: fieldDef(source), target: fieldDef(target), value: fieldDef(measure) },
+        title: `${title(measure.field)} flow from ${title(source.field)} to ${title(target.field)}`
+      },
+      score: 0.82,
+      family: "relationship",
+      rationale: `${title(source.field)} and ${title(target.field)} form source and target entities with positive ${title(measure.field)}, so a sankey shows flow magnitude.`
+    }, opts.intent);
+  } else if (namedFlow && cyclic) {
+    guidance.push({
+      code: "flow-cycle",
+      severity: "warning",
+      fields: [source.field, target.field],
+      requiresDecision: true,
+      message: "Source/target rows contain a cycle or self-link. Sankey layouts cannot preserve every such link; choose a row-preserving view or explicitly resolve the flow model."
+    });
+  }
+}
+function addTreemapCandidate(ctx) {
+  const { data, nominal, profiles, candidates, opts, measure } = ctx;
+  if (!measure || !hasPositiveValues(data, measure.field)) return;
+  const category = nominal.find((profile) => profile.cardinality > 7);
+  if (!category) return;
+  const group = firstLowCardNominal(profiles, /* @__PURE__ */ new Set([category.field, measure.field]));
+  pushValid(candidates, {
+    spec: {
+      type: "treemap",
+      data,
+      encoding: {
+        category: fieldDef(category),
+        value: fieldDef(measure),
+        ...group ? { group: fieldDef(group) } : {}
+      },
+      title: `${title(measure.field)} by ${title(category.field)}`
+    },
+    score: 0.7,
+    family: "composition",
+    rationale: `${title(category.field)} has ${category.cardinality} categories, too many for a clear pie, so a treemap shows part-to-whole area by ${title(measure.field)}.`
+  }, opts.intent);
+}
+function addBoxCandidate(ctx) {
+  const { data, lowNominal, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const category = lowNominal.find((profile) => {
+    const counts = /* @__PURE__ */ new Map();
+    for (const row of data) {
+      const value = getField(row, profile.field);
+      if (isMissingValue(value)) continue;
+      const key = String(value);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts.size >= 2 && [...counts.values()].every((count) => count >= 5);
+  });
+  if (!category) return;
+  pushValid(candidates, {
+    spec: {
+      type: "box",
+      data,
+      encoding: { x: fieldDef(category), y: fieldDef(measure) },
+      title: `${title(measure.field)} distribution by ${title(category.field)}`
+    },
+    score: 0.81,
+    family: "distribution",
+    rationale: `${title(category.field)} repeats with many ${title(measure.field)} observations per category, so a box plot summarizes spread and outliers.`
+  }, opts.intent);
+}
+function addCalendarHeatmapCandidate(ctx) {
+  const { data, profiles, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const date = profiles.find((profile) => profile.type === "temporal");
+  if (!date) return;
+  const dates = distinctDates(data, date.field);
+  const spanDays = dates.length > 1 ? (dates[dates.length - 1].getTime() - dates[0].getTime()) / 864e5 : 0;
+  const density = spanDays > 0 ? dates.length / spanDays : 0;
+  if (dates.length < 180 || spanDays < 300 || density < 0.45) return;
+  pushValid(candidates, {
+    spec: {
+      type: "calendarHeatmap",
+      data,
+      encoding: { date: fieldDef(date), color: fieldDef(measure) },
+      title: `${title(measure.field)} by day`
+    },
+    score: 0.72,
+    family: "density",
+    rationale: `${title(date.field)} is daily temporal data spanning about a year, so a calendar heatmap shows day-by-day ${title(measure.field)} intensity.`
+  }, opts.intent);
+}
+function addSlopeCandidate(ctx) {
+  const { data, profiles, nominal, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const x = profiles.find((profile) => (profile.type === "temporal" || profile.type === "nominal" || profile.type === "ordinal") && profile.cardinality === 2);
+  const series = nominal.find((profile) => profile.field !== x?.field && profile.cardinality >= 2);
+  if (!x || !series) return;
+  const xValues = new Set(stringValues(data, x.field));
+  if (groupsWithAllValues(data, series.field, x.field, xValues) < 2) return;
+  pushValid(candidates, {
+    spec: {
+      type: "slope",
+      data,
+      encoding: { x: fieldDef(x), y: fieldDef(measure), series: fieldDef(series) },
+      title: `${title(measure.field)} change by ${title(series.field)}`,
+      colorByChange: true
+    },
+    score: 0.79,
+    family: "trend",
+    rationale: `${title(x.field)} has exactly two positions for each ${title(series.field)}, so a slope chart emphasizes before-and-after change in ${title(measure.field)}.`
+  }, opts.intent);
+}
+function addDumbbellCandidate(ctx) {
+  const { data, profiles, nominal, candidates, opts, measure } = ctx;
+  if (!measure || nominal.length < 1) return;
+  const group = profiles.find((profile) => profile.field !== measure.field && profile.cardinality === 2);
+  const category = nominal.find((profile) => profile.field !== group?.field && profile.cardinality >= 2);
+  if (!group || !category) return;
+  const groupValues = new Set(stringValues(data, group.field));
+  if (groupsWithAllValues(data, category.field, group.field, groupValues) < 2) return;
+  pushValid(candidates, {
+    spec: {
+      type: "dumbbell",
+      data,
+      encoding: { category: fieldDef(category), value: fieldDef(measure), group: fieldDef(group) },
+      title: `${title(measure.field)} gap by ${title(category.field)}`,
+      sort: "gap"
+    },
+    score: 0.78,
+    family: "comparison",
+    rationale: `${title(group.field)} has exactly two groups within each ${title(category.field)}, so a dumbbell chart makes the ${title(measure.field)} gap easy to compare.`
+  }, opts.intent);
+}
+function addSingleValueCandidates(ctx) {
+  const { data, quantitative, candidates, guidance, opts } = ctx;
+  if (data.length !== 1 || quantitative.length < 2) return;
+  const value = profileByName(quantitative, ["value", "actual", "current", "sales", "revenue"]) ?? quantitative[0];
+  const target = profileByName(quantitative.filter((profile) => profile.field !== value.field), ["target", "goal", "budget", "plan", "quota"]);
+  const max = profileByName(
+    quantitative.filter((profile) => profile.field !== value.field && profile.field !== target?.field),
+    ["max", "total", "limit", "capacity"]
+  );
+  const valueNumber = numericValues(data, value.field)[0];
+  const targetNumber = target ? numericValues(data, target.field)[0] : void 0;
+  const maxNumber = max ? numericValues(data, max.field)[0] : void 0;
+  if (target && Number.isFinite(targetNumber)) {
+    pushValid(candidates, {
+      spec: { type: "bullet", data, value: { field: value.field }, target: { field: target.field }, max: Number.isFinite(maxNumber) ? maxNumber : void 0, label: title(value.field), title: `${title(value.field)} vs ${title(target.field)}` },
+      score: 0.86,
+      family: "value",
+      rationale: `${title(value.field)} is a single value with ${title(target.field)} as a target, so a bullet graph shows compact KPI attainment.`
+    }, opts.intent);
+  }
+  if (max && Number.isFinite(maxNumber) && typeof valueNumber === "number" && Number.isFinite(valueNumber)) {
+    const gaugeMax = maxNumber;
+    if (gaugeMax > 0 && gaugeMax > valueNumber) pushValid(candidates, {
+      spec: { type: "gauge", data, value: { field: value.field }, max: gaugeMax, target: target ? { field: target.field } : void 0, label: title(value.field), title: `${title(value.field)} attainment` },
+      score: 0.84,
+      family: "value",
+      rationale: `${title(value.field)} is a single value against ${target ? title(target.field) : title(max?.field ?? "Maximum")}, so a gauge shows progress on a bounded scale.`
+    }, opts.intent);
+  } else if (target && !max) {
+    guidance.push({
+      code: "missing-maximum",
+      severity: "info",
+      fields: [value.field, target.field],
+      requiresDecision: true,
+      message: "A target does not establish a gauge maximum. Supply an explicit maximum to recommend a gauge; a bullet chart is available without inventing one."
+    });
+  }
+}
+function addTrendCandidate(ctx) {
+  const { data, ordered, profiles, candidates, opts, measure } = ctx;
+  if (ordered.length === 0 || !measure) return;
+  const x = ordered[0];
+  const encoding = { x: fieldDef(x), y: fieldDef(measure) };
+  const series = firstLowCardNominal(profiles, /* @__PURE__ */ new Set([x.field, measure.field]));
+  if (series) encoding.series = fieldDef(series);
+  pushValid(candidates, {
+    spec: {
+      type: "line",
+      data,
+      encoding,
+      title: `${title(measure.field)} over ${title(x.field)}`
+    },
+    score: 0.92,
+    family: "trend",
+    rationale: `${title(x.field)} is ${x.type}, so a line chart shows how ${title(measure.field)} changes over ordered rows${series ? `, split by low-cardinality ${title(series.field)}` : ""}.`
+  }, opts.intent);
+}
+function addBarAndPieCandidates(ctx) {
+  const { data, lowNominal, manyNominal, candidates, opts, measure } = ctx;
+  if (!measure) return;
+  const category = lowNominal[0];
+  if (category) {
+    pushValid(candidates, {
+      spec: {
+        type: "bar",
+        data,
+        encoding: { x: fieldDef(category), y: fieldDef(measure) },
+        title: `${title(measure.field)} by ${title(category.field)}`
+      },
+      score: 0.84,
+      family: "comparison",
+      rationale: `${title(category.field)} has ${category.cardinality} categories, making bars a good comparison of ${title(measure.field)}.`
+    }, opts.intent);
+    if (category.cardinality <= 7 && measure.quantitative.negative === 0 && measure.quantitative.positive > 0 && measure.quantitative.valid === data.length) {
+      pushValid(candidates, {
+        spec: {
+          type: "pie",
+          data,
+          encoding: { theta: fieldDef(measure), color: fieldDef(category) },
+          title: `${title(measure.field)} share by ${title(category.field)}`
+        },
+        score: 0.58,
+        family: "composition",
+        rationale: `${title(category.field)} has ${category.cardinality} slices, so a pie can show part-to-whole share for ${title(measure.field)}.`
+      }, opts.intent);
+    }
+  } else if (manyNominal.length > 0) {
+    const wideCategory = manyNominal[0];
+    pushValid(candidates, {
+      spec: {
+        type: "bar",
+        data,
+        encoding: { x: fieldDef(wideCategory), y: fieldDef(measure) },
+        title: `${title(measure.field)} by ${title(wideCategory.field)}`
+      },
+      score: 0.62,
+      family: "comparison",
+      rationale: `${title(wideCategory.field)} has ${wideCategory.cardinality} categories. This bar preserves every row; consider more space or a table, and explicitly choose any filtering or grouping.`
+    }, opts.intent);
+  }
+}
+function addScatterCandidate(ctx) {
+  const { data, profiles, quantitative, candidates, opts } = ctx;
+  if (quantitative.length < 2) return;
+  const [x, y] = quantitative;
+  const encoding = { x: fieldDef(x), y: fieldDef(y) };
+  const color = firstLowCardNominal(profiles, /* @__PURE__ */ new Set([x.field, y.field]));
+  if (color) encoding.color = fieldDef(color);
+  pushValid(candidates, {
+    spec: {
+      type: "scatter",
+      data,
+      encoding,
+      title: `${title(y.field)} vs ${title(x.field)}`
+    },
+    score: 0.86,
+    family: "relationship",
+    rationale: `${title(x.field)} and ${title(y.field)} are quantitative, so scatter reveals their relationship${color ? ` with ${title(color.field)} as color` : ""}. Additional measures are not silently assigned to bubble size.`
+  }, opts.intent);
+}
+function addSingleMeasureCandidates(ctx) {
+  const { data, quantitative, candidates, opts } = ctx;
+  if (quantitative.length !== 1) return;
+  const q = quantitative[0];
+  pushValid(candidates, {
+    spec: {
+      type: "histogram",
+      data,
+      encoding: { x: fieldDef(q) },
+      title: `${title(q.field)} distribution`
+    },
+    score: 0.78,
+    family: "distribution",
+    rationale: `${title(q.field)} is the only quantitative field, so a histogram shows its distribution.`
+  }, opts.intent);
+  pushValid(candidates, {
+    spec: {
+      type: "kpi",
+      data,
+      value: { field: q.field, aggregate: "sum" },
+      label: `Total ${title(q.field)}`,
+      title: `Total ${title(q.field)}`
+    },
+    score: 0.62,
+    family: "value",
+    rationale: `${title(q.field)} is the only quantitative field, so a KPI summarizes it as a total.`
+  }, opts.intent);
+}
+function addHeatmapAndMatrixCandidates(ctx) {
+  const { data, lowNominal, candidates, opts, measure } = ctx;
+  if (lowNominal.length < 2 || !measure) return;
+  const [x, y] = lowNominal;
+  pushValid(candidates, {
+    spec: {
+      type: "heatmap",
+      data,
+      encoding: { x: fieldDef(x), y: fieldDef(y), color: fieldDef(measure) },
+      title: `${title(measure.field)} by ${title(x.field)} and ${title(y.field)}`
+    },
+    score: 0.76,
+    family: "density",
+    rationale: `${title(x.field)} and ${title(y.field)} are low-cardinality categories, so a heatmap shows ${title(measure.field)} across their combinations.`
+  }, opts.intent);
+  pushValid(candidates, {
+    spec: {
+      type: "matrix",
+      data,
+      rows: [y.field],
+      columns: [x.field],
+      values: [{ field: measure.field, op: "sum" }],
+      title: `${title(measure.field)} matrix`
+    },
+    score: 0.68,
+    family: "density",
+    rationale: `A matrix summarizes ${title(measure.field)} by ${title(y.field)} rows and ${title(x.field)} columns.`
+  }, opts.intent);
+}
+function addTableCandidate(ctx) {
+  const { data, profiles, candidates, opts } = ctx;
+  if (!profiles.some((column) => column.valid > 0)) return;
+  pushValid(candidates, {
+    spec: {
+      type: "table",
+      data,
+      columns: profiles.map((column) => ({ field: column.field })),
+      title: "Data detail"
+    },
+    score: 0.4,
+    family: "comparison",
+    rationale: "A table retains individual observations without choosing an aggregate, ordering, or quantitative meaning for an identifier. Browser tables can scroll; static exports have finite space."
+  }, opts.intent);
+}
+function buildCandidates(ctx) {
+  addGuidance(ctx);
+  addFunnelCandidate(ctx);
+  addWaterfallCandidate(ctx);
+  addSankeyCandidate(ctx);
+  addTreemapCandidate(ctx);
+  addBoxCandidate(ctx);
+  addCalendarHeatmapCandidate(ctx);
+  addSlopeCandidate(ctx);
+  addDumbbellCandidate(ctx);
+  addSingleValueCandidates(ctx);
+  addTrendCandidate(ctx);
+  addBarAndPieCandidates(ctx);
+  addScatterCandidate(ctx);
+  addSingleMeasureCandidates(ctx);
+  addHeatmapAndMatrixCandidates(ctx);
+  addTableCandidate(ctx);
+}
+function selectRecommendations(ctx) {
+  const max = ctx.opts.maxResults === void 0 || !Number.isFinite(ctx.opts.maxResults) ? 5 : Math.max(0, Math.floor(ctx.opts.maxResults));
+  const results = ctx.candidates.map((candidate) => explainCandidate(candidate, ctx.data, ctx.profile, ctx.opts)).filter((candidate) => candidate !== void 0).sort((a, b) => b.score - a.score).slice(0, max);
+  for (const result of results) {
+    result.alternatives = [...new Set(results.filter((other) => other !== result).map((other) => other.spec.type))];
+  }
+  return results;
+}
+function recommendChart(input, opts = {}) {
+  const ctx = createRecommendContext(input, opts);
+  if (ctx.data.length === 0) return finishRecommendations(ctx, []);
+  buildCandidates(ctx);
+  return finishRecommendations(ctx, selectRecommendations(ctx), ctx.guidance);
+}
+export {
+  profileColumns,
+  profileData2 as profileData,
+  recommendChart
+};
+//# sourceMappingURL=recommend.js.map