@outsidedata/dolex 0.1.0

package/src/patterns/definitions/flow/alluvial.ts

@@ -0,0 +1,124 @@
+/**
+ * Alluvial Diagram — categorical flow over time.
+ *
+ * Like a Sankey but with a temporal dimension. Shows how
+ * entities move between categorical states across ordered
+ * stages (often time periods). The flows between columns
+ * reveal transitions, retention, and churn.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const alluvialPattern: VisualizationPattern = {
+  id: 'alluvial',
+  name: 'Alluvial Diagram',
+  category: 'flow',
+  description:
+    'Flows between categorical columns ordered left-to-right (often time). Shows how entities transition between states across stages: retention, churn, and movement.',
+  bestFor:
+    'State transitions over time: customer segments changing over quarters, voting patterns across elections, career paths, cohort movement.',
+  notFor:
+    'Non-temporal flows (use Sankey), simple composition (use stacked bar), very many categories per stage (too many flows).',
+
+  dataRequirements: {
+    minRows: 5,
+    maxRows: 500,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'States at different stages/time periods' },
+      { type: 'numeric', count: 1, description: 'Flow quantity between states' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Temporal categorical transitions — alluvial shows state changes over time',
+      weight: 80,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions transitions, movement, or changes over stages',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(transition|movement|churn|retention|cohort|switch|migrat|convert|stage|phase|path|alluvial|from.+to.+over)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Multiple categorical columns with an ordering — natural for alluvial',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 3 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Penalize when not temporal — use Sankey for static flows',
+      weight: -20,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries && ctx.dataShape.dateColumnCount === 0;
+      },
+    },
+    {
+      condition: 'Penalize for too many categories per stage — flows become unreadable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount > 15;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const stageColumns = columns.filter((_, i) => i < columns.length - 1);
+    const valueCol = columns[columns.length - 1];
+
+    // If only two columns, treat first as combined "source_stage" info
+    const stages = stageColumns.length >= 2
+      ? stageColumns
+      : [columns[0], columns.length > 1 ? columns[1] : columns[0]];
+
+    const spec: VisualizationSpec = {
+      pattern: 'alluvial',
+      title: options?.title ?? `Flow across ${stages.join(' → ')}`,
+      data,
+      encoding: {
+        stages: stages.map((col) => ({
+          field: col,
+          type: 'nominal' as const,
+          title: col,
+        })),
+        size: {
+          field: valueCol,
+          type: 'quantitative' as const,
+          title: valueCol,
+          range: [1, 50] as [number, number],
+        },
+        color: {
+          field: stages[0],
+          type: 'nominal',
+          title: stages[0],
+        },
+      },
+      config: {
+        stageFields: stages,
+        valueField: valueCol,
+        nodeWidth: options?.nodeWidth ?? 20,
+        nodePadding: options?.nodePadding ?? 10,
+        flowOpacity: options?.flowOpacity ?? 0.4,
+        showLabels: options?.showLabels ?? true,
+        showValues: options?.showValues ?? false,
+        colorBy: options?.colorBy ?? 'source',
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/flow/chord.ts

@@ -0,0 +1,132 @@
+/**
+ * Chord Diagram — relationships between groups.
+ *
+ * A circular layout where arcs represent groups and chords
+ * represent flows between them. The width of each chord
+ * encodes the magnitude of the relationship. Shows
+ * bidirectional flows and relative importance.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const chordPattern: VisualizationPattern = {
+  id: 'chord',
+  name: 'Chord Diagram',
+  category: 'flow',
+  description:
+    'Circular layout with arcs for groups and curved chords connecting them. Chord width represents flow magnitude. Shows mutual relationships and overall connectivity.',
+  bestFor:
+    'Bidirectional flows between groups: trade between countries, migration between regions, collaboration between departments, phone calls between cities.',
+  notFor:
+    'Unidirectional flow (use Sankey), many groups over 12 (too dense), non-relational data.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 100,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'Source and target groups (often the same set)' },
+      { type: 'numeric', count: 1, description: 'Flow/relationship magnitude' },
+    ],
+    minCategories: 3,
+    maxCategories: 12,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Bidirectional relationships between groups — chord shows mutual flows',
+      weight: 80,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoricalColumnCount < 2 || ctx.dataShape.numericColumnCount < 1) return false;
+        // Check if source and target draw from the same set of values
+        const cats = ctx.columns.filter((c) => c.type === 'categorical');
+        if (cats.length < 2) return false;
+        const sourceVals = new Set(ctx.data.map((d) => d[cats[0].name]));
+        const targetVals = new Set(ctx.data.map((d) => d[cats[1].name]));
+        let overlap = 0;
+        for (const v of sourceVals) {
+          if (targetVals.has(v)) overlap++;
+        }
+        // If significant overlap, it's likely bidirectional group-to-group data
+        return overlap >= Math.min(sourceVals.size, targetVals.size) * 0.5;
+      },
+    },
+    {
+      condition: 'Intent mentions chord, mutual, bidirectional, or between groups',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(chord|mutual|bidirectional|between\s+groups|inter.*(department|region|country)|trade\s+between|migration\s+between|collaborat)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Moderate number of groups (3-12) — sweet spot for chord',
+      weight: 30,
+      matches: (ctx) => {
+        const allCategories = new Set([
+          ...ctx.data.map((d) => {
+            const cats = ctx.columns.filter((c) => c.type === 'categorical');
+            return cats.length > 0 ? d[cats[0].name] : null;
+          }),
+          ...ctx.data.map((d) => {
+            const cats = ctx.columns.filter((c) => c.type === 'categorical');
+            return cats.length > 1 ? d[cats[1].name] : null;
+          }),
+        ]);
+        return allCategories.size >= 3 && allCategories.size <= 12;
+      },
+    },
+    {
+      condition: 'Penalize for clearly unidirectional flow — use Sankey instead',
+      weight: -20,
+      matches: (ctx) => {
+        return /\b(funnel|pipeline|step|stage|conversion)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Penalize for single categorical column — no group-to-group relationship',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount < 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const sourceCol = columns[0];
+    const targetCol = 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: 'chord',
+      title: options?.title ?? `Relationships between ${sourceCol} groups`,
+      data,
+      encoding: {
+        source: {
+          field: sourceCol,
+          type: 'nominal',
+        },
+        target: {
+          field: targetCol,
+          type: 'nominal',
+        },
+        size: {
+          field: valueCol,
+          type: 'quantitative' as const,
+          title: valueCol,
+          range: [1, 30] as [number, number],
+        },
+      },
+      config: {
+        sourceField: sourceCol,
+        targetField: targetCol,
+        valueField: valueCol,
+        padAngle: options?.padAngle ?? 0.05,
+        ribbonOpacity: options?.ribbonOpacity ?? 0.5,
+        showLabels: options?.showLabels ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/flow/funnel.ts

@@ -0,0 +1,75 @@
+/**
+ * Funnel Chart — sequential conversion/dropout visualization.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const funnelPattern: VisualizationPattern = {
+  id: 'funnel',
+  name: 'Funnel Chart',
+  category: 'flow',
+  description: 'Tapered bars showing progressive narrowing through sequential stages — conversions, pipelines, dropout rates.',
+  bestFor: 'Conversion funnels, sales pipelines, hiring funnels, dropout analysis. 3-8 sequential stages with decreasing values.',
+  notFor: 'Non-sequential data, bidirectional flows (use Sankey), data without progressive reduction.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 8,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Stage names (ordered)' },
+      { type: 'numeric', count: 1, description: 'Count/value per stage' },
+    ],
+    minCategories: 3,
+    maxCategories: 8,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions funnel or conversion',
+      weight: 90,
+      matches: (ctx) => /\b(funnel|conversion\s*(rate|funnel)?|pipeline|dropout|drop.?off)\b/i.test(ctx.intent),
+    },
+    {
+      condition: 'Sequential stages with decreasing values',
+      weight: 50,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount >= 1 &&
+               ctx.dataShape.numericColumnCount >= 1 &&
+               ctx.dataShape.categoryCount >= 3 &&
+               ctx.dataShape.categoryCount <= 8;
+      },
+    },
+    {
+      condition: 'Penalize for too many stages',
+      weight: -40,
+      matches: (ctx) => ctx.dataShape.categoryCount > 8,
+    },
+    {
+      condition: 'Penalize for time series data',
+      weight: -30,
+      matches: (ctx) => ctx.dataShape.hasTimeSeries,
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const categoryCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+
+    return {
+      pattern: 'funnel',
+      title: options?.title ?? 'Conversion Funnel',
+      data,
+      encoding: {
+        x: { field: valueCol, type: 'quantitative' },
+        y: { field: categoryCol, type: 'nominal' },
+        color: { field: categoryCol, type: 'nominal' },
+      },
+      config: {
+        categoryField: categoryCol,
+        valueField: valueCol,
+        showConversionRates: options?.showConversionRates ?? true,
+        style: options?.style ?? 'tapered',
+      },
+    };
+  },
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Flow patterns — for showing movement, transitions, and relationships between states.
+ */
+
+export { sankeyPattern } from './sankey.js';
+export { alluvialPattern } from './alluvial.js';
+export { chordPattern } from './chord.js';

package/src/patterns/definitions/flow/sankey.ts

@@ -0,0 +1,140 @@
+/**
+ * Sankey Diagram — flow between states.
+ *
+ * Shows quantities flowing from sources to destinations through
+ * intermediate nodes. Width of each flow encodes magnitude.
+ * Ideal for energy flows, budget allocation, user conversion funnels.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const sankeyPattern: VisualizationPattern = {
+  id: 'sankey',
+  name: 'Sankey Diagram',
+  category: 'flow',
+  description:
+    'Nodes connected by flows whose width represents quantity. Shows how a total distributes through a system: sources, intermediate steps, and destinations.',
+  bestFor:
+    'Energy flow, budget allocation, user journey funnels, import/export trade, material flow, conversion pipelines.',
+  notFor:
+    'Simple composition (use stacked bar or waffle), non-flow data, cyclical flows (Sankey requires directed acyclic graph).',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 200,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'Source and target nodes' },
+      { type: 'numeric', count: 1, description: 'Flow quantity' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Source-target-value structure — Sankey is the natural choice',
+      weight: 85,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          /\b(from|source|origin)\b/i.test(
+            ctx.columns
+              .filter((c) => c.type === 'categorical')
+              .map((c) => c.name)
+              .join(' ')
+          )
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions flow, Sankey, funnel, or path',
+      weight: 70,
+      matches: (ctx) => {
+        return /\b(flow|sankey|funnel|path|journey|pipeline|from\s+.+\s+to|source.+target|allocation|distribut.+through)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Two categorical columns suggesting from/to relationship',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Penalize for single categorical column — no from/to relationship',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount < 2;
+      },
+    },
+    {
+      condition: 'Penalize for time series — alluvial is better for temporal flows',
+      weight: -20,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const sourceCol = columns[0];
+    const targetCol = columns.length > 1 ? columns[1] : columns[0];
+    const valueCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    // Extract unique nodes
+    const nodes = [
+      ...new Set([
+        ...data.map((d) => d[sourceCol]),
+        ...data.map((d) => d[targetCol]),
+      ]),
+    ].map((name) => ({ name: String(name) }));
+
+    // Build links
+    const links = data.map((d) => ({
+      source: String(d[sourceCol]),
+      target: String(d[targetCol]),
+      value: Number(d[valueCol]) || 0,
+    }));
+
+    const spec: VisualizationSpec = {
+      pattern: 'sankey',
+      title: options?.title ?? `Flow from ${sourceCol} to ${targetCol}`,
+      data,
+      encoding: {
+        source: {
+          field: sourceCol,
+          type: 'nominal',
+        },
+        target: {
+          field: targetCol,
+          type: 'nominal',
+        },
+        size: {
+          field: valueCol,
+          type: 'quantitative' as const,
+          title: valueCol,
+          range: [1, 50] as [number, number],
+        },
+      },
+      config: {
+        sourceField: sourceCol,
+        targetField: targetCol,
+        valueField: valueCol,
+        nodes,
+        links,
+        nodeWidth: options?.nodeWidth ?? 20,
+        nodePadding: options?.nodePadding ?? 10,
+        nodeAlign: options?.nodeAlign ?? 'justify',
+        linkOpacity: options?.linkOpacity ?? 0.5,
+        showLabels: options?.showLabels ?? true,
+        showValues: options?.showValues ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/geo/choropleth.ts

@@ -0,0 +1,82 @@
+import type { VisualizationPattern } from '../../../types.js';
+import { applyGeoScope, buildGeoSpecConfig } from '../../../renderers/d3/geo/geo-scope.js';
+
+export const choroplethPattern: VisualizationPattern = {
+  id: 'choropleth',
+  name: 'Choropleth Map',
+  category: 'geo',
+  description:
+    'Geographic regions shaded by data values. Darker colors indicate higher values, instantly revealing spatial patterns.',
+  bestFor:
+    'Country-level data: GDP, population, election results, disease rates, temperature. Any numeric metric with a geographic key.',
+  notFor:
+    'Point data (use proportional symbol), routes/trajectories, non-geographic categories, data with no geographic key.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 300,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Geographic identifier (country name, ISO code, state)' },
+      { type: 'numeric', count: 1, description: 'Value to color-encode' },
+    ],
+    minCategories: 3,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions map or geographic visualization',
+      weight: 85,
+      matches: (ctx) => {
+        return /\b(map|geographic|choropleth|country|countries|state\s+map|province|spatial|world\s+map|heat\s*map.*countr)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Data has a column that looks like country/state names or codes',
+      weight: 50,
+      matches: (ctx) => {
+        const catCols = ctx.columns.filter((c) => c.type === 'categorical');
+        return catCols.some((col) => {
+          const samples = col.sampleValues.map((v) => v.toLowerCase());
+          const geoIndicators = ['usa', 'china', 'india', 'uk', 'france', 'germany', 'brazil', 'japan', 'california', 'texas', 'new york'];
+          return samples.some((s) => geoIndicators.some((g) => s.includes(g)));
+        });
+      },
+    },
+    {
+      condition: 'Penalize when no numeric column for coloring',
+      weight: -40,
+      matches: (ctx) => ctx.dataShape.numericColumnCount === 0,
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const geoCol = columns[0];
+    const valueCol = columns.length > 1 ? columns[1] : columns[0];
+    const geo = applyGeoScope(data, geoCol, options);
+    const regionLabel = geo.regionConfig?.subdivisionType ?? (geo.isUs ? 'State' : 'Region');
+
+    return {
+      pattern: 'choropleth',
+      title: options?.title ?? `${valueCol} by ${regionLabel}`,
+      data: geo.data,
+      encoding: {
+        geo: { field: geoCol, type: 'nominal' },
+        color: {
+          field: valueCol,
+          type: 'quantitative',
+          scale: options?.colorScale,
+        },
+      },
+      config: {
+        geoField: geoCol,
+        valueField: valueCol,
+        mapType: geo.mapType,
+        projection: geo.projection,
+        colorScheme: options?.colorScheme ?? 'blues',
+        ...buildGeoSpecConfig(geo),
+      },
+    };
+  },
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Geo pattern definitions — choropleth, proportional-symbol.
+ */
+
+export { choroplethPattern } from './choropleth.js';
+export { proportionalSymbolPattern } from './proportional-symbol.js';

package/src/patterns/definitions/geo/proportional-symbol.ts

@@ -0,0 +1,94 @@
+/**
+ * Proportional Symbol Map — sized circles on a geographic base.
+ *
+ * Places circles at geographic locations, sized by a data value.
+ * Better than choropleth for point data (cities, facilities) and
+ * when you need to show magnitude without area-distortion bias.
+ */
+
+import type { VisualizationPattern } from '../../../types.js';
+import { applyGeoScope, buildGeoSpecConfig } from '../../../renderers/d3/geo/geo-scope.js';
+
+export const proportionalSymbolPattern: VisualizationPattern = {
+  id: 'proportional-symbol',
+  name: 'Proportional Symbol Map',
+  category: 'geo',
+  description:
+    'Circles placed on a map, sized proportionally to data values. Avoids the area-distortion bias of choropleths.',
+  bestFor:
+    'City-level data: population, revenue by location, earthquake magnitudes, facility capacity. Point-based metrics.',
+  notFor:
+    'Area-based metrics (use choropleth), data without lat/lon or city names, non-geographic data.',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 500,
+    requiredColumns: [
+      { type: 'categorical', count: 1, description: 'Location identifier (city, facility name)' },
+      { type: 'numeric', count: 1, description: 'Value for circle sizing' },
+    ],
+    minCategories: 3,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent mentions cities, points on map, or bubble map',
+      weight: 80,
+      matches: (ctx) => {
+        return /\b(bubble\s*map|proportional|symbol\s*map|city|cities|point|points\s+on\s+map|location|locations)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Data has lat/lon or coordinate columns',
+      weight: 60,
+      matches: (ctx) => {
+        return ctx.columns.some((col) =>
+          /\b(lat|latitude|lon|longitude|lng|coord)/i.test(col.name)
+        );
+      },
+    },
+    {
+      condition: 'Penalize when no numeric column for sizing',
+      weight: -40,
+      matches: (ctx) => ctx.dataShape.numericColumnCount === 0,
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const locationCol = columns[0];
+    const latCol = columns.find((c) => /lat/i.test(c)) ?? null;
+    const lonCol = columns.find((c) => /lon|lng/i.test(c)) ?? null;
+    const coordinateCols = new Set([latCol, lonCol].filter(Boolean));
+    const valueCol = columns.find((c, i) => i > 0 && !coordinateCols.has(c)) ?? columns[1] ?? columns[0];
+    const geo = applyGeoScope(data, locationCol, options);
+
+    return {
+      pattern: 'proportional-symbol',
+      title: options?.title ?? `${valueCol} by Location`,
+      data: geo.data,
+      encoding: {
+        geo: { field: locationCol, type: 'nominal' },
+        size: {
+          field: valueCol,
+          type: 'quantitative',
+          range: options?.sizeRange ?? [4, 40],
+        },
+        color: options?.colorField
+          ? { field: options.colorField, type: 'nominal' }
+          : undefined,
+      },
+      config: {
+        locationField: locationCol,
+        valueField: valueCol,
+        latField: latCol,
+        lonField: lonCol,
+        mapType: geo.mapType,
+        projection: geo.projection,
+        opacity: options?.opacity ?? 0.7,
+        ...buildGeoSpecConfig(geo),
+      },
+    };
+  },
+};