@outsidedata/dolex 0.1.0

package/src/patterns/definitions/comparison/connected-dot-plot.ts

@@ -0,0 +1,113 @@
+/**
+ * Connected Dot Plot — two metrics per category.
+ *
+ * Also called a "dumbbell chart" or "Cleveland dot plot".
+ * Shows two values per category connected by a line, making
+ * the gap between them the primary visual. Far clearer than
+ * grouped bars for comparing two measures.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const connectedDotPlotPattern: VisualizationPattern = {
+  id: 'connected-dot-plot',
+  name: 'Connected Dot Plot',
+  category: 'comparison',
+  description:
+    'Two dots per category connected by a line. The length of the connecting line encodes the gap between two values, making differences immediately visible.',
+  bestFor:
+    'Comparing two metrics per category: budget vs actual, male vs female, 2020 vs 2024, target vs achieved.',
+  notFor:
+    'Single metric (use bar), more than 2 metrics (use parallel coordinates or radar), time series with many points (use line).',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 30,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category labels' },
+      { type: 'numeric', count: 2, description: 'Two values to compare per category' },
+    ],
+    minCategories: 3,
+    maxCategories: 20,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Exactly 2 numeric columns — connected dot plot is superior to grouped bar',
+      weight: 70,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount === 2 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 3 &&
+          ctx.dataShape.categoryCount <= 20
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions comparing two things per category',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(budget\s*vs|actual\s*vs|male\s*(and|vs)|female\s*(and|vs)|gap|both|two\s+metric|dual|paired|dumbbell)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions range or span between values',
+      weight: 40,
+      matches: (ctx) => {
+        return /\b(range|span|min.+max|low.+high|start.+end)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Penalize for single metric',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const metric1Col = columns.length > 1 ? columns[1] : columns[0];
+    const metric2Col = columns.length > 2 ? columns[2] : metric1Col;
+
+    const spec: VisualizationSpec = {
+      pattern: 'connected-dot-plot',
+      title: options?.title ?? `${metric1Col} vs ${metric2Col} by ${categoryCol}`,
+      data,
+      encoding: {
+        y: {
+          field: categoryCol,
+          type: 'nominal',
+          title: categoryCol,
+          sort: null,
+        },
+        x: {
+          field: metric1Col,
+          type: 'quantitative',
+          title: `${metric1Col} / ${metric2Col}`,
+        },
+        color: {
+          scale: {
+            domain: [metric1Col, metric2Col],
+            range: options?.colors ?? ['#4e79a7', '#e15759'],
+          },
+        },
+      },
+      config: {
+        metric1Field: metric1Col,
+        metric2Field: metric2Col,
+        categoryField: categoryCol,
+        showLabels: options?.showLabels ?? true,
+        showDifference: options?.showDifference ?? true,
+        sortBy: options?.sortBy ?? 'gap',
+        sortOrder: options?.sortOrder ?? 'descending',
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/diverging-bar.ts

@@ -0,0 +1,110 @@
+/**
+ * Diverging Bar Chart — differences from a baseline or zero.
+ *
+ * Excels when values span positive and negative, or when comparing
+ * deviations from an average/target. The visual encoding of direction
+ * (left vs right, or up vs down) makes differences instantly readable.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const divergingBarPattern: VisualizationPattern = {
+  id: 'diverging-bar',
+  name: 'Diverging Bar Chart',
+  category: 'comparison',
+  description:
+    'Horizontal bars extending left and right from a central baseline. Shows positive and negative deviations clearly.',
+  bestFor:
+    'Data with positive and negative values, profit/loss, above/below average, sentiment scores, change from baseline.',
+  notFor: 'All-positive data without a meaningful midpoint. Use standard bar instead.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 40,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category labels' },
+      { type: 'numeric', count: 1, description: 'Value with positive and negative range' },
+    ],
+    minCategories: 3,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Data contains negative values — diverging bar is ideal',
+      weight: 70,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasNegativeValues &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions difference, change, deviation, or baseline',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(differ|change|deviat|baseline|target|above|below|gain|loss|profit|deficit|surplus|sentiment|positive|negative)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Value range spans zero with meaningful spread on both sides',
+      weight: 30,
+      matches: (ctx) => {
+        const { min, max } = ctx.dataShape.valueRange;
+        return min < 0 && max > 0 && Math.abs(min) > max * 0.2 && Math.abs(max) > Math.abs(min) * 0.2;
+      },
+    },
+    {
+      condition: 'Penalize when no negative values exist',
+      weight: -40,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasNegativeValues;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'diverging-bar',
+      title: options?.title ?? `${valueCol} deviation by ${categoryCol}`,
+      data,
+      encoding: {
+        x: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        y: {
+          field: categoryCol,
+          type: 'nominal',
+          title: categoryCol,
+          sort: null,
+        },
+        color: {
+          field: valueCol,
+          type: 'quantitative',
+          scale: {
+            domain: [
+              Math.min(...data.map((d) => Number(d[valueCol]) || 0)),
+              0,
+              Math.max(...data.map((d) => Number(d[valueCol]) || 0)),
+            ],
+            range: ['#d73027', '#f7f7f7', '#1a9850'],
+          },
+        },
+      },
+      config: {
+        orientation: 'horizontal',
+        showLabels: true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/grouped-bar.ts

@@ -0,0 +1,119 @@
+/**
+ * Grouped Bar — side-by-side bars for multi-metric comparison.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const groupedBarPattern: VisualizationPattern = {
+  id: 'grouped-bar',
+  name: 'Grouped Bar Chart',
+  category: 'comparison',
+  description:
+    'Side-by-side bars for comparing multiple metrics or series across categories. Nested groups with color-coded series.',
+  bestFor:
+    'Direct comparison of 2-4 metrics per category: revenue vs cost by department, male vs female enrollment by year, Q1 vs Q2 sales by product.',
+  notFor:
+    'Single metric (use bar), part-to-whole (use stacked-bar), >5 series (too many bars per group), time series (use line).',
+
+  dataRequirements: {
+    minRows: 4,
+    maxRows: 100,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Group category' },
+      { type: 'numeric', count: 1, description: 'Value to compare' },
+    ],
+    minCategories: 2,
+    maxCategories: 20,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions grouped bar or side-by-side bar',
+      weight: 90,
+      matches: (ctx) => {
+        return /\b(grouped?\s*bar|side[\s-]*by[\s-]*side\s*bar|clustered?\s*bar)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Two categorical columns + one numeric — classic grouped bar shape',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Multiple numeric columns with categories — compare metrics side by side',
+      weight: 50,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount <= 5 &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions comparing multiple metrics',
+      weight: 25,
+      matches: (ctx) => {
+        return /\b(compar\w+\s+(multiple|several|different)\s+(metric|measure|value|series)|side[\s-]*by[\s-]*side|grouped)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Penalize for single numeric column with single categorical — regular bar is simpler',
+      weight: -30,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount === 1 &&
+          ctx.dataShape.categoricalColumnCount === 1
+        );
+      },
+    },
+    {
+      condition: 'Penalize for too many series (>5)',
+      weight: -25,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount > 5;
+      },
+    },
+    {
+      condition: 'Penalize for time series data',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const seriesCol = columns.length > 2 ? columns[1] : undefined;
+    const valueCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'grouped-bar',
+      title: options?.title ?? `Comparison by ${categoryCol}`,
+      data,
+      encoding: {
+        x: { field: categoryCol, type: 'nominal', title: categoryCol },
+        y: { field: valueCol, type: 'quantitative', title: valueCol },
+        color: seriesCol
+          ? { field: seriesCol, type: 'nominal', scale: {} }
+          : { field: categoryCol, type: 'nominal', scale: {} },
+      },
+      config: {
+        categoryField: categoryCol,
+        seriesField: seriesCol,
+        valueField: valueCol,
+        orientation: options?.orientation ?? 'vertical',
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Comparison patterns — for comparing values across categories.
+ */
+
+export { barPattern } from './bar.js';
+export { divergingBarPattern } from './diverging-bar.js';
+export { slopeChartPattern } from './slope-chart.js';
+export { connectedDotPlotPattern } from './connected-dot-plot.js';
+export { bumpChartPattern } from './bump-chart.js';

package/src/patterns/definitions/comparison/lollipop.ts

@@ -0,0 +1,138 @@
+/**
+ * Lollipop Chart — dots on sticks for cleaner ranking.
+ *
+ * A thin line from baseline to a dot at the data value.
+ * Like a bar chart with less ink. Cleaner than bars when
+ * there are many categories (10-40) and the dot emphasis
+ * makes values easier to read than bar endpoints.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const lollipopPattern: VisualizationPattern = {
+  id: 'lollipop',
+  name: 'Lollipop Chart',
+  category: 'comparison',
+  description:
+    'Dots on sticks — a thin line from baseline to a dot at the data value. Like a bar chart with less ink, cleaner for many categories.',
+  bestFor:
+    'Ranking and comparison with many categories (10-40). Cleaner than bars when there are many items. Dot emphasis makes values easier to read.',
+  notFor:
+    'Few categories (<5, just use bar), composition or part-to-whole, time series data.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 60,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category axis' },
+      { type: 'numeric', count: 1, description: 'Value to compare' },
+    ],
+    minCategories: 3,
+    maxCategories: 50,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions lollipop chart',
+      weight: 90,
+      matches: (ctx) => {
+        return /\b(lollipop)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Many-category ranking (10-40 categories) — lollipop is cleaner than bars',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 10 &&
+          ctx.dataShape.categoryCount <= 40 &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Moderate category count with ranking intent',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoryCount >= 8 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          /\b(rank|top|bottom|highest|lowest|most|least|largest|smallest)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Default comparison shape — categories with one numeric value',
+      weight: 30,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Penalize for very few categories — bar chart is simpler',
+      weight: -35,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount < 5;
+      },
+    },
+    {
+      condition: 'Penalize for time series data',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize for two numeric columns — connected dot plot is better',
+      weight: -20,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount === 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'lollipop',
+      title: options?.title ?? `${valueCol} by ${categoryCol}`,
+      data,
+      encoding: {
+        x: {
+          field: categoryCol,
+          type: 'nominal',
+          title: categoryCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: {
+          field: categoryCol,
+          type: 'nominal',
+          scale: {},
+        },
+      },
+      config: {
+        categoryField: categoryCol,
+        valueField: valueCol,
+        orientation: options?.orientation ?? 'horizontal',
+        dotRadius: options?.dotRadius ?? 14,
+        sorted: options?.sorted ?? true,
+        sortBy: options?.sortBy ?? 'value',
+        sortOrder: options?.sortOrder ?? 'descending',
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/slope-chart.ts

@@ -0,0 +1,110 @@
+/**
+ * Slope Chart — two-point comparison.
+ *
+ * Shows change between exactly two time points or conditions.
+ * Far more effective than side-by-side bars for showing direction
+ * and magnitude of change. The slope of each line tells the story.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const slopeChartPattern: VisualizationPattern = {
+  id: 'slope-chart',
+  name: 'Slope Chart',
+  category: 'comparison',
+  description:
+    'Lines connecting two points per category, showing change between two states. The angle of each slope communicates direction and magnitude of change at a glance.',
+  bestFor:
+    'Before/after comparisons, two-year trends, start vs end, A/B test results, policy change impacts.',
+  notFor:
+    'More than 2 time points (use line chart), single time point (use bar), more than 15 categories (too cluttered).',
+
+  dataRequirements: {
+    minRows: 4,
+    maxRows: 60,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category (each gets a slope line)' },
+      { type: 'numeric', count: 1, description: 'Value metric' },
+    ],
+    minCategories: 2,
+    maxCategories: 15,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Exactly 2 time points or conditions — slope chart is the best choice',
+      weight: 80,
+      matches: (ctx) => {
+        // Look for exactly 2 unique values in a date or secondary categorical column
+        const { dateColumnCount, categoricalColumnCount } = ctx.dataShape;
+        if (dateColumnCount >= 1) {
+          const dateCol = ctx.columns.find((c) => c.type === 'date');
+          if (dateCol && dateCol.uniqueCount === 2) return true;
+        }
+        if (categoricalColumnCount >= 2) {
+          // Check if any categorical column has exactly 2 values (e.g., "before"/"after")
+          const secondaryCats = ctx.columns.filter((c) => c.type === 'categorical');
+          if (secondaryCats.some((c) => c.uniqueCount === 2)) return true;
+        }
+        return false;
+      },
+    },
+    {
+      condition: 'Intent mentions before/after, start/end, or two-point comparison',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(before|after|start|end|then|now|initial|final|first|last|two\s*(year|point|period)|vs\.?\s|versus|a\s*\/\s*b|change\s+from|compared\s+to)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Penalize for many time points — use line chart instead',
+      weight: -50,
+      matches: (ctx) => {
+        const dateCols = ctx.columns.filter((c) => c.type === 'date');
+        return dateCols.some((c) => c.uniqueCount > 3);
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+    const periodCol = columns.length > 2 ? columns[1] : columns.length > 1 ? columns[0] : columns[0];
+
+    // Determine the two periods
+    const periods = [...new Set(data.map((d) => d[periodCol]))].slice(0, 2);
+
+    const spec: VisualizationSpec = {
+      pattern: 'slope-chart',
+      title: options?.title ?? `${valueCol}: ${periods[0]} vs ${periods[1]}`,
+      data,
+      encoding: {
+        x: {
+          field: periodCol,
+          type: 'ordinal',
+          title: periodCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: {
+          field: categoryCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        periods,
+        categoryField: categoryCol,
+        valueField: valueCol,
+        timeField: periodCol,
+        showLabels: true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/comparison/waterfall.ts

@@ -0,0 +1,99 @@
+/**
+ * Waterfall Chart — sequential cumulative positive/negative breakdown.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const waterfallPattern: VisualizationPattern = {
+  id: 'waterfall',
+  name: 'Waterfall Chart',
+  category: 'comparison',
+  description:
+    'Floating bars showing how an initial value is affected by sequential positive and negative intermediate values to reach a final total.',
+  bestFor:
+    'Financial breakdowns (revenue → costs → profit), variance analysis (budget → actuals), bridge charts showing contributing factors.',
+  notFor:
+    'Non-sequential data, simple comparison across categories, time series, part-to-whole.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 30,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Step labels' },
+      { type: 'numeric', count: 1, description: 'Values (positive and negative)' },
+    ],
+    minCategories: 3,
+    maxCategories: 20,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions waterfall or bridge chart',
+      weight: 90,
+      matches: (ctx) => {
+        return /\b(waterfall|bridge\s*chart)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Financial breakdown with positive and negative values',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.hasNegativeValues === true &&
+          /\b(breakdown|contribut|step|cumulative|running|bridge|variance|profit|loss|revenue|cost|budget|actual)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Sequential categorical data with mixed positive/negative values',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.hasNegativeValues === true &&
+          !ctx.dataShape.hasTimeSeries
+        );
+      },
+    },
+    {
+      condition: 'Penalize for time series data',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize when no negative values — just use bar chart',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.hasNegativeValues !== true;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'waterfall',
+      title: options?.title ?? `${valueCol} Waterfall`,
+      data,
+      encoding: {
+        x: { field: categoryCol, type: 'nominal', title: categoryCol },
+        y: { field: valueCol, type: 'quantitative', title: valueCol },
+      },
+      config: {
+        categoryField: categoryCol,
+        valueField: valueCol,
+        totalColumns: ['first', 'last'],
+        showConnectors: true,
+      },
+    };
+
+    return spec;
+  },
+};