@outsidedata/dolex 0.1.0

package/src/patterns/definitions/composition/stacked-bar.ts

@@ -0,0 +1,118 @@
+/**
+ * Stacked Bar Chart — part-to-whole over categories.
+ *
+ * Shows both the total and the composition of that total.
+ * Best when you care about both the parts AND the whole.
+ * Supports normalized (100%) mode for pure composition comparison.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const stackedBarPattern: VisualizationPattern = {
+  id: 'stacked-bar',
+  name: 'Stacked Bar Chart',
+  category: 'composition',
+  description:
+    'Bars divided into colored segments, showing both total values and their composition. Each segment represents a subcategory contribution.',
+  bestFor:
+    'Showing how a total breaks down into parts across categories. Revenue by product by region, population by age group by country.',
+  notFor:
+    'Comparing individual segment values across bars (hard to compare non-baseline segments). Use grouped bar for precise comparison of parts.',
+
+  dataRequirements: {
+    minRows: 4,
+    maxRows: 200,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'Category axis and segment grouping' },
+      { type: 'numeric', count: 1, description: 'Value for each segment' },
+    ],
+    minCategories: 2,
+    maxCategories: 15,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Two categorical dimensions + numeric value — natural for stacked bar',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.seriesCount >= 2 &&
+          ctx.dataShape.seriesCount <= 8
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions breakdown, composition, or stacked',
+      weight: 45,
+      matches: (ctx) => {
+        return /\b(breakdown|stacked|composed|composition|made\s+up|constitut|contribution|split\s+by)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Moderate number of series segments (2-8)',
+      weight: 20,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount >= 2 && ctx.dataShape.seriesCount <= 8;
+      },
+    },
+    {
+      condition: 'Penalize for too many series — segments become unreadable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.seriesCount > 8;
+      },
+    },
+    {
+      condition: 'Penalize for single categorical dimension — use regular bar',
+      weight: -20,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount < 2 && ctx.dataShape.seriesCount <= 1;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const seriesCol = columns.length > 1 ? columns[1] : columns[0];
+    const valueCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'stacked-bar',
+      title: options?.title ?? `${valueCol} by ${categoryCol} and ${seriesCol}`,
+      data,
+      encoding: {
+        x: {
+          field: categoryCol,
+          type: 'nominal',
+          title: categoryCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: {
+          field: seriesCol,
+          type: 'nominal',
+          title: seriesCol,
+        },
+      },
+      config: {
+        categoryField: categoryCol,
+        seriesField: seriesCol,
+        valueField: valueCol,
+        sortBy: options?.sortBy,
+        sortOrder: options?.sortOrder ?? 'descending',
+        normalized: options?.normalized ?? false,
+        showLabels: options?.showLabels ?? (data.length <= 40),
+        showTotal: options?.showTotal ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/composition/sunburst.ts

@@ -0,0 +1,114 @@
+/**
+ * Sunburst — nested hierarchical composition.
+ *
+ * Concentric rings showing hierarchy from center outward.
+ * Like a treemap but radial, which can better show the
+ * relationship between levels. Supports interactive drill-down.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const sunburstPattern: VisualizationPattern = {
+  id: 'sunburst',
+  name: 'Sunburst Chart',
+  category: 'composition',
+  description:
+    'Concentric rings where each ring represents a level of hierarchy. Inner rings are parents, outer rings are children. Arc angle encodes proportion.',
+  bestFor:
+    'Multi-level hierarchies (3+ levels): org charts with budget, file system usage, taxonomy breakdowns, nested categories.',
+  notFor:
+    'Flat data (use waffle), two levels only (treemap is simpler), precise value comparison (arc angles are hard to read).',
+
+  dataRequirements: {
+    minRows: 6,
+    maxRows: 300,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'Hierarchy levels (parent, child)' },
+      { type: 'numeric', count: 1, description: 'Size value for arc angle' },
+    ],
+    requiresHierarchy: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Deep hierarchy (3+ categorical levels) — sunburst shows nesting clearly',
+      weight: 80,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasHierarchy &&
+          ctx.dataShape.categoricalColumnCount >= 3 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions sunburst, nested, or multi-level hierarchy',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(sunburst|concentric|nested|multi.level|drill\s*down|tree|taxonomy)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Two-level hierarchy with many items — sunburst is visually appealing',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasHierarchy &&
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.categoryCount >= 5
+        );
+      },
+    },
+    {
+      condition: 'Penalize for flat data — no hierarchy to show',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasHierarchy;
+      },
+    },
+    {
+      condition: 'Penalize for too few items — not enough to fill the rings',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount < 6;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    // Expect columns ordered by hierarchy depth: level0, level1, ..., value
+    const levels = columns.slice(0, -1);
+    const valueCol = columns[columns.length - 1];
+
+    const spec: VisualizationSpec = {
+      pattern: 'sunburst',
+      title: options?.title ?? `Hierarchical composition: ${levels.join(' > ')}`,
+      data,
+      encoding: {
+        angle: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: {
+          field: levels[0],
+          type: 'nominal',
+          title: levels[0],
+        },
+        label: {
+          field: levels[levels.length - 1],
+          type: 'nominal',
+        },
+      },
+      config: {
+        levelFields: levels,
+        valueField: valueCol,
+        innerRadius: options?.innerRadius ?? 40,
+        showLabels: options?.showLabels ?? true,
+        showValues: options?.showValues ?? false,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/composition/treemap.ts

@@ -0,0 +1,118 @@
+/**
+ * Treemap — hierarchical composition.
+ *
+ * Nested rectangles where area encodes value. Excels at showing
+ * hierarchical part-to-whole relationships: how a total breaks
+ * down into groups, which break down into subgroups.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const treemapPattern: VisualizationPattern = {
+  id: 'treemap',
+  name: 'Treemap',
+  category: 'composition',
+  description:
+    'Nested rectangles where area represents value. Shows hierarchical composition: total → groups → subgroups. Space-efficient for many items.',
+  bestFor:
+    'Hierarchical data with size values: file system usage, organizational budgets, market cap by sector and company, product category revenue.',
+  notFor:
+    'Non-hierarchical flat data (use waffle), comparing exact values (hard to compare rectangle areas), time series.',
+
+  dataRequirements: {
+    minRows: 4,
+    maxRows: 500,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category labels (or hierarchical groups)' },
+      { type: 'numeric', count: 1, description: 'Size value for rectangle area' },
+    ],
+    requiresHierarchy: false, // Works with flat data too, just better with hierarchy
+  },
+
+  selectionRules: [
+    {
+      condition: 'Hierarchical data — treemap is the natural choice',
+      weight: 80,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasHierarchy &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 2
+        );
+      },
+    },
+    {
+      condition: 'Many categories (10+) with composition intent — treemap handles scale',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoryCount >= 10 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          /\b(compos|proportion|share|breakdown|makeup|size|biggest|largest)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions treemap or hierarchical visualization',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(treemap|hierarch|nested|drill\s*down|parent|child|sub\s*category)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Multiple categorical dimensions for nesting',
+      weight: 40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount >= 2 && ctx.dataShape.numericColumnCount >= 1;
+      },
+    },
+    {
+      condition: 'Penalize for very few categories — waffle or bar is clearer',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount < 5 && !ctx.dataShape.hasHierarchy;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const parentCol = columns.length > 2 ? columns[0] : undefined;
+    const childCol = columns.length > 2 ? columns[1] : undefined;
+    const sizeCol = columns.length > 2 ? columns[2] : valueCol;
+
+    const spec: VisualizationSpec = {
+      pattern: 'treemap',
+      title: options?.title ?? `${valueCol} composition${parentCol ? ` (${parentCol} > ${childCol})` : ''}`,
+      data,
+      encoding: {
+        size: {
+          field: sizeCol,
+          type: 'quantitative',
+          title: sizeCol,
+        },
+        color: {
+          field: parentCol ?? categoryCol,
+          type: 'nominal',
+          title: parentCol ?? categoryCol,
+        },
+        label: {
+          field: childCol ?? categoryCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        categoryField: categoryCol,
+        valueField: sizeCol,
+        parentField: parentCol ?? null,
+        childField: childCol ?? null,
+        showLabels: options?.showLabels ?? true,
+        padding: options?.padding ?? 2,
+        borderWidth: options?.borderWidth ?? 1,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/composition/waffle.ts

@@ -0,0 +1,127 @@
+/**
+ * Waffle Chart — part-to-whole, better than pie.
+ *
+ * A grid of small squares where each square represents a unit
+ * (usually 1%). More accurate than pie charts because humans
+ * are better at counting squares than estimating angles.
+ * The go-to replacement for pie charts.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const wafflePattern: VisualizationPattern = {
+  id: 'waffle',
+  name: 'Waffle Chart',
+  category: 'composition',
+  description:
+    'A 10x10 grid of colored squares, each representing 1% of the total. More perceptually accurate than pie charts for showing proportions.',
+  bestFor:
+    'Part-to-whole comparisons with 2-8 categories. Percentage breakdowns. Survey results. Market share. Election results.',
+  notFor:
+    'Many categories over 8 (too many colors). Very small differences (hard to see 1% vs 2%). Non-percentage data (requires total context).',
+
+  dataRequirements: {
+    minRows: 2,
+    maxRows: 8,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Category labels' },
+      { type: 'numeric', count: 1, description: 'Value (will be converted to proportions)' },
+    ],
+    minCategories: 2,
+    maxCategories: 8,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Part-to-whole with few categories — waffle beats pie every time',
+      weight: 75,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoryCount >= 2 &&
+          ctx.dataShape.categoryCount <= 8 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions percentage, proportion, or share',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(percent|proportion|share|part.of|makeup|pie|waffle|how\s+much\s+of)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Very few categories (2-4) — waffle is clearest',
+      weight: 30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount >= 2 && ctx.dataShape.categoryCount <= 4;
+      },
+    },
+    {
+      condition: 'Penalize for too many categories — colors become indistinguishable',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount > 8;
+      },
+    },
+    {
+      condition: 'Penalize when data has time dimension — composition over time is better as stacked',
+      weight: -20,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize for hierarchical data — treemap is better',
+      weight: -25,
+      matches: (ctx) => {
+        return ctx.dataShape.hasHierarchy;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    // Calculate percentages
+    const total = data.reduce((sum, row) => sum + (Number(row[valueCol]) || 0), 0);
+    const waffleData = data.map((row) => ({
+      ...row,
+      _percentage: total > 0 ? ((Number(row[valueCol]) || 0) / total) * 100 : 0,
+      _squares: total > 0 ? Math.round(((Number(row[valueCol]) || 0) / total) * 100) : 0,
+    }));
+
+    // Ensure squares sum to 100 by adjusting the largest category
+    const totalSquares = waffleData.reduce((sum, row) => sum + row._squares, 0);
+    if (totalSquares !== 100 && waffleData.length > 0) {
+      const sorted = [...waffleData].sort((a, b) => b._percentage - a._percentage);
+      sorted[0]._squares += 100 - totalSquares;
+    }
+
+    const spec: VisualizationSpec = {
+      pattern: 'waffle',
+      title: options?.title ?? `${valueCol} composition`,
+      data: waffleData,
+      encoding: {
+        color: {
+          field: categoryCol,
+          type: 'nominal',
+          title: categoryCol,
+        },
+      },
+      config: {
+        categoryField: categoryCol,
+        valueField: valueCol,
+        gridSize: options?.gridSize ?? 10,
+        squareSize: options?.squareSize ?? 20,
+        gap: options?.gap ?? 2,
+        total,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/distribution/beeswarm.ts

@@ -0,0 +1,115 @@
+/**
+ * Beeswarm Plot — individual points, avoids overplotting.
+ *
+ * Shows every data point while using force-directed positioning
+ * to prevent overlap. Reveals distribution shape AND individual
+ * values, making outliers and clusters immediately visible.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const beeswarmPattern: VisualizationPattern = {
+  id: 'beeswarm',
+  name: 'Beeswarm Plot',
+  category: 'distribution',
+  description:
+    'Dots arranged along a single axis, jittered to avoid overlap. Shows individual data points while revealing distribution shape, clusters, and outliers.',
+  bestFor:
+    'Medium-sized datasets (20-500 rows) where individual points matter. Finding outliers, clusters, and gaps. Comparing distributions across a few groups.',
+  notFor:
+    'Very large datasets over 1000 points (too slow/cluttered), very small datasets under 10 (use strip plot).',
+
+  dataRequirements: {
+    minRows: 10,
+    maxRows: 500,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Value to distribute points along' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent mentions outliers — beeswarm makes every point visible',
+      weight: 80,
+      matches: (ctx) => {
+        return /\b(outlier|individual|point|each|every|anomal|extreme|unusual)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Medium dataset size (20-500) — sweet spot for beeswarm',
+      weight: 50,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount >= 20 && ctx.dataShape.rowCount <= 500;
+      },
+    },
+    {
+      condition: 'Distribution with a grouping column (1-5 groups)',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 2 &&
+          ctx.dataShape.categoryCount <= 5
+        );
+      },
+    },
+    {
+      condition: 'Penalize for very large datasets — too many points',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 500;
+      },
+    },
+    {
+      condition: 'Penalize for time series — not the right chart type',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'beeswarm',
+      title: options?.title ?? `Distribution of ${valueCol}${groupCol ? ` by ${groupCol}` : ''}`,
+      data,
+      encoding: {
+        x: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        y: groupCol
+          ? {
+              field: groupCol,
+              type: 'nominal',
+              title: groupCol,
+            }
+          : undefined,
+        color: groupCol
+          ? {
+              field: groupCol,
+              type: 'nominal',
+            }
+          : {
+              field: valueCol,
+              type: 'quantitative',
+            },
+      },
+      config: {
+        valueField: valueCol,
+        categoryField: groupCol ?? null,
+        dotRadius: options?.dotRadius ?? 4,
+        showMedianLine: options?.showMedianLine ?? true,
+        opacity: options?.opacity ?? 0.7,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/distribution/box-plot.ts

@@ -0,0 +1,115 @@
+/**
+ * Box Plot — compact distribution summary.
+ *
+ * Shows quartiles, median, whiskers, and outliers for numeric data
+ * across groups. The fundamental distribution summary chart.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const boxPlotPattern: VisualizationPattern = {
+  id: 'box-plot',
+  name: 'Box Plot',
+  category: 'distribution',
+  description:
+    'Quartile summary showing median, Q1/Q3 box, whiskers, and outliers. Compact distribution comparison across groups.',
+  bestFor:
+    'Comparing distributions across 2-12 groups with a compact summary. Salary by department, test scores by school, response times by endpoint.',
+  notFor:
+    'Single group with no comparison (use histogram). Showing distribution shape detail (use violin). Very few data points per group under 5.',
+
+  dataRequirements: {
+    minRows: 10,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Value to analyze' },
+      { type: 'categorical', count: 1, description: 'Group variable (2-12 groups)' },
+    ],
+    minCategories: 2,
+    maxCategories: 20,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Numeric values grouped by categories — box plot summarizes distribution',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 2 &&
+          ctx.dataShape.categoryCount <= 12 &&
+          ctx.dataShape.rowCount >= 10
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions box plot, quartile, outlier, or compact distribution summary',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(box\s*plot|boxplot|quartile|outlier|whisker|iqr|interquartile)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Medium-sized groups with enough data for meaningful quartiles',
+      weight: 25,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoryCount === 0) return false;
+        const avgPerGroup = ctx.dataShape.rowCount / ctx.dataShape.categoryCount;
+        return avgPerGroup >= 5 && avgPerGroup <= 500;
+      },
+    },
+    {
+      condition: 'Penalize for single group — use histogram instead',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount === 0 || ctx.dataShape.categoryCount < 2;
+      },
+    },
+    {
+      condition: 'Penalize for too many groups — consider ridgeline or violin',
+      weight: -25,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount > 12;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'box-plot',
+      title: options?.title ?? `${valueCol} by ${groupCol}`,
+      data,
+      encoding: {
+        x: {
+          field: groupCol,
+          type: 'nominal',
+          title: groupCol,
+        },
+        y: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        color: {
+          field: groupCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        valueField: valueCol,
+        categoryField: groupCol,
+        orientation: options?.orientation ?? 'vertical',
+        sortBy: options?.sortBy ?? 'value',
+        sortOrder: options?.sortOrder ?? 'descending',
+        whiskerType: options?.whiskerType ?? 'iqr',
+        showOutliers: options?.showOutliers ?? true,
+        showMean: options?.showMean ?? false,
+      },
+    };
+
+    return spec;
+  },
+};